session held at EntwicklerCamp 2017

1. Entwicklercamp 2017
C / C++ für Notes & Domino Entwickler
Ulrich Krause
27. – 29..03.2017
Maritim Hotel, Gelsenkirchen

2. Über: Ulrich Krause
Lotus Notes und Domino seit 1993
Entwickler
Administrator
IBM Champion 2010 – 2016
OpenNTF Contributor
Entwickler bei midpoints GmbH

3. 1996 – Erste „Entwicklerversion“

4. “ A word of warning. This is difficult, horrible,
tedious frustrating error prone work that WILL
take far more time than you think, and WILL
come back and bite you in the .. leg .. ”
( Bill Buchan )

5. C API
LSX ToolkitC++ API
JAVA 2
CAPI
LS 2 CAPI
Möglichkeiten

6. Was können wir NICHT mit der API?
 Modifikationen an der Software selbst. Z.B.,
Entfernen von Menüpunkten oder
Funktionen.
- Das Hinzufügen ist über Client Menu Addins
möglich
 Ändern des Aktivitätenprotokolls
 Ändern der ECL eines Users
 Zugriff auf DAOS.
Was können wir mit der API?
 Erstellen und Löschen von Datenbanken.
 Erstellen, Bearbeiten und Löschen von
Dokumenten oder Designelementen.
 Erstellen, Bearbeiten, und Löschen von Items
in einem Dokument.
 Erstellen, Bearbeiten, Löschen und
Verwenden von Ansichtenindexen.
 Erstellen, Bearbeiten und Löschen von ACL
Einträgen
 Backup und Restore von Datenbanken
 Erstellen und Bearbeiten von
Kalendereinträgen
 Verwaltung des IDVault
 Arbeiten mit Server Statistiken

7. Wo operiert die API?
Back-EndFront-End

8. NSF /NTF Container )
Betriebssystem
Notes Object Interface (NOI)
Lotus Script
C++ API
Notes Core ( C API )
Visual Basic (COM)JAVA
JNI
Zugriffe

9. Jede Art von Anwendung.
z.B. NotesPeek, DAOS
Estimator.
Erlauben das Ausführen
von Code vor und / oder
nach einem Ereignis auf
dem Server.
z.B. Virenscanner.
Anwendungen im Kontext des
Servers. Lassen sich über LOAD
…, TELL … und QUIT steuern
z.B. amgr, router …
Wie Extension Manager, es
wird aber auf Events im
Kontext des HTTP stack
reagiert.
z.B. midpoints DSAPI
Authenticator
Arten von Anwendungen

10. Welche Werkzeuge brauche ich?
 https://www-
01.ibm.com/marketing/iwm/tnd/nochargesearch.jsp?cat=&q
0=&pf=&k=ALL&pn=&pid=&rs=&S_TACT=104CBW71&status=
Active&S_CMP=&b=&sr=1&q=C+API+Domino&ibm-
search.x=0&ibm-search.y=0
 http://www-
01.ibm.com/support/docview.ws
s?uid=swg24005686

11. Welche Werkzeuge brauche ich?
IBM Domino or IBM Notes 9.0.1 for Windows. All Windows platforms
supported by Domino 9.0.1 are also supported by this toolkit.
Microsoft Visual Studio 2010 SP1.
Visual Studio (Express) 2005 & 2008 funktionieren auch mit 9.0.1 (nicht
supported )
Novell SUSE Linux Enterprise Server (SLES) 10 x86 (32-bit)
32 Bit IBM Domino 8.5 for Linux on xSeries
GNU Compiler Collection (gcc/g++) version 4.1.0
Novell SUSE Linux Enterprise Server (SLES) 11 x86_64 (64 bit)
64 Bit IBM Domino 9.0.1 for
GNU Compiler Collection (gcc/g++) version 4.3.x
Macintosh OS X 10.5.5 or late

12. Alternative IDE
https://code.visualstudio.com/

13. Standalone Compiler für Windows
http://landinghub.visualstudio.com/visual-cpp-build-tools

14. http://www.boost.org/
https://theboostcpplibraries.com/

15. Warum Boost ?
Beispiel: Es gibt kein trim() in C /C++ ( std::string )
#include <boost/algorithm/string.hpp>
string s = „ midpoints „;
boost::trim_left(s);
boost::trim_right(s);
boost::trim(s);
boost::copy_trim_xxx(s);
boost::trim_right_if(str, boost::is_any_of("0"));

16. Boost.Build makes it easy to build C++ projects,
everywhere.
You name your executables and libraries and list
their sources. Boost.Build takes care about compiling
your sources with right options, creating static and
shared libraries, making executables, and other
chores — whether you're using gcc, msvc, or a dozen
more supported C++ compilers — on Windows, OSX,
Linux and commercial UNIX systems.
http://www.boost.org/build/
CMake (cross-platform make) ist ein
plattformunabhängiges Programmierwerkzeug
für die Entwicklung und Erstellung von Software.
https://cmake.org/

17. Codedichte, Kosten, Schwierigkeitsgrade
 Es existieren sehr wenige Beispiele für
C / C++ *. Die Anzahl der Entwickler ist
überschaubar. Es wird Spezialwissen
vorausgesetzt. Dementsprechend ist die
Erstellung von Programmen aufwändig
und teuer.
C
C++
LS 2 CAPI
 Beispiele für LS2CAPI sind reichlich
vorhanden. Die Anpassung oder das
Erstellen von Code auf Basis von
LS2CAPI erfordert fundierte Kenntnisse.
 LotusScript und Java haben eine
breite Codebasis. Beispiele für fast alle
Aufgabenstellungen sind leicht zu
finden.Die Erstellung / Anpassung von
Code ist einfach und preiswert
Lotus Script, Java
JAVA 2 CAPI
* Im Kontext von IBM Notes & Domino

18. Grundlagen

22. C/C++: Additional Include Directories

23. C/C++: Preprocessor Definitions

24. C/C++: Code Generation

25. Handles
#if defined (_MSC_VER) && !defined(ND64)
#pragma pack(push, 1)
#endif
#include <global.h>
#include <osenv.h>
#include <oserr.h>
#include <addin.h>
#include <nsfdb.h>
#if defined (_MSC_VER) && !defined (ND64)
#pragma pack(pop)
#endif

26. #if defined (W64)
#define HANDLE DHANDLE
#undef NOTEHANDLE
#define NOTEHANDLE DHANDLE
#else // 32Bit
#define DHANDLE HANDLE
#undef NOTEHANDLE
#define NOTEHANDLE HANDLE
#endif

27. Windows vs. Linux
#if defined(UNIX)
#include <sys/stat.h>
#include <sys/types.h>
#define DIR_SEPARATOR '/'
#define _vsnprintf vsnprintf
#define _snprintf snprintf
#define strcpy_s(t, l, s) strcpy(t, s)
#define sprintf_s(t, l, f, ...) sprintf(t, f, __VA_ARGS__)
#define strcat_s(t, l, s) strcat(t, s)
#define strncpy_s(t, l, s, n) strncpy(t, s, n)
#define strtok_s(s, t, c) strtok(s, t)
#define memcpy_s(t, m, s, l) memcpy(t, s, l)
#elif defined(W32)
#pragma warning(disable: 4996)
#define strdup(str) _strdup(str)
#define DIR_SEPARATOR ''
#define popen _popen
#define pclose _pclose
#endif

28. Linker: Additional Library Directories

29. Linker: Additional Dependencies

30. Beispiel: C API

31. Beispiel: DLL mit C API

32. Beispiel: C++ API

33. C++ API (cont.)

34. C++ API (cont.)

35. C++ API (cont.)

36. C++ API (cont.)
Starten im Notes Programmverzeichnis
 ec10-dbtitle-cpp.exe
 Benötigt eine zusätzliche LCPPN.DLL (~2.5 MB), die auf jeden
Rechner ausgerollt werden muss, auf dem das Programm laufen
soll

37.  The most recent version of the C++ API
toolkit for Notes & Domino is 8.0.2 IF3.
 While this version of the toolkit should work
with newer versions of Notes and Domino,
such as 8.5.3 and 9.0.1, any incompatibilities,
limitations or defects in this toolkit will not
be addressed.
 No Linux 64.

38. Eigener C++ Wrapper
 Klassencode mit Konstruktor, Destruktor und
Errorhandling.
 Einfache Verwendung im Code.

39. Lohnt sich das?
Wenn man „nur mal so“ mit der API spielen möchte, dann
lohnt sich der Aufwand sicherlich nicht.
Im professionellen Einsatz ist der Wrapper sinnvoll.
 Er nimmt Entwicklern ( alt und neu ) viel Arbeit ab.
 Es können auch Klassen, Methoden und Eigenschaften erstellt
werden, die nicht im Standardumfang der API vorhanden sind (
Stichwort undokumentiert )
„Das umzusetzen ist aber viel Arbeit“
 Klein anfangen! Der Wrapper kann sukzessive erweitert werden.
 C / CPP Wrapper können parallel verwendet werden

40. RichText

41. CAPI und RichText
 Frage im Forum:
 Kennt jemand eine Möglichkeit,
die Größe von eingebetteten
Bildern in einem Notes RichText
Item auszulesen?

42. CAPI und RichText
Es gibt keine Methode oder
Eigenschaft dafür
Es gibt keine Methode oder
Eigenschaft dafür
Es gibt keine @Formel dafür
@Formula ?

43. Dann bauen wir uns eine Funktion selber
Container für unstrukturierte Daten
Mehrere Items mit dem selben Namen möglich
Compound Document Records ( CD )
 Feste Struktur ( CD Type + Daten )
 Über 200 unterschiedliche CD Types
RichText ist niemals „leer“

44. Dann bauen wir uns eine Funktion selber

45. Schematischer Programmaufbau
Öffnen der Datenbank und des zu untersuchenden
Dokuments
Lesen des „Body“ Items
Lesen der enthaltenen CD Records bis „Image Header“
gefunden ist
Lesen des Header CD Records
Ausgabe der Daten
Programmabschluß

46. „Image Header“ suchen

47. Auslesen der „Image Header“ Daten

48. Funktionen
kapseln (DLL)

49. Ein Fall aus der Praxis
Erste Kontaktaufnahme des Kunden (04.08.2015)
“Our company does mortgages and we need to check the
customer's security info (PATRIOT ACT).
We use a 3rd party software package. Here is a sample of a bat
file that is being executed. For your info the bat file is always
executed without errors from Bridger even when the server
crashes.
As far as NSD files we have been working with IBM Support for
many months now.
They have not been able to find anything very helpful in them.
But if it OK with my manager I would be glad to send you
some. BTY. We have hundreds to choose from.  “

50. Die Ausgangslage
Formular
ausfüllen
 Der Kunde füllt auf der Webseite des Unternehmens ein Formular aus
und sendet es ab.
Server erhält
Request
 Die Daten werden aufbereitet
 Die Daten für die Prüfung werden extrahiert und der LotusScript Code
für die Ansteuerung des 3rd-party Tools ausgeführt
Prüfen der Daten
 Die Prüfung erfolgt
 LotusScript wartet bis zur Beendigung des Prüfprozesses und
empfängt das Ergebnis der Prüfung
Rückmeldung
 Abhängig vom Ergebnis der Prüfung erhält der Kunde Mitteilungen
über die weitere Vorgehensweise auf dem Bildschirm
 Oder auch nicht …
8.5.3 FP6 64Bit Domino server running on Win 2008/64

51. Funktionsaufruf

52. Deklarationen

53. Strukturen

54. Umsetzung als exportierte Funktion

55. Deklaration und Funktionsaufruf

56. Mail des Kunden an IBM Support ( 17.08.2015 )
“The servers have not crashed since 8/7/2015. Therefore, you can
close this PMR.
Instead of using a C-API call to the Windows "CreateProcess"
function we are now using a type of wrapper DLL function call.
Thank you and the Support team which worked with us to located
this problem. It has been a very long and trying 9 months.
I also would like to convey an every bigger "thank you" from our
several hundred users.
Whenever the server crashed their work load increased because
they had to recover any lost data.
They are now able to work normally. “
Mail nach Installation der DLL ( 06.08.2015):
“Buckle your seat belts. Ralph and I will attempt to plug this in
and test it the rest of Today and will attempt to go live with it
Tomorrow morning. I'll let you know how it goes... “

57. Lessons learned
 Code kann jahrelang ohne Probleme funktionieren. Eines Tages wird er es nicht mehr.
 Ursachen für das Fehlverhalten können erkannt und beseitigt werden.
 Ursachen für das Fehlverhalten können nicht erkannt und nicht beseitigt werden.
 Probleme treten grundsätzlich bei geschäftskritischen Anwendungen auf.
 In der Regel treten Probleme beim C-Level auf; kurz vor oder während des
Wochenendes
 Verlasse dich nicht darauf, daß der Softwarehersteller dein Problem löst.
 Es lohnt sich immer, einen Plan B zu haben.

58. Extension
Manager

59. Extension Manager
„Hört“ auf Events am Domino Server
Es gibt unzählige Events ( extmgr.h )
Der Extension Manager kann VOR oder NACH dem Event
die Daten das Events verarbeiten.
 EM_REG_BEFORE
 EM_REG_AFTER
Beispiel: TriggerHappy, OpenNTF
 https://www.openntf.org/main.nsf/project.xsp?r=project/Trigger%
20Happy

60. Passwort an (Server) ID übergeben

61. Passwort an (Server) ID übergeben
Event EM_GETPASSWORD registrieren. Wir registrieren den Event VOR der
eigentlichen Passwortabfrage.
Modifizierter Code aus CAPI Samples: notesapi9.0.1samplesmiscextpwd

62. Wenn der Event nicht EM_GETPASSWORD
ist, dann zurück zur aufrufenden Funktion
Passwort aus Datei auslesen, in die Struktur
schreiben und zurück zur aufrufenden
Funktion.

63. Backup &
Restore

64. Backup Restore
Die cAPI stellt eine ganze Reihe von Methoden für das
Backup und Restore von Notes Applikationen zur
Verfügung
Gerald Peters - Backup und Restore mit der C-API, EC2017
Daniel Nashed – Domino Backup, DNUG Domino Day 2016
DomBackup
 https://www.openntf.org/main.nsf/project.xsp?r=project/DomBac
kup

65. DomBackup CLI
-h [-–help] Display this help message
-s [-–source] source file/folder
-d [-–dest] destination file/folder
-i [-–include-sub-dirs] Include subdirs, applies to folder backup only
(optional, default = false)
-t [-–throttle] Wait short time between file writes (optional, default =
false)
-z [-–zip] Move file to .zip archive after backup (optional, default =
false)
-u [-–unique-filename] appends a timestamp to the archive filename
(optional, default = false)
-a [-–application-type] (=nsf) nsf,ntf,both (optional, default = nsf only)
-f [-–input-file] Backup all the files specified in an .ind file in the data
folder to <dest>
-v [-–version] Display the version number

66. Standalone
Programm

67. Versionsinformationen
Wie kommt die Versionsnummer in
eine Notes Anwendung oder ein
Template ?
Die Nummer ist auch nicht in allen
Datenbanken oder Templates vorhanden.
Warum ist das so?

68. ntfbuild.exe
Commandline tool.
Benötigt Notes Client
Kann in Buildumgebungen wie Jenkins, Bamboo oder
TeamCity verwendet werden.
Verwendet ein eigenes CPP Framework
Boost Libraries
Easyloggingcpp
 https://github.com/muflihun/easyloggingpp
cmdline: A simple command line parser for C++
 https://github.com/tanakh/cmdline

69. ntfbuild.exe

70. ntfbuild.exe

71. Inside ntfbuild.exe - Filehandling
• boost::filesystem zum Erstellen von Verzeichnissen ( auch verschachtelt )und
Löschen von Dateien
• NSFDbRename zum Verschieben / Umbenennen von Notes Datenbanken.
Kann auch sehr große Datenbanken auf einem Server verschieben

72. Inside ntfbuild.exe - Signing
#include <nsfnote.h>
STATUS LNPUBLIC NSFNoteSignExt3(
NOTEHANDLE hNote,
KFHANDLE hKFC,
const char far *SignatureItemName,
WORD ItemCount,
DHANDLE hItemIDs,
DWORD Flags,
DWORD Reserved,
void *pReserved);

73. Welches Zertifikat ist das DEFAULT Zertifikat?

74. @If(CertificateList="";"";
@X509Certificates([SetAsEncryptionCertificate];
UserCertificate;"";CertificateList));
@Command([ViewRefreshFields])

75. midpoints Certana
Certificate Analyzer
Kommandozeilen Tool
Analysiert Dokumente mit Internet Zertifikaten in 1 - n
Adressbüchern ( expired, not valid before, default )
OpenSSL
 https://www.openssl.org/
Secure programming with the OpenSSL API (IBM)
 https://www.ibm.com/developerworks/library/l-openssl/
Undokumentierte Funktionen.

76. midpoints Certana
Usage: certana.exe -s <servername> [options] [flags]
Options:
-h --help Prints this help
-s --server Target server
-u --user Analyse certificates of a named user
-i --infile Read list of users from .ind file
-o --outfile Write to file
Flags:
--primary Search in primary Domino Directory (names.nsf) only
--no-console Silent mode. Writes to file if configured with -o <filename>
--debug Debug mode

77. Inside Certana
if (error = SECNABEnumerateCertificates(
hNote,
(SECNABENUMPROC)callback_certs ,pCtx, 0, 0)) {
}

78. Undokumentierte
Funktionen

80. Undokumentierte Funktionen.
http://www-
10.lotus.com/ldd/46dom.nsf/0/54feea2820bfc15a412568960034054b?OpenDocument
PMR 00452,999,724 - Antwort vom Support
“Some functionality is decided by the lab to not be published. This is a choice
made for various reasons (functionality incomplete to be used in all cases, not be
limited later on to change the functionality, etc...) This request will not be met.
Several other such requests were made but never met”

81. Undokumentierte Funktionen
http://www.nirsoft.net/utils/dll_export_viewer.html

82. Undokumentierte Funktionen
.bat, Batchfiles zum Erstellen der statischen library
.def, enthält die Funktionsnamen und Ordinalzahlen
.h, enthält die Funktionen und ihre Signaturen
.lib, die statische library

83. Statische Library erstellen
Funktion finden  nnotes.dll in DLL Export öffnen und Funktion suchen. Ordinalzahl ermitteln.
Eintrag in .def  Funktion mit Ordinalzahl in .def Datei für den Export eintragen
Eintrag in .h
 Die Signatur der Funktion muss in die .h Datei eingetragen werden. Das ist der
schwierige Teil, weil diese Angaben nicht (immer) durch Suche im Netz zu
finden sind. Viel Glück!
Erstellen der .lib
Beispiel für 64Bit:
call "C:Program Files (x86)Microsoft Visual Studio 8VCvcvarsall.bat" amd64
call "%ICPP_COMPILER11%biniclvars.bat" intel64
del notesplus64.lib
xilib /MACHINE:x64 /DEF:notesplus64.def /OUT:notesplus64.lib

84. Server
Addin

85. Eigene Administrationsprozesse
Wie lösche ich eine oder mehrere Einträge in einer
Gruppe, ohne die Person oder Gruppe selber zu löschen?
Es gibt dafür keinen Administrationsprozess.
Bob Balfe - Creating a custom Administration Process
Request Handler
 https://www.ibm.com/developerworks/lotus/library/ls-
Custom_AdminP_Handler/
Video von 2007 (immer noch verfügbar )
 http://www.screencast.com/t/htEtry53BSk
 http://www.eknori.de/2007-12-15/delete-group-members-using-
the-administration-process/

86. Java2CAPI

87. Java2CAPI – Domino JNA
Karsten Lehmann, mindoo
https://github.com/klehmann/domino-jna

88. Java2CAPI – Domino JNA
Cross-platform access to IBM Notes/Domino C API
methods from Java
The project provides functionality that is not available in
the classic Java API of IBM Notes/Domino or that is poorly
implemented. (see GitHub )
Also works in XPages
The code should run in 32 and 64 bit Notes Client and
Domino server environments on Windows, Linux and Mac.
It is not expected to run without changes on other
platforms, mainly because of little endian / big endian
differences or memory alignments, but we don't currently
have access to those platforms anywa

89. DOTS – application.tool
Was ist und was kann das application.tool?
 DOTS Task ( Scanner, Jobber )
 Verwendet Domino JNA. (DirectoryScanner.class)
 Scannen aller Datenbanken und Templates auf dem lokalen Server oder Remote Servern
 Auslesen aller Eigenschaften eines Datenbank / Template Objets
 Auslesen der ACL
 Analyse des FT Verzeichnisses
 Analyse des NIFNSF Verzeichnisses

90. @DbColumn
@DbLookup

91. @Formula
@DbLookup( class : cache ; server : database ; view ; key ; fieldName
; keywords ) or
@DbLookup( class : cache ; server : database ; view ; key ;
columnNum ; keywords)
@DbColumn( class : cache ; server : database ; view ; columnNum )
Klasse / Class
Text. Gibt den Typ der Datenbank an, auf den
Sie zugreifen. Handelt es sich um eine Domino
Datenbank, können Sie entweder "Notes" oder
"" (leere Zeichenfolge) angeben.

92. Templates
1 Database Initialization and Termination;
MainEntryPoint(), DBDTerm()
2 Open and Close a Session;
DBDOpen, DBDClose
3 Perform a Database Driver Function;
DBDPerformFunction
Siehe CAPI UserGuide, Chapter 12-7,External Database Drivers

93. @DbLookup("dbdrv"; "dbdriver.db"; "North America")
@DbColumn("dbdrv"; "dbdriver.db")

94. DSAPI

95. “The Domino Web Server Application Programming Interface (DSAPI) is a C
API that you can use to write your own extensions to the Domino Web Server.
These extensions, or filters, let you customize authentication for Web users. “

100. Ulrich Krause
Developer
midpoints GmbH
ulrich.krause@midpoints.de