C-API Documentation
C-API Version 3.3.0.0
SignWare C-API [Core]
The API documentation is structured in object modules. Each module describes the accessible types, variables, and functions for the corresponding object. Major headers are- SPAcquire.h declares functions for capturing dynamic signatures without GUI (SPAcquire object). Please see SPGuiAcqu.h to capture signatures with GUI.
- SPBackgroundObjects.h declares a container for tablet background descriptors.
- SPBitmap.h declares functions for converting objects such as signatures, references, and templates to a standard image format (SPBitmap object).
- SPCleanParameter.h defines a parameter container for cleaning static images (SPCleanParameter object).
- SPCompare.h defines a signature comparison object (SPCompare).
- SPFlatFile.h declares functions for serializing objects. Serialized objects (SPFlatFile objects) can be saved in a file or in a database.
- SPGuiAcqu.h declares functions for capturing dynamic signatures with GUI (SPGuiAcqu object). Please see SPAcquire.h to capture signatures without GUI.
- SPGuiContainer.h declares funtions or capturing signatures with GUI from one or more tablets at the same time.
- SPGuiDisp.h declares functions for visualizing signatures (SPGuiDisp object).
- SPGuiDyn.h declares functions for visualizing dynamic features of signatures (SPGuiDyn object).
- SPImage.h declares functions for processing images containing static signatures (SPImage object).
- SPPropertyMap.h implements a property container.
- SPReference.h declares functions related to references (SPReference object, comprising several dynamic signatures).
- SPScanner.h declares functions for accessing scanners, including enumerating scanner devices and querying scanner properties
- SPSmartcard.h defines an interface to smart cards, based on ISO 7816 (SPSmartcard object).
- SPSmartcardDriver.h defines an interface to CT-API-compliant smart card readers (SPSmartcardDriver object).
- SPSignature.h declares functions for processing a single dynamic signature (SPSignature object, comprising tablet vectors (samples) and other properties of a dynamic signature).
- SPSignWare.h contains global definitions such as return codes and type definitions.
- SPTablet.h declares functions related to the SPTablet object used for capturing signatures from a tablet.
- SPTabletEnum.h declares functions related to the SPTabletEnum object used to enumerate installed and connected tablets on the computer.
- SPTeller.h defines an interface to SignBase® (SPTeller and SPTellerImage objects).
- SPTicket.h declares functions for handling license tickets (SPTicket object, deprecated).
- SPTemplate.h declares functions related to signature templates (SPTemplate object). A template is a special type of a signature reference optimized for minimum storage requirements.
Error handling and debugging
All SignWare functions return an error code as described in the function description. The lists of error codes need not be comprehensive.- Call SPSignwareGetErrorString to convert an error code to an English text.
- More detailed information about errors is written into a log file if the environment variable SPDEBUG is set to a value in the range 1 through 5. The bigger the value, the more information will be logged.
- The location of the log file is defined by the environment variable SPDEBUGDIR. If the value of SPDEBUGDIR is the pathname of an existing directory, the log file will be named logfile.log in that directory. Otherwise, the value of SPDEBUGDIR is taken as filename of the log file.
- If SPDEBUGDIR is not set, the log file will be named logfile.log in the directory specified by the environment variable TEMP. If TEMP is not set, TMP will be used. If both environment variables are not set, the current working directory will be used.
- No log information is written if the log file cannot be created, e.g., if the specified path does not exist or if access is denied.
- If the log file already exists, new information will be appended. If the log file does not exist, it will be created.
- Always include a log file with SPDEBUG set to 5 when sending an incident (bug) report to the SignWare contact address.
FAQs: Frequently Asked Questions
What databases are supported by SignWare?SignWare does not access any database directly. SignWare converts (serializes) some objects such as signatures, references, and templates to a binary flat file format that may be inserted into any database as a blob.
How can I check if a tablet is installed and connected?
Create an SPTablet object, then check the device. A Tablet is connected if the driver is not SP_UNKNOWN_DRV and the resolution is non-zero. Please note that there is a limitation on Wacom tablets: the driver returns a valid tablet ID and resolution even if no tablet is connected to the system.
Are there any restrictions on the size and resolution of static images?
The static compare engine rejects images with a width smaller than 20 pixels or a height smaller than 10 pixels. Moreover, the width must not exceed 2560 pixels and the height must not exceed 1920 pixels. The minimum resolution of static images is 150 DPI, resolutions 200 DPI through 300 DPI are recommended.
How can I determine if a static image is empty?
Query the signature region (SPImageGetSignatureRegion) and check if the resulting rectangle is smaller than 5mm by 5mm.
You may want to clean the image first to remove any dirt by calling SPImageCleanSignature.
How can I determine if a dynamic signature is empty?
Check if the number of vectors in the signature (see SPSignatureGetNrVectors) is greater than 5.
This check might include vectors having a pressure level of 0. Alternatively, you may check the size of the signature image (see SPSignatureGetImageSize), but this is more expensive in terms of CPU time.
The above checking is implemented in a single call to SPSignatureCheck or SPReferenceCheck with SP_SIGNATURE_MIN_VECTORS or SP_SIGNATURE_MIN_WIDTH and SP_SIGNATURE_MIN_HEIGHT set accordingly.
How can I read the background image of a tablet for audit purposes?
Query the background image (SPGuiAcquGetBackgroundImage).
The returned Image equals the image as it was sent to the tablet (or PC screen) without signature strokes.