Entwicklercamp 2017

C / C++ für Notes & Domino EntwicklerUlrich Krause

27. – 29..03.2017 Maritim Hotel, Gelsenkirchen

Über: Ulrich Krause

Lotus Notes und Domino seit 1993

EntwicklerAdministrator

IBM Champion 2010 – 2016OpenNTF Contributor

Entwickler bei midpoints GmbH

1996 – Erste „Entwicklerversion“

“ 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 )

C API

LSX ToolkitC++ API

JAVA 2 CAPI

LS 2 CAPI

Möglichkeiten

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

Wo operiert die API?

Back-EndFront-End

NSF /NTF Container )

Betriebssystem

Notes Object Interface (NOI)

Lotus Script

C++ API

Notes Core ( C API )

Visual Basic (COM)JAVA

JNI

Zugriffe

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

Welche Werkzeuge brauche ich?

https://www-01.ibm.com/marketing/iwm/tnd/nochargesearch.jsp?cat=&q0=&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.wss?uid=swg24005686

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 xSeriesGNU 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 forGNU Compiler Collection (gcc/g++) version 4.3.x

Macintosh OS X 10.5.5 or late

Alternative IDE

https://code.visualstudio.com/

Standalone Compiler für Windows

http://landinghub.visualstudio.com/visual-cpp-build-tools

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

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"));

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/

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 preiswertLotus Script, Java

JAVA 2 CAPI

* Im Kontext von IBM Notes & Domino

Grundlagen

C/C++: Additional Include Directories

C/C++: Preprocessor Definitions

C/C++: Code Generation

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

#if defined (W64)

#define HANDLE DHANDLE#undef NOTEHANDLE#define NOTEHANDLE DHANDLE

#else // 32Bit

#define DHANDLE HANDLE#undef NOTEHANDLE#define NOTEHANDLE HANDLE

#endif

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

Linker: Additional Library Directories

Linker: Additional Dependencies

Beispiel: C API

Beispiel: DLL mit C API

Beispiel: C++ API

C++ API (cont.)

C++ API (cont.)

C++ API (cont.)

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

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.

Eigener C++ Wrapper

Klassencode mit Konstruktor, Destruktor und Errorhandling.

Einfache Verwendung im Code.

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

RichText

CAPI und RichText

Frage im Forum: Kennt jemand eine Möglichkeit,

die Größe von eingebetteten Bildern in einem Notes RichText Item auszulesen?

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

Lotu

sScr

ipt ? Java ?

@Formula ?

Dann bauen wir uns eine Funktion selber

Container für unstrukturierte DatenMehrere 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“

Dann bauen wir uns eine Funktion selber

Schematischer Programmaufbau

Öffnen der Datenbank und des zu untersuchenden Dokuments

Lesen des „Body“ ItemsLesen der enthaltenen CD Records bis „Image Header“

gefunden istLesen des Header CD RecordsAusgabe der DatenProgrammabschluß

„Image Header“ suchen

Auslesen der „Image Header“ Daten

Funktionen kapseln (DLL)

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. “

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

Funktionsaufruf

Deklarationen

Strukturen

Umsetzung als exportierte Funktion

Deklaration und Funktionsaufruf

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... “

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.

Extension Manager

Extension Manager

„Hört“ auf Events am Domino ServerEs 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

Passwort an (Server) ID übergeben

Passwort an (Server) ID übergeben

Event EM_GETPASSWORD registrieren. Wir registrieren den Event VOR der eigentlichen Passwortabfrage.

Modifizierter Code aus CAPI Samples: notesapi\9.0.1\samples\misc\extpwd

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.

Backup &Restore

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, EC2017Daniel Nashed – Domino Backup, DNUG Domino Day 2016

DomBackup https://

www.openntf.org/main.nsf/project.xsp?r=project/DomBackup

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

Standalone Programm

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?

ntfbuild.exe

Commandline tool. Benötigt Notes ClientKann in Buildumgebungen wie Jenkins, Bamboo oder

TeamCity verwendet werden.Verwendet ein eigenes CPP FrameworkBoost LibrariesEasyloggingcpp https://github.com/muflihun/easyloggingpp

cmdline: A simple command line parser for C++ https://github.com/tanakh/cmdline

ntfbuild.exe

ntfbuild.exe

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

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);

Welches Zertifikat ist das DEFAULT Zertifikat?

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

midpoints Certana

Certificate AnalyzerKommandozeilen ToolAnalysiert 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.

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

Inside Certanaif (error = SECNABEnumerateCertificates(

hNote, (SECNABENUMPROC)callback_certs ,pCtx, 0, 0)) {

}

Undokumentierte Funktionen

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”

Undokumentierte Funktionen

http://www.nirsoft.net/utils/dll_export_viewer.html

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

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 8\VC\vcvarsall.bat" amd64call "%ICPP_COMPILER11%\bin\iclvars.bat" intel64del notesplus64.libxilib /MACHINE:x64 /DEF:notesplus64.def /OUT:notesplus64.lib

Server Addin

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-th

e-administration-process/

Java2CAPI

Java2CAPI – Domino JNA

Karsten Lehmann, mindoo

https://github.com/klehmann/domino-jna

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 XPagesThe 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

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

@DbColumn

@DbLookup

@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.

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

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

@DbColumn("dbdrv"; "dbdriver.db")

DSAPI

“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. “

THANK YOU

Ulrich KrauseDeveloper

midpoints GmbH

ulrich.krause@midpoints.de