visit Kofax web site

SPReference.h File Reference


Detailed Description

SignWare Dynamic Development toolkit, reference object.

Author:
uko
An SPReference object is a collection of signature objects forming a signature reference. SPReference objects can be used to create a flat file to save a signature or reference to disk or to a database, or to compare a reference against a signature, or to create a template object (compressed flat file format optimized for smart cards).

Use SPReferenceCreate, SPReferenceCreateFromFlatFile, SPReferenceCreateFromFlatFile3, SPReferenceCreateFromGuiAcqu, or SPReferenceCreateFromTellerImage to create an SPReference object.


Defines

#define SP_REFERENCE_CHECK_SIGNATURES   "SPReferenceCheckSignatures"
 Check all signatures included in a reference.
#define SP_REFERENCE_MAX_DURATION   "SPReferenceMaxDuration"
 Maximum duration to enter all signatures within a reference.
#define SP_REFERENCE_MIN_DYNAMIC_QUALITY   "SPReferenceMinDynamicQuality"
 Minimum dynamic quality of a reference.
#define SP_REFERENCE_MIN_MATCH   "SPReferenceMinMatch"
 Variance of a reference.
#define SP_REFERENCE_MIN_SIGNATURES   "SPReferenceMinSignatures"
 Minimum number of signatures contained in a reference.

Functions

SPINT32 __cdecl SPReferenceAddSignature (pSPREFERENCE_T *ppReference, pSPSIGNATURE_T pSignature)
 Add a signature to an SPReference object.
SPINT32 __cdecl SPReferenceCheck (pSPREFERENCE_T pReference, pSPPROPERTYMAP_T pParams)
 Check a reference.
SPINT32 __cdecl SPReferenceClone (pSPREFERENCE_T pReference, pSPREFERENCE_T *ppReference)
 Create a copy of an SPReference object.
SPINT32 __cdecl SPReferenceCreate (pSPREFERENCE_T *ppReference)
 Create a new SPReference object.
SPINT32 __cdecl SPReferenceCreateFromAcquire (pSPREFERENCE_T *ppReference, pSPACQUIRE_T pSPAcquire)
 Create an SPReference object from the result of a signature acquiry.
SPINT32 __cdecl SPReferenceCreateFromFlatFile (pSPREFERENCE_T *ppReference, const SPUCHAR *pbFlatFile, SPINT32 iFlatFileLength)
 Create a new SPReference object from a flat file object.
SPINT32 __cdecl SPReferenceCreateFromFlatFile3 (pSPREFERENCE_T *ppReference, const SPUCHAR *pbFlatFile, SPINT32 iFlatFileLength, SPINT32 iFlags)
 Create a new SPReference object from a flat file object.
SPINT32 __cdecl SPReferenceCreateFromGuiAcqu (pSPREFERENCE_T *ppReference, pSPGUIACQU_T pSPGuiAcqu)
 Create an SPReference object from the result of a signature acquiry.
SPINT32 __cdecl SPReferenceCreateFromTellerImage (pSPREFERENCE_T *ppReference, pSPTELLERIMAGE_T pTellerImage)
 Create an SPReference object from an SPTellerImage object.
SPINT32 __cdecl SPReferenceFree (pSPREFERENCE_T *ppReference)
 Deallocate an SPReference object.
SPINT32 __cdecl SPReferenceFreeImage (SPUCHAR **ppbImage)
 Deallocate a bitmap created by SPReferenceGetImage or SPReferenceGetImage2.
SPINT32 __cdecl SPReferenceGetDynamicQuality (pSPREFERENCE_T pReference, SPINT32 *piResult)
 Get the quality of the dynamic features of the signatures contained in an SPReference object.
SPINT32 __cdecl SPReferenceGetImage (pSPREFERENCE_T pReference, SPDOUBLE dZoom, SPINT32 iImageFormat, SPINT32 iIndex, SPUCHAR **ppbImage, SPINT32 *piImageLength)
 Create a bitmap from a signature stored in an SPReference object.
SPINT32 __cdecl SPReferenceGetImage2 (pSPREFERENCE_T pReference, SPDOUBLE dZoom, SPINT32 iImageFormat, SPINT32 iIndex, pSPTICKET_T pTicket, SPUCHAR **ppbImage, SPINT32 *piImageLength)
 Create a bitmap from a signature stored in an SPReference object.
SPINT32 __cdecl SPReferenceGetImageSize (pSPREFERENCE_T pReference, SPINT32 iIndex, SPINT32 *piWidth, SPINT32 *piHeight)
 Get the size of an image for a signature of an SPReference object.
SPINT32 __cdecl SPReferenceGetSignatureCount (pSPREFERENCE_T pReference, SPINT32 *piNrSignatures)
 Get the number of signatures contained in an SPReference object.
SPINT32 __cdecl SPReferenceGetStaticQuality (pSPREFERENCE_T pReference, SPINT32 iIndex, SPINT32 *piResult)
 Get the quality of the static features of a signature contained in an SPReference object.
SPINT32 __cdecl SPReferenceGetVariance (pSPREFERENCE_T pReference, SPINT32 *piVariance)
 Check the variance of the signatures contained in an SPReference object.
SPINT32 __cdecl SPReferenceGetVarianceEx (pSPREFERENCE_T pReference, SPINT32 iQuality, SPINT32 *piVariance)
 Check the variance of the signatures contained in an SPReference object.
SPINT32 __cdecl SPReferenceMirrorY (pSPREFERENCE_T pReference)
 Mirror a reference vertically.


Define Documentation

#define SP_REFERENCE_CHECK_SIGNATURES   "SPReferenceCheckSignatures"
 

Check all signatures included in a reference.

See also:
SPReferenceCheck

#define SP_REFERENCE_MAX_DURATION   "SPReferenceMaxDuration"
 

Maximum duration to enter all signatures within a reference.

See also:
SPReferenceCheck

#define SP_REFERENCE_MIN_DYNAMIC_QUALITY   "SPReferenceMinDynamicQuality"
 

Minimum dynamic quality of a reference.

See also:
SPReferenceCheck

#define SP_REFERENCE_MIN_MATCH   "SPReferenceMinMatch"
 

Variance of a reference.

See also:
SPReferenceCheck

#define SP_REFERENCE_MIN_SIGNATURES   "SPReferenceMinSignatures"
 

Minimum number of signatures contained in a reference.

See also:
SPReferenceCheck


Function Documentation

SPINT32 __cdecl SPReferenceAddSignature pSPREFERENCE_T ppReference,
pSPSIGNATURE_T  pSignature
 

Add a signature to an SPReference object.

Note:
The SPReference object may move in memory. If you have multiple pointers to the SPReference object, you have to update all of them.
Parameters:
ppReference [io] pointer to variable containing a pointer to an SPReference object. The SPReference object may move in memory, therefore the variable may be updated by this function.
pSignature [i] pointer to an SPSignature object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceCreate, SPReferenceGetSignatureCount, SPSignatureCreateFromReference

SPINT32 __cdecl SPReferenceCheck pSPREFERENCE_T  pReference,
pSPPROPERTYMAP_T  pParams
 

Check a reference.

Reference plausibility check. A reference should have a min static and dynamic quality and a max variance.

Parameters:
pReference [i] pointer to an SPReferrence object.
pParams [i] Parameters, may be NULL
Returns:
int result, SP_NOERR on success, SP_INVALIDERR if check failed, else error code
  • SP_PARAMERR an invalid parameter was passed
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a)
See also:
SPSignatureCheck

SPINT32 __cdecl SPReferenceClone pSPREFERENCE_T  pReference,
pSPREFERENCE_T ppReference
 

Create a copy of an SPReference object.

Parameters:
pReference [i] pointer to the SPReference object to be copied.
ppReference [o] pointer to a variable that will be filled with a pointer to a new SPReference object. The caller is responsible for deallocating the new object by calling SPReferenceFree.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceCreate, SPReferenceFree

SPINT32 __cdecl SPReferenceCreate pSPREFERENCE_T ppReference  ) 
 

Create a new SPReference object.

Typically, SPReferenceAddSignature is used after calling this function to add signatures to the new SPReference object.

Parameters:
ppReference [o] pointer to a variable that will be filled with a pointer to a new SPReference object. The caller is responsible for deallocating the new object by calling SPReferenceFree.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceAddSignature, SPReferenceCreateFromFlatFile, SPReferenceCreateFromFlatFile3, SPReferenceCreateFromGuiAcqu, SPReferenceCreateFromTellerImage, SPReferenceFree

SPINT32 __cdecl SPReferenceCreateFromAcquire pSPREFERENCE_T ppReference,
pSPACQUIRE_T  pSPAcquire
 

Create an SPReference object from the result of a signature acquiry.

The returned reference may contain a single signature (in this case a signature was captured), or multiple signatures (when a true reference was captured). It is the responsability of the application to convert the reference to a signature if the returned object includes a single signature.

Parameters:
ppReference [o] pointer to a variable that will be filled with a pointer to a new SPReference object. The caller is responsible for deallocating the new object by calling SPReferenceFree.
pSPAcquire [i] pointer to an SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPReferenceCreate, SPReferenceCreateFromTellerImage, SPReferenceFree, SPGuiAcquGetReference

SPINT32 __cdecl SPReferenceCreateFromFlatFile pSPREFERENCE_T ppReference,
const SPUCHAR pbFlatFile,
SPINT32  iFlatFileLength
 

Create a new SPReference object from a flat file object.

This function deserializes an SPReference object serialized by SPFlatFileCreateFromReference.

SPReferenceCreateFromFlatFile() is equivalent to SPReferenceCreateFromFlatFile3() with a value of zero for iFlags unless overridden by environment variable SIGNWARE_ISO_LOAD.

The value of that environment variable is either a decimal number or a hexadecimal number (prefixed by "0x"). The number will be shifted left 20 bits, that is, the following values (and combinations thereof) are defined:

Parameters:
ppReference [o] pointer to a variable that will be filled with a pointer to a new SPReference object. The caller is responsible for deallocating the new object by calling SPReferenceFree.
pbFlatFile [i] pointer to an array of bytes containing a serialized SPReference object.
iFlatFileLength [i] length (in bytes) of the serialized data pointed to by pbFlatFile.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceCreate, SPReferenceCreateFromFlatFile3, SPReferenceCreateFromGuiAcqu, SPReferenceCreateFromTellerImage, SPReferenceFree, SPFlatFileCreateFromReference

SPINT32 __cdecl SPReferenceCreateFromFlatFile3 pSPREFERENCE_T ppReference,
const SPUCHAR pbFlatFile,
SPINT32  iFlatFileLength,
SPINT32  iFlags
 

Create a new SPReference object from a flat file object.

This function deserializes an SPReference object serialized by SPFlatFileCreateFromReference.

This function does not use environment variable SIGNWARE_ISO_LOAD.

Parameters:
ppReference [o] pointer to a variable that will be filled with a pointer to a new SPReference object. The caller is responsible for deallocating the new object by calling SPReferenceFree.
pbFlatFile [i] pointer to an array of bytes containing a serialized SPReference object.
iFlatFileLength [i] length (in bytes) of the serialized data pointed to by pbFlatFile.
iFlags [i] flags modifying the behavior of this function:
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceCreate, SPReferenceCreateFromFlatFile, SPReferenceCreateFromGuiAcqu, SPReferenceCreateFromTellerImage, SPReferenceFree, SPFlatFileCreateFromReference3

SPINT32 __cdecl SPReferenceCreateFromGuiAcqu pSPREFERENCE_T ppReference,
pSPGUIACQU_T  pSPGuiAcqu
 

Create an SPReference object from the result of a signature acquiry.

The returned reference may contain a single signature (in this case a signature was captured), or multiple signatures (when a true reference was captured). It is the responsability of the application to convert the reference to a signature if the returned object includes a single signature.

Parameters:
ppReference [o] pointer to a variable that will be filled with a pointer to a new SPReference object. The caller is responsible for deallocating the new object by calling SPReferenceFree.
pSPGuiAcqu [i] pointer to an SPGuiAcqu object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPReferenceCreate, SPReferenceCreateFromTellerImage, SPReferenceFree, SPGuiAcquGetReference

SPINT32 __cdecl SPReferenceCreateFromTellerImage pSPREFERENCE_T ppReference,
pSPTELLERIMAGE_T  pTellerImage
 

Create an SPReference object from an SPTellerImage object.

Parameters:
ppReference [o] pointer to a variable that will be filled with a pointer to a new SPReference object. The caller is responsible for deallocating the new object by calling SPReferenceFree.
pTellerImage [i] pointer to an SPTellerImage object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPReferenceCreate, SPReferenceCreateFromFlatFile, SPReferenceCreateFromFlatFile3, SPReferenceCreateFromGuiAcqu, SPReferenceFree, SPTellerImageCreateFromReference

SPINT32 __cdecl SPReferenceFree pSPREFERENCE_T ppReference  ) 
 

Deallocate an SPReference object.

The SPReference object must have been created by SPReferenceCreate, SPReferenceCreateFromFlatFile, SPReferenceCreateFromFlatFile3, SPReferenceCreateFromGuiAcqu, SPReferenceCreateFromTellerImage, SPReferenceClone, or SPGuiAcquGetReference.

Parameters:
ppReference [io] pointer to a variable containing a pointer to an SPReference object. The variable will be set to NULL if this function succeeds.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceCreate, SPReferenceCreateFromFlatFile, SPReferenceCreateFromFlatFile3, SPReferenceCreateFromGuiAcqu, SPGuiAcquGetReference

SPINT32 __cdecl SPReferenceFreeImage SPUCHAR **  ppbImage  ) 
 

Deallocate a bitmap created by SPReferenceGetImage or SPReferenceGetImage2.

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

SPINT32 __cdecl SPReferenceGetDynamicQuality pSPREFERENCE_T  pReference,
SPINT32 piResult
 

Get the quality of the dynamic features of the signatures contained in an SPReference object.

Parameters:
pReference [i] pointer to an SPReference object.
piResult [o] pointer to a variable that will be filled with the quality (in percent) of the dynamic features of the signatures.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a)
See also:
SPReferenceGetStaticQuality

SPINT32 __cdecl SPReferenceGetImage pSPREFERENCE_T  pReference,
SPDOUBLE  dZoom,
SPINT32  iImageFormat,
SPINT32  iIndex,
SPUCHAR **  ppbImage,
SPINT32 piImageLength
 

Create a bitmap from a signature stored in an SPReference object.

Parameters:
pReference [i] pointer to an SPReference object.
dZoom [i] the zoom factor (must be positive).
iImageFormat [i] desired format of the bitmap: Flags that can be added with the `|' operator:
iIndex [i] zero-based index of the signature within the reference.
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 SPReferenceFreeImage.
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:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceGetImage2, SPReferenceFreeImage, SPSignatureGetImage, SPTemplateGetImage

SPINT32 __cdecl SPReferenceGetImage2 pSPREFERENCE_T  pReference,
SPDOUBLE  dZoom,
SPINT32  iImageFormat,
SPINT32  iIndex,
pSPTICKET_T  pTicket,
SPUCHAR **  ppbImage,
SPINT32 piImageLength
 

Create a bitmap from a signature stored in an SPReference object.

Parameters:
pReference [i] pointer to an SPReference object.
dZoom [i] the zoom factor (must not exceed 1.0).
iImageFormat [i] desired format of the bitmap: Flags that can be added with the `|' operator:
iIndex [i] zero-based index of the signature within the reference.
pTicket [i] pointer to an SPTicket object. The ticket must have been charged for usage SP_TICKET_RENDER. You can pass NULL if no ticket is to be used.
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 SPReferenceFreeImage.
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:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceGetImage, SPReferenceFreeImage, SPSignatureGetImage, SPTemplateGetImage, SPTicketCharge

SP_TICKET_RENDER

SPINT32 __cdecl SPReferenceGetImageSize pSPREFERENCE_T  pReference,
SPINT32  iIndex,
SPINT32 piWidth,
SPINT32 piHeight
 

Get the size of an image for a signature of an SPReference object.

The actual image might be slightly bigger than predicted by this function.

Parameters:
pReference [i] pointer to an SPReference object.
iIndex [i] zero-based index of the signature within the reference.
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:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceGetImage, SPReferenceGetImage2
Todo:
Compute the exact size of the image.

SPINT32 __cdecl SPReferenceGetSignatureCount pSPREFERENCE_T  pReference,
SPINT32 piNrSignatures
 

Get the number of signatures contained in an SPReference object.

Parameters:
pReference [i] pointer to an SPReference object.
piNrSignatures [o] pointer to a variable that will be filled with the number of signatures contained in the SPReference object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a), Darwin (x86_64)
See also:
SPReferenceCreate, SPReferenceAddSignature, SPSignatureCreateFromReference

SPINT32 __cdecl SPReferenceGetStaticQuality pSPREFERENCE_T  pReference,
SPINT32  iIndex,
SPINT32 piResult
 

Get the quality of the static features of a signature contained in an SPReference object.

Parameters:
pReference [i] pointer to an SPReference object.
iIndex [i] Zero-based index of the signature to test.
piResult [o] pointer to a variable that will be filled with the quality (in percent) of the static features of the signature.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a)
See also:
SPReferenceGetDynamicQuality, SPReferenceGetSignatureCount

SPINT32 __cdecl SPReferenceGetVariance pSPREFERENCE_T  pReference,
SPINT32 piVariance
 

Check the variance of the signatures contained in an SPReference object.

This function is equivalent to SPReferenceGetVarianceEx with 80 being passed for iQuality.

Parameters:
pReference [i] pointer to an SPReference object.
piVariance [o] pointer to a variable that will be filled with the value 1 (variance of the signatures is acceptable) or 0 (the variance of the signatures is too big).
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a)
See also:
SPReferenceGetVarianceEx

SPINT32 __cdecl SPReferenceGetVarianceEx pSPREFERENCE_T  pReference,
SPINT32  iQuality,
SPINT32 piVariance
 

Check the variance of the signatures contained in an SPReference object.

SPReferenceGetVarianceEx calculates the variance based on a static compare of all embedded signatures against each other (the match rate of each single signature comparison must exceed iQuality)

Parameters:
pReference [i] pointer to an SPReference object.
iQuality [i] variance quality level, 0 through 100, typically 80.
piVariance [o] pointer to a variable that will be filled with the value 1 (variance of the signatures is acceptable) or 0 (the variance of the signatures is too big).
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a)
See also:
SPReferenceGetVariance

SPINT32 __cdecl SPReferenceMirrorY pSPREFERENCE_T  pReference  ) 
 

Mirror a reference vertically.

The reference is mirrored such that for each signature the range of Y coordinates is not changed.

Parameters:
pReference [i] pointer to an SPReference object.
Returns:
int result, SP_NOERR on success, else error code:
  • SP_PARAMERR an invalid parameter was passed
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM), Android (ARMv7a)