Overview
The signoAPI for Windows contains several COM-compatible components that are delivered as DLL or OCX files. Using the COM interface enables the components to be used in different programming languages, but the parameters need to be transferred in COM-compatible containers. For more details, see the section on COM data structures.
The components of signoAPI are generally compatible with all Windows versions from Windows 10 onwards. They can be used in all programming languages and development environments in which COM DLLs can be referenced. For details, please refer to the documentation of your development environment.
There is a separate implementation for use with Java, called “signoAPI Java". Please speak to your signotec contact.
Using libraries in programming
The following describes how the libraries can be integrated. ActiveX controls require special handling.
C#
ActiveX control
The element can be added to the “Toolbox” tab in Visual Studio, either via the menu item “Tools/Select Toolbox Items...” or via the context menu of the Toolbox under “Select Items...”. In the dialog box that appears, the desired component must be activated under the “COM Components” tab. When a form is active in the editor, the toolbox tab is visible and the activated ActiveX element can be added to the form using drag and drop. A Windows Form host is required in WPF.
COM component without GUI
The library must be added under the references. The components can be found under the heading “COM". The library name is documented in the description of the individual components.
C++
ActiveX control
After registration, the component can be integrated into a GUI by selecting available ActiveX controls. In Visual Studio, you can do this by right-clicking a dialog element and selecting the menu item “Insert ActiveX control". A list of available items will then appear, from which you can select the desired item. After confirmation, the component is automatically integrated and a corresponding header is created.
COM component without GUI
To use the library, it must first be included using the preprocessor directive #import. To do this, you need either the path to the library or the library ID. Alternatively, the class can be integrated using the Prog ID. You can find the IDs in the documentation for the components.
Example SignPDF3 with library ID:
#import "libid:9ae466d7-8126-4355-bc49-8507fc252566" raw_interfaces_only
Example SignPDF3 with Prog ID:
#import "progid:SIGNPDF3.SignDigSigPDF.1" raw_interfaces_only
If the keyword raw_interfaces_only is appended to the import command, a header is created with methods that return an HRESULT value. The return value indicates whether the function failed and why. If the keyword is not used, a wrapper function is automatically created for all methods of the component that throws a COM error if the function fails. The error must then be handled accordingly. It is up to the developer to decide which of the two options to use.
Before the library is used, it must be initialised. To do this, a pointer of the desired interface type is created and used to call the CoCreateInstance function with the class ID (CLSID) and interface ID (IID). A component can also have multiple interfaces. The IDs can also be derived from the type definitions of the class and interface. The corresponding IDs and names can be found in the documentation for the respective component.
After the interface has been used, it must be closed again using the Release function.
An example using the SignPDF3 library:
SIGNPDF3Lib::ISignDigSigPDF* interfacePtr;
CoCreateInstance(
__uuidof(SignDigSigPDF),
nullptr,
CLSCTX_INPROC_SERVER,
__uuidof(ISignDigSigPDF),
(void**)&interfacePtr
);
[code that uses the interface]
if (interfacePtr)
{
interfacePtr->Release();
}
Data and data formats
Documents
Documents can take the form of PDFs or images. However, many functionalities are only available for PDF documents.
Information on how coordinates are referenced in the documents can be found here.
SignData
The “SignData” data structure is a standard format for signature data developed by signotec that is used by various components. It is an encrypted, compressed, biometric format that can be stored in a database or as a tag in a document.
For reasons of backward compatibility, the “PadData” data structure, a raw format for signature data, is still available in some cases. This is deprecated and should no longer be used.
The signature data can be visualised in real time using the “signview.dll” component, as long as it is not RSA-encrypted.
COM data structures
Only OLE- and COM-compliant data types are used for communication with the components.
Various data, such as the content of PDF documents and certificates, is passed to the methods as a byte array. For this purpose, the transferred content is interpreted as a sequence of bytes.
In C#, the byte array is passed as an object.
In C++, the byte array is passed in the form of a variant structure. The variant object must have the attributes VT_ARRAY and VT_UI1 set, and its member variable parray must point to a SAFEARRAY structure that contains the document data.
For compatibility reasons, strings are passed as BSTR in C++. In C#, automatic conversion is performed so that the data type “string” is used.
A string object is passed in a few methods. In C#, this is a string interpreted as an object, and in C++, it is a VARIANT of type VT_BSTR, which contains the string in BSTR format.
The return values of all of a component’s functions are explicitly described in the individual methods, unless the component’s methods all return a value of type HRESULT. In the latter case, the following applies:
If execution is unsuccessful, a COMException containing the returned HRESULT value is thrown in both C# and C++ if the library was imported without the raw_interface_only keyword. If the library was imported in C++ with the raw_interfaces_only keyword, the methods return the HRESULT value directly, which the user must check independently. If executed successfully, the return value corresponds to the value S_OK.
Example applications
To ensure that you have the best possible access to this component, signotec provides additional example applications in addition to this documentation. The code for these sample applications is included in the signoAPI setup. If you do not yet own a licence, a time-limited key makes it possible for you to evaluate the components that would otherwise cost money over a prolonged time period.
The SignPDF demo app is designed to show the interaction of various signotec components. It shows how digital signatures can be created and supports you through all steps from display to signing, saving and validation. The C++ version of the demo includes all important functions, while the C# demo also illustrates various additional functions.
There is a separate sample application in C# for the STImgCtl component, which allows you to test the most commonly used features directly, and quickly get a feel for how the methods interact and relate to each other.
A demo application in C# is also available for signoMobileCapture.