Hinweise zur Arbeit mit den Komponenten

Überblick

Das signoAPI für Windows enthält mehrere COM-kompatible Komponenten, die als DLL oder OCX ausgeliefert werden. Durch die Verwendung des COM-Interfaces können die Komponenten in verschiedenen Programmiersprachen verwendet werden, dafür müssen aber die Parameter in COM-kompatiblen Containern übergeben werden. Näheres dazu findet sich im Abschnitt zu den COM-Datenstrukturen.

Die Komponenten der signoAPI sind grundsätzlich auf allen Windows-Versionen ab Windows 10 lauffähig. Sie können in allen Programmiersprachen und Entwicklungsumgebungen verwendet werden, in denen COM-DLLs referenziert werden können. Für Details beachten Sie bitte die Dokumentation Ihrer Entwicklungsumgebung.

Verwendung der Bibliotheken beim Programmieren

Nachfolgend wird beschrieben, wie die Bibliotheken eingebunden werden können. Für ActiveX-Steuerelemente ist dabei eine gesonderte Handhabung notwendig.

C#

ActiveX-Steuerelement

Das Element kann in Visual Studio dem Reiter “Toolbox” hinzugefügt werden, entweder über den Menüpunkt “Extras/Toolboxelemente auswählen…” oder über das Kontextmenü der Toolbox unter “Elemente auswählen…”. In dem darauf erscheinenden Dialog muss unter dem Reiter “COM-Komponenten” die gewünschte Komponente aktiviert werden. Wenn ein Formular im Editor aktiv ist, ist der Toolboxreiter sichtbar, und das aktivierte ActiveX-Element kann per Drag and Drop dem Formular hinzugefügt werden. In WPF wird ein Windows Form Host benötigt.

COM-Komponente ohne GUI

Die Bibliothek muss unter den Verweisen hinzugefügt werden. Die Komponenten finden sich dabei unter dem Punkt “COM”. Der Bibliotheksname ist in der Beschreibung der einzelnen Komponenten dokumentiert.

C++

ActiveX-Steuerelement

Nach der Registrierung kann die Komponente über die Auswahl verfügbarer ActiveX-Steuerelemente in ein GUI angebunden werden. In Visual Studio kann dafür nach Rechtsklick auf ein Dialogelement der Menüpunkt “ActiveX-Steuerelement einfügen” ausgewählt werden. Dann erscheint eine Liste von verfügbaren Elementen, aus der das gewünschte Element ausgesucht werden kann. Nach der Bestätigung wird die Komponente automatisch eingebunden und ein entsprechender Header erstellt.

COM-Komponente ohne GUI

Um die Bibliothek zu verwenden, muss sie zunächst mit der Präprozessor-Direktive #import eingebunden werden. Dazu wird entweder der Pfad zur Bibliothek oder die Bibliotheks-ID benötigt. Alternativ kann die Klasse über die Prog-ID eingebunden werden. Die IDs finden Sie jeweils in der Dokumentation zu den Komponenten.

Beispiel SignPDF3 mit Bibliotheks-ID:

#import "libid:9ae466d7-8126-4355-bc49-8507fc252566" raw_interfaces_only

Beispiel SignPDF3 mit Prog-ID:

#import "progid:SIGNPDF3.SignDigSigPDF.1" raw_interfaces_only

Wird dem Import-Befehl das Schlüsselwort raw_interfaces_only nachgestellt, wird ein Header mit Methoden erstellt, die einen HRESULT-Wert zurückgeben. Der Rückgabewert gibt an, ob die Funktion fehlgeschlagen ist und warum. Wird das Schlüsselwort nicht verwendet, wird für alle Methoden der Komponente automatisch eine Wrapper-Funktion erstellt, die einen COM-Fehler wirft, wenn die Funktion fehlschlägt. Der Fehler muss dann entsprechend abgefangen werden. Es bleibt dem Entwickler überlassen, welche der beiden Möglichkeiten verwendet werden soll.

Vor Verwendung der Bibliothek muss sie noch initialisiert werden. Dazu wird ein Zeiger vom Typ der gewünschten Schnittstelle (“Interface”) erstellt und damit die Funktion CoCreateInstance mit der Klassen-ID (CLSID) und der Schnittstellen-ID (IID) aufgerufen. Eine Komponente kann auch mehrere Schnittstellen haben. Die IDs können auch aus den Typdefinitionen der Klasse und Schnittstelle abgeleitet werden. Die entsprechenden IDs und Namen finden sich in der Dokumentation der jeweiligen Komponente.

Nach Verwendung der Schnittstelle muss sie mittels der Funktion Release wieder geschlossen werden.

Ein Beispiel mit der Bibliothek SignPDF3:

SIGNPDF3Lib::ISignDigSigPDF* interfacePtr;
CoCreateInstance(
                 __uuidof(SignDigSigPDF),
                 nullptr,
                 CLSCTX_INPROC_SERVER,
                 __uuidof(ISignDigSigPDF),
                 (void**)&interfacePtr
                 );
                 
[code that uses the interface]

if (interfacePtr)
{
    interfacePtr->Release();
}

Daten und Datenformate

Dokumente

Dokumente können im PDF-Format oder als Bild vorliegen. Viele Funktionalitäten sind aber nur für PDF-Dokumente verfügbar.

Informationen dazu, wie Koordinaten in den Dokumenten referenziert werden, sind hier zu finden.

SignData

Die Datenstruktur “SignData“ ist ein von signotec entwickeltes Standardformat für die Unterschriftendaten, das von verschiedenen Komponenten verwendet wird. Es ist ein verschlüsseltes, komprimiertes, biometrisches Format, das in einer Datenbank oder als Tag in einem Dokument hinterlegt werden kann.

Aus Gründen der Rückwärtskompatibilität ist teilweise noch die Datenstruktur „PadData“, ein Rohformat für Unterschriftendaten, verfügbar. Diese ist veraltet und sollte nicht mehr verwendet werden.

COM-Datenstrukturen

Für die Kommunikation mit den Komponenten werden ausschließlich OLE- und COM-konforme Datentypen verwendet.

Verschiedene Daten wie zum Beispiel der Inhalt von PDF-Dokumenten und Zertifikaten wird an die Methoden jeweils als Byte-Array übergeben. Dafür wird der übergebene Inhalt als eine Sequenz von Bytes interpretiert.

In C# wird das Byte-Array als Object übergeben.

In C++ wird der Byte-Array in Form einer Variant-Struktur übergeben. Das Variant-Objekt muss die Attribute VT_ARRAY und VT_UI1 gesetzt haben und seine Membervariable parray muss auf eine SAFEARRAY-Struktur zeigen, die die Daten des Dokuments enthält.

Strings werden aus Kompatibilitätsgründen in C++ als BSTR übergeben. In C# wird eine automatische Konvertierung vorgenommen, so dass mit dem Datentyp “string” gearbeitet wird.

In wenigen Methoden wird ein Stringobject übergeben. Dabei handelt es sich in C# um einen als Object interpretierten String, in C++ um ein VARIANT vom Typ VT_BSTR, das den String im Format BSTR enthält.

Die Rückgabewerte aller Funktionen einer Komponente sind entweder in den einzelnen Methoden explizit beschrieben, oder alle Methoden der Komponente geben einen Wert vom Typ HRESULT zurück. In letzterem Fall gilt:

Bei nicht erfolgreicher Ausführung wird sowohl in C# und als auch in C++, falls die Bibliothek ohne das Schlüsselwort raw_interface_only importiert wurde, eine COMException geworfen, die den zurückgegebenen HRESULT-Wert enthält. Wurde die Bibliothek in C++ mit dem Schlüsselwort raw_interfaces_only importiert, geben die Methoden direkt den HRESULT-Wert zurück, den der Benutzer selbstständig überprüfen muss. Bei erfolgreicher Ausführung entspricht dann der Rückgabewert dem Wert S_OK.

Beispielanwendungen

Um Ihnen den bestmöglichen Zugang zu dieser Komponente zu ermöglichen, bietet signotec neben dieser Dokumentation zusätzliche Beispielanwendungen an. Der Code dieser Beispielanwendungen ist im signoAPI-Setup enthalten. Sofern Sie noch keine Lizenz besitzen, stellt ein zeitlich begrenzter Schlüssel sicher, dass eine Evaluierung der sonst kostenpflichtigen Komponenten über einen ausgedehnten Zeitraum erfolgen kann.

Die SignPDF-Demo-App wurde entwickelt, um das Zusammenspiel verschiedener signotec-Komponenten zu veranschaulichen. Sie zeigt, wie digitale Signaturen erstellt werden können, und begleitet Sie durch alle Schritte von der Darstellung über den Signiervorgang und die Speicherung bis hin zur Validierung. In der C++-Version der Demo sind alle wichtigen Funktionen enthalten, in der C#-Demo werden obendrein noch verschiedene zusätzliche Funktionen veranschaulicht.

Für die Komponente STImgCtl gibt es eine separate Beispielanwendung in C#, die Ihnen die Möglichkeit bietet, die meistgenutzten Features direkt zu testen und so schnell einen Eindruck vom Zusammenspiel der Methoden und ihren Abhängigkeiten untereinander zu erhalten.

Für signoMobileCapture ist ebenfalls eine Demoanwendung in C# vorhanden.