SPTemplate.h File Reference

---

Detailed Description

SignWare Dynamic Development toolkit, SPTemplate object.

Author:

uko

This header defines the SPTemplate object.

A template is a compressed representation of a signature reference. It is optimized for minimum storage space, but the compression is lossy. You will typically save templates on a smart card, where memory space is limited. Databases normally do not have memory restrictions so you would normally save a reference signature as a flat file object in a database.

A signature reference includes at least three signatures.

Functions
SPINT32 __cdecl	SPTemplateAddOption (pSPTEMPLATE_T pTemplate, SPINT32 iOptionType, SPVPTR lValue)
	Add an optional parameter (option) to an SPTemplate object.
SPINT32 __cdecl	SPTemplateAddOptionId (pSPTEMPLATE_T pTemplate, SPINT32 iOptionType, SPINT32 iId, SPVPTR lValue)
	Add an optional parameter (option) with ID to an SPTemplate object.
SPINT32 __cdecl	SPTemplateClone (pSPTEMPLATE_T pTemplate, pSPTEMPLATE_T *ppTemplate)
	Create a copy of an SPTemplate object.
SPINT32 __cdecl	SPTemplateCreateFromFlatFile (pSPTEMPLATE_T *ppTemplate, const SPUCHAR *pbFlatFile, SPINT32 iFlatFileLength)
	Create a new SPTemplate object from a flat file object.
SPINT32 __cdecl	SPTemplateCreateFromReference (pSPTEMPLATE_T *ppTemplate, pSPREFERENCE_T pReference, SPINT32 iMaxTemplateSize)
	Create an SPTemplate object from an SPreference object.
SPINT32 __cdecl	SPTemplateCreateFromSmartcard (pSPTEMPLATE_T *ppTemplate, pSPSMARTCARD_T pSmartcard)
	Create an SPTemplate by loading data from a smart card represented by an SPSmartcard object.
SPINT32 __cdecl	SPTemplateDelOptionId (pSPTEMPLATE_T pTemplate, SPINT32 iId)
	Delete by ID an optional parameter (option) of an SPTemplate object.
SPINT32 __cdecl	SPTemplateFree (pSPTEMPLATE_T *ppTemplate)
	Deallocate an SPTemplate object.
SPINT32 __cdecl	SPTemplateFreeImage (SPUCHAR **ppImage)
	Deallocate a bitmap created by SPTemplateGetImage.
SPINT32 __cdecl	SPTemplateFreeOption (pSPTEMPLATE_T pTemplate, char **ppOptionString)
	Deallocate a string created by SPTemplateGetOption or SPTemplateGetOptionId.
SPINT32 __cdecl	SPTemplateGetImage (pSPTEMPLATE_T pTemplate, SPDOUBLE dZoom, SPINT32 iImageFormat, SPUCHAR **ppbImage, SPINT32 *piImageLength)
	Create a bitmap from the signature contained in an SPTemplate object.
SPINT32 __cdecl	SPTemplateGetImageSize (pSPTEMPLATE_T pTemplate, SPINT32 *piWidth, SPINT32 *piHeight)
	Get the size of an image for the signature contained in an SPTemplate object.
SPINT32 __cdecl	SPTemplateGetOption (pSPTEMPLATE_T pTemplate, SPINT32 iIndex, int *piOptionType, SPVPTR *plValue)
	Get an optional parameter (option) from an SPTemplate object.
SPINT32 __cdecl	SPTemplateGetOptionId (pSPTEMPLATE_T pTemplate, SPINT32 iId, int *piOptionType, SPVPTR *plValue)
	Get an optional parameter (option) by ID from an SPTemplate object.
SPINT32 __cdecl	SPTemplateGetSignature (pSPTEMPLATE_T pTemplate, pSPSIGNATURE_T *ppSignature)
	Create an SPSignature object from an SPTemplate object.

---

Function Documentation

SPINT32 __cdecl SPTemplateAddOption (  pSPTEMPLATE_T  pTemplate, SPINT32  iOptionType, SPVPTR  lValue )

Add an optional parameter (option) to an SPTemplate object. Parameters: pTemplate  [i] pointer to an SPTemplate object. iOptionType  [i] data type of the option's value: SP_TEMPLATE_OPTION_STR string SP_TEMPLATE_OPTION_INT signed 32-bit integer SP_TEMPLATE_OPTION_SHORT signed 16-bit integer SP_TEMPLATE_OPTION_BYTE signed 8-bit integer lValue  [i] value of the option. The value must be cast to SPVPTR, but will be interpreted according to the data type specified by iOptionType. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateAddOptionId, SPTemplateGetOption

SPINT32 __cdecl SPTemplateAddOptionId (  pSPTEMPLATE_T  pTemplate, SPINT32  iOptionType, SPINT32  iId, SPVPTR  lValue )

Add an optional parameter (option) with ID to an SPTemplate object. Parameters: pTemplate  [i] pointer to an SPTemplate object. iOptionType  [i] data type of the option's value: SP_TEMPLATE_OPTION_STR string SP_TEMPLATE_OPTION_INT signed 32-bit integer SP_TEMPLATE_OPTION_SHORT signed 16-bit integer SP_TEMPLATE_OPTION_BYTE signed 8-bit integer iId  [i] identifier for the option, an integer in the range 0 through 65535. Identifiers in the range 0 through 1024 are reservered for Kofax. The identifier must be unique within the template. If an option having the specified ID already exists, that option will be overwritten with the new one. lValue  [i] value of the option. The value must be cast to SPVPTR, but will be interpreted according to the data type specified by iOptionType. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateGetOptionId, SPTemplateDelOptionId

SPINT32 __cdecl SPTemplateClone (  pSPTEMPLATE_T  pTemplate, pSPTEMPLATE_T *  ppTemplate )

Create a copy of an SPTemplate object. Parameters: pTemplate  [i] pointer to the SPTemplate object to be copied. ppTemplate  [o] pointer to a variable that will be filled with a pointer to a new SPTemplate object. The caller is responsible for deallocating the new object by calling SPTemplateFree. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter SP_MEMERR out of memory Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPFlatFileFree

SPINT32 __cdecl SPTemplateCreateFromFlatFile (  pSPTEMPLATE_T *  ppTemplate, const SPUCHAR *  pbFlatFile, SPINT32  iFlatFileLength )

Create a new SPTemplate object from a flat file object. This function deserializes an SPTemplate object serialized by SPFlatFileCreateFromTemplate. Parameters: ppTemplate  [o] pointer to a variable that will be filled with a pointer to a new SPTemplate object. The caller is responsible for deallocating the new object by calling SPTemplateFree. pbFlatFile  [i] pointer to an array of bytes containing a serialized SPTemplate object. iFlatFileLength  [i] length (in bytes) of the serialized data pointed to by pbFlatFile. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter SP_MEMERR out of memory Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateCreateFromReference, SPTemplateCreateFromSmartcard, SPFlatFileCreateFromTemplate, SPTemplateFree

SPINT32 __cdecl SPTemplateCreateFromReference (  pSPTEMPLATE_T *  ppTemplate, pSPREFERENCE_T  pReference, SPINT32  iMaxTemplateSize )

Create an SPTemplate object from an SPreference object. The parameter iMaxTemplateSize limits the template size but reduces resolution when too small. It typically ranges from 2 KByte to 10 KByte, depending on limitations that may arise, e.g., from maximum available space on a smart card. Parameters: pReference  [i] pointer to an SPReference object. iMaxTemplateSize  [i] maximum size of the serialized (flat file) representation of the SPTemplate object. ppTemplate  [o] pointer to a variable that will be filled with a pointer to a new SPTemplate object. The caller is responsible for deallocating the new object by calling SPTemplateFree. Returns: SP_NOERR on success, else error code: SP_DYNAMICERR error in dynamic engine SP_PARAMERR invalid parameter SP_MEMERR out of memory Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateCreateFromFlatFile, SPTemplateCreateFromSmartcard, SPTemplateCreateFromTemplate, SPTemplateFree Todo: Actually implement iMaxTemplateSize.

SPINT32 __cdecl SPTemplateCreateFromSmartcard (  pSPTEMPLATE_T *  ppTemplate, pSPSMARTCARD_T  pSmartcard )

Create an SPTemplate by loading data from a smart card represented by an SPSmartcard object. Parameters: ppTemplate  [o] pointer to a variable that will be filled with a pointer to a new SPTemplate object. The caller is responsible for deallocating the new object by calling SPTemplateFree. pSmartcard  [i] pointer to an SPSmartcard object. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter SP_SMARTCARDERR a smart card driver error occured Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM) See also: SPTemplateCreateFromFlatFile, SPTemplateCreateFromReference, SPTemplateFree, SPSmartcardLoadTemplate, SPSmartcardSaveTemplate

SPINT32 __cdecl SPTemplateDelOptionId (  pSPTEMPLATE_T  pTemplate, SPINT32  iId )

Delete by ID an optional parameter (option) of an SPTemplate object. Parameters: pTemplate  [i] pointer to an SPTemplate object. iId  [i] identifier of the option to be deleted, an integer in the range 0 through 65535. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter SP_MEMERR out of memory Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateAddOptionId

SPINT32 __cdecl SPTemplateFree (  pSPTEMPLATE_T *  ppTemplate  )

Deallocate an SPTemplate object. The SPTemplate object must have been allocated by SPTemplateClone, SPTemplateCreateFromFlatFile, SPTemplateCreateFromReference, SPTemplateCreateFromSmartcard, or SPSmartcardLoadTemplate. Parameters: ppTemplate  [io] pointer to a variable containing a pointer to an SPTemplate object. The variable will be set to NULL if this function succeeds. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)

SPINT32 __cdecl SPTemplateFreeImage (  SPUCHAR **  ppImage  )

Deallocate a bitmap created by SPTemplateGetImage. Parameters: ppImage  [io] pointer to a variable containing a pointer to a bitmap. The bitmap must have been created by SPTemplateGetImage. The variable will be set to NULL if this function succeeds. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateGetImage

SPINT32 __cdecl SPTemplateFreeOption (  pSPTEMPLATE_T  pTemplate, char **  ppOptionString )

Deallocate a string created by SPTemplateGetOption or SPTemplateGetOptionId. The string must have been allocated by SPTemplateGetOption or SPTemplateGetOptionId. Parameters: pTemplate  [i] pointer to the SPTemplate object from which the string has been retrieved, currently not used. ppOptionString  [io] pointer to a variable containing a pointer to a string. The variable will be set to NULL if this function succeeds. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateGetOption, GetOptionId

SPINT32 __cdecl SPTemplateGetImage (  pSPTEMPLATE_T  pTemplate, SPDOUBLE  dZoom, SPINT32  iImageFormat, SPUCHAR **  ppbImage, SPINT32 *  piImageLength )

Create a bitmap from the signature contained in an SPTemplate object. Parameters: pTemplate  [i] pointer to an SPTemplate object. dZoom  [i] the zoom factor (must be positive). iImageFormat  [i] desired format of the bitmap: SP_IMAGE_GIF SP_IMAGE_CCITT4 SP_IMAGE_TIFF SP_IMAGE_BMP_WIN Flags that can be added with the `|' operator: SP_IMAGE_BLACKWHITE SP_IMAGE_BLACKWHITE_1BPP SP_IMAGE_CROSSED SP_DONT_RENDER_METAFONT SP_DONT_RENDER_DIRECT ppbImage  [o] pointer to a variable that will be filled with a pointer to an array of bytes containing the bitmap. The caller is responsible for deallocating that array of bytes by calling SPTemplateFreeImage. piImageLength  [o] pointer to a variable that will be filled with the length (in bytes) of the bitmap returned via ppbImage. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter SP_MEMERR out of memory Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateFreeImage, SPSignatureGetImage, SPReferenceGetImage

SPINT32 __cdecl SPTemplateGetImageSize (  pSPTEMPLATE_T  pTemplate, SPINT32 *  piWidth, SPINT32 *  piHeight )

Get the size of an image for the signature contained in an SPTemplate object. The actual image might be slightly bigger than predicted by this function. Parameters: pTemplate  [i] pointer to an SPTemplate object. piWidth  [o] pointer to a variable that will be filled with the width (in pixels) of the image. piHeight  [o] pointer to a variable that will be filled with the height (in pixels) of the image. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateGetImage Todo: Compute the exact size of the image.

SPINT32 __cdecl SPTemplateGetOption (  pSPTEMPLATE_T  pTemplate, SPINT32  iIndex, int *  piOptionType, SPVPTR *  plValue )

Get an optional parameter (option) from an SPTemplate object. This function can be used for enumerating all the options of a template. Parameters: pTemplate  [i] pointer to an SPTemplate object. iIndex  [i] zero-based index of the option to be retrieved. Options added with either SPTemplateAddOption or SPTemplateAddOptionId can be retrieved. The numbering of options need not reflect the order in which they have been added. piOptionType  [o] pointer to a variable that will be filled with the data type of the option's value: 0 the option does not exist SP_TEMPLATE_OPTION_STR string SP_TEMPLATE_OPTION_INT signed 32-bit integer SP_TEMPLATE_OPTION_SHORT signed 16-bit integer SP_TEMPLATE_OPTION_BYTE signed 8-bit integer plValue  [o] pointer to a variable that will be filled with the value of the selected option. The value is cast to SPVPTR and is to be interpreted according to the data type returned via piOptionType. If the data type of the option is SP_TEMPLATE_OPTION_STR, the application will be responsible for deallocating the string by calling SPTemplateFreeOption. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter SP_MEMERR out of memory Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateAddOption, SPTemplateAddOptionId, SPTemplateFreeOption

SPINT32 __cdecl SPTemplateGetOptionId (  pSPTEMPLATE_T  pTemplate, SPINT32  iId, int *  piOptionType, SPVPTR *  plValue )

Get an optional parameter (option) by ID from an SPTemplate object. Parameters: pTemplate  [i] pointer to an SPTemplate object. iId  [i] identifier of the option to be retrieved, an integer in the Identifiers in the range 0 through 1024 are reservered for Kofax. piOptionType  [i] pointer to a variable that will be filled with the data type of the option's value: 0 the option does not exist SP_TEMPLATE_OPTION_STR string SP_TEMPLATE_OPTION_INT signed 32-bit integer SP_TEMPLATE_OPTION_SHORT signed 16-bit integer SP_TEMPLATE_OPTION_BYTE signed 8-bit integer plValue  [o] pointer to a variable that will be filled with the value of the selected option. The value is cast to a void pointer and is to be interpreted according to the data type returned via piOptionType. If the data type of the option is SP_TEMPLATE_OPTION_STR, the application will be responsible for deallocating the string by calling SPTemplateFreeOption. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter SP_MEMERR out of memory Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateAddOptionId, SPTemplateDelOptionId, SPTemplateFreeOption

SPINT32 __cdecl SPTemplateGetSignature (  pSPTEMPLATE_T  pTemplate, pSPSIGNATURE_T *  ppSignature )

Create an SPSignature object from an SPTemplate object. This is a convenience function that behaves exactly like SPSignatureCreateFromTemplate. Parameters: pTemplate  [i] pointer to an SPTemplate object. ppSignature  [o] pointer to a variable that will be filled with a pointer to a new SPSignature object. The caller is responsible for deallocating the new object by calling SPSignatureFree. Returns: SP_NOERR on success, else error code: SP_PARAMERR invalid parameter SP_MEMERR out of memory Operating Systems: Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64) See also: SPTemplateGetImage, SPSignatureCreateFromTemplate