ACS AET65 Application Programming Interface Download Page 1

Page: 1 / 84

Application Programming Interface

idvation GmbH

Otto-Hesse-Straße 19 / T5

Phone +49 6151 9926567

D-64293 Darmstadt

Fax +49 6151 3689296

[email protected]

www.idvation.com

Application Programming Interface

AET65
Fingerprint Reader

Summary of Contents for AET65

Page 1: ...rogramming Interface idvation GmbH Otto Hesse Stra e 19 T5 Phone 49 6151 9926567 D 64293 Darmstadt Fax 49 6151 3689296 info idvation com www idvation com Application Programming Interface AET65 Finger...

Page 2: ...tion comTitle Here Page 2 of 84 Revision History Version Date Prepared By Description of Changes 1 0 August 6 2010 Melissa Balmes Based on UPEK s BSAPI Reference Manual Changed document filename to AP...

Page 3: ...11 3 2 4 ABSOpen 12 3 2 5 ABSClose 13 3 2 6 ABSEnumerateDevices 13 3 2 7 ABSGetDeviceProperty 14 3 2 8 ABSFree 14 3 3 Biometric Functions 15 3 3 1 ABSEnroll 15 3 3 2 ABSVerify 16 3 3 3 ABSVerifyMatch...

Page 4: ...or Biometric and Image Grabbing Functions ABS_FLAG_xxxx 54 6 4 Template Purpose Constants ABS_PURPOSE_xxxx 55 6 5 Key Constants for ABS_PROFILE_DATA ABS_PKEY_xxxx 56 6 6 ABS_PKEY_IMAGE_FORMAT Values A...

Page 5: ...DATE 82 8 3 Image Grabbing Functions 83 8 3 1 Constant ABS_FLAG_HIGH_RESOLUTION 83 8 3 2 Structure ABS_IMAGE 83 8 3 3 New Grabbing Functions 83 8 4 Global Parameter ABS_PARAM_POWER_SAVE_CHECK_KEYBOARD...

Page 6: ...e follows the PC SC API standards For information on the smart card reader module please refer to the AET65 Smart Card Reader Reference Manual document REF_AET65_v1 0 The purpose of this document is t...

Page 7: ...PI BSAPI does not require any framework to use it BSAPI will provide more functionality comparing to BioAPI so more biometric and miscellaneous features of our devices will be available e g navigation...

Page 8: ...agement of the device quality assurance and other policies This allows users of BSAPI to concentrate on application logic and not sink into low level details Future versions of BioAPI BSP will be rede...

Page 9: ...ect user s interaction with FM All these functions are collectively called interactive operations in this document Interactive operation functions share the way how the interaction is achieved All tho...

Page 10: ...rts the last scan as not being latent There are two ways how to perform the anti latent checking The first one is built in high level biometric operations enrollment and verification I e calling ABSEn...

Page 11: ..._STATUS_OK 0 means success 3 2 2 ABSInitializeEx ABS_STATUS ABSInitializeEx IN ABS_DWORD dwFlags Description Initialize the BSAPI library BSAPI must be initialized before you can call any other functi...

Page 12: ...ld be closed with ABSClose Return Value ABS_STATUS Result code ABS_STATUS_OK 0 means success Remarks To close the connection you should call ABSClose To open a connection through USB no extra paramete...

Page 13: ...of ABSOpen should be paired with a call to ABSClose 3 2 6 ABSEnumerateDevices ABS_STATUS ABSEnumerateDevices IN const ABS_CHAR pszEnumDsn OUT ABS_DEVICE_LIST ppDeviceList Description Enumerate current...

Page 14: ...on Handle to the connection to FM dwPropertyld One of ABS_DEVPROP_xxxx constants specifying what device property the caller is interested in ppPropertyData Address of a pointer which will be set to po...

Page 15: ...tion IN ABS_OPERATION pOperation OUT ABS_BIR ppEnrolledTemplate IN ABS_DWORD dwFlags Description Scan the live finger process it into a fingerprint template and return it to the caller Parameters hCon...

Page 16: ...will be stored The result is indexed into the pTemplateArray determining the matching template or 1 if no template matches dwFlags Bitmask specifying flags which modify slightly behavior of the functi...

Page 17: ...lledTemplate The first template to be compared In the most common situation when a template with enrollment purpose is being matched with a template with another purpose the enrollment template has to...

Page 18: ...owed Note that calling ABSCapture with dwPurpose set to ABS_PURPOSE_ENROLL is obsolete and it is functionally equivalent to calling ABSEnroll ppCapturedTemplate Pointer which is set to newly allocated...

Page 19: ...with global parameter ABS_PARAM_LATENT_CHECK so you should not call this function after ABSVerify and ABSEnroll after calling those functions assuming the global parameter ABS_PARAM_LATENT_CHECK is tu...

Page 20: ...ation is not supported by the device ABS_STATUS_NOT_SUPPORTED is returned Please note there are few very old legacy devices where the navigation support is broken With these devices the function never...

Page 21: ...ant and ABS_IFMT_xxxx constants for more details Functions ABSGrabImage and ABSRawGrabImage require that you describe the desired image format in a form of ABS_IMAGE_FORMAT structure You can get list...

Page 22: ...ion 1 0 idvation GmbH Otto Hesse Stra e 19 T5 Phone 49 6151 9926567 D 64293 Darmstadt Fax 49 6151 3689296 info idvation com www idvation com Page 22 of 84 Page 22 of 84 Return Value ABS_STATUS Result...

Page 23: ...are device specific Various device models tune various aspects of the grab operations to various degree Please prefer ABSGrab or ABSGrabImage whenever possible Unlike ABSGrab this function waits for...

Page 24: ...that requested image format ABS_PKEY_IMAGE_FORMAT is always interpreted in the strict way i e the caller has to know which image formats are supported by the FM he uses Return Value ABS_STATUS Result...

Page 25: ...epeated until an image of some minimal quality is provided Parameters hConnection Handle to the connection to FM pOperation See description of ABS_OPERATION dwPurpose A value indicates a purpose of th...

Page 26: ...BSGrab or ABSGrabImage whenever possible Unlike ABSGrabImage this function waits for just one swipe and ends even if the resulting image has low quality The caller can use the output parameters to fur...

Page 27: ...o the degree possible i e those which are not supported by the device are silently ignored In contrast if flag ABS_FLAG_STRICT_PROFILE is set the profile data is interpreted in a more strict way and t...

Page 28: ...d from callback to cancel operation which called the callback It is the only way how to cancel interactive operations which have OperationID set to zero See description of member OperationID of struct...

Page 29: ...S_STATUS ABSSetSessionParameter IN ABS_CONNECTION hConnection IN ABS_DWORD dwParamID IN ABS_DATA pParamValue Description Sets value of session wide parameter These settings influence behavior of certa...

Page 30: ...ABS_PARAM_xxxx constants pParamValue Output parameter for the retrieved value The function sets it to point to newly allocated ABS_DATA Use ABSFree to release the memory See description of ABS_PARAM_...

Page 31: ...ion 1 0 idvation GmbH Otto Hesse Stra e 19 T5 Phone 49 6151 9926567 D 64293 Darmstadt Fax 49 6151 3689296 info idvation com www idvation com Page 31 of 84 Page 31 of 84 Return Value ABS_STATUS Result...

Page 32: ...D dwParamID OUT ABS_DATA ppParamValue Description Retrieves value of global wide parameter Parameters dwParamID ID of the parameter to retrieve See description of ABS_PARAM_xxxx constants pParamValue...

Page 33: ...whether they are or are not supported are device dependent dwLED1 Parameter defining the detailed behavior of the 1st LED This parameter is mode specific For the manual mode dwMode 0 the value is int...

Page 34: ...ABSGetLED IN ABS_CONNECTION hConnection OUT ABS_DWORD dwMode OUT ABS_DWORD dwLED1 OUT ABS_DWORD dwLED2 Description This function allows the application to query the state and behavior of the two user...

Page 35: ...at the conversion can be taken in place or to newly allocated image structure depending if you set the parameter ppBinarizedImage to NULL or not Parameters pGrayScaleImage Pointer to the input gray sc...

Page 36: ...ut this is set to point to a buffer containing zero terminated string with textual message If no message is provided it points to empty string so the caller does not need check it for NULL The buffer...

Page 37: ...ck void ABSDefaultCallback IN const ABS_OPERATION pOperation IN ABS_DWORD dwMsgID IN void pMsgData Description Default BSAPI callback implementation It provides default implementation of callback whic...

Page 38: ...inter to the structure passed in through ABS_OPERATION structure remains valid until the biometric operation is over typedef struct abs_default_callback_context ABS_DWORD Version HWND ParentWindow ABS...

Page 39: ...2 bytes unsigned short ABS_WORD typedef Signed integer type 4 bytes int ABS_LONG typedef Unsigned integer type 4 bytes insigned int ABS_DWORD typedef Boolean value zero non zero int ABS_BOOL typedef R...

Page 40: ...mportant impacts The template has exactly same binary representation when stored to some storage or database so they may be used on all platforms despite byte order the platform uses When using values...

Page 41: ...esents a fingerprint template but potentially can contain other data as well e g audit data BIR consists of a header followed by the opaque data and optionally by a signature This type is binary compa...

Page 42: ...to zero you can cancel the operation only from its callback passing a zero as the parameter for ABSCancelOperation Context User defined pointer passed into the operation callback BSAPI does not interp...

Page 43: ...Profile key It can be any constant ABS_PKEY_xxxx Value Value key dependent 5 2 6 ABS_SWIPE_INFO This structure provides various information about the swipe from ABSRawGrab ABSGrabImage or ABSRawGrabI...

Page 44: ...disabled MsgId is set to ABS_MSG_PROCESS_SUCCESS If any quality check failed the value is set to the most important relevant callback message ID see constants ABS_MSG_QUALITY_xxxx Flags Bitmask indica...

Page 45: ...sensor subsamples the scanned image or when the information about sub sampling is not available for the given piece of hardware typedef struct abs_image_format ABS_WORD ScanResolutionH ABS_WORD ScanR...

Page 46: ...alDPI ABS_DWORD VerticalDPI ABS_BYTE ImageData ABS_VARLEN ABS_IMAGE Description Width Width of the image in pixels Height Height of the image in pixels ColorCount Maximal color count of the image Hori...

Page 47: ...k of an interactive operation typedef struct abs_process_begin_data ABS_DWORD ProcessID ABS_DWORD Step ABS_DWORD StepCount ABS_PROCESS_BEGIN_DATA Description Process ID ID of process stage See ABS_PRO...

Page 48: ...ssed template Can be NULL if no template is associated with the message 5 2 13 ABS_NAVIGATION_DATA This structure is a container for additional data associated with ABS_MSG_NAVIGATE_CHANGE message sen...

Page 49: ..._LIST The format of the data returned by ABSEnumerateDevices it contains info about all enumerated devices Please note that the real output parameter from ABSEnumerateDevices has variable length array...

Page 50: ...Otto Hesse Stra e 19 T5 Phone 49 6151 9926567 D 64293 Darmstadt Fax 49 6151 3689296 info idvation com www idvation com Page 50 of 84 Page 50 of 84 5 2 16 ABS_CALLBACK void ABS_CALLBACK IN const ABS_OP...

Page 51: ...swipe so user has time to see the bad quality feedback However this default behavior might not be desired in some other scenarios For example if the callback implementation writes every message to a n...

Page 52: ...x 49 6151 3689296 info idvation com www idvation com Page 52 of 84 Page 52 of 84 dwMsgData ID of message See description of ABS_MSG_xxxx constants pMsgData Pointer to data with additional information...

Page 53: ...is used only local devices can be opened regardless whether ABS_INIT_FLAG_FORCE_LOCAL_SENSOR flag is or is not used ABS_INIT_FLAG_FORCE_LOCAL_SENSOR 0x2 Forces BSAPI to ignore remote sessions and alw...

Page 54: ...tion If used the verification is automatically restarted when the user s swipe does not match any template in a provided template set Only function ABSVerify supports this flag See documentation of th...

Page 55: ...ocessing For example enrollment usually requires a higher template quality so built in biometric tests for template quality are stricter when ABS_PURPOSE_ENROLL is specified Please notice that the def...

Page 56: ...lems are ignored during the swipe and thus they are not sent to callback You can still retrieve some information about scan quality in form of ABS_SWIPE_INFO structure When set to zero scanning qualit...

Page 57: ...he best image When set to zero the calibration tuning is disabled ABS_PKEY_REC_DIGITAL_GAIN 8 This value is used for digital image enhancement The value determines a factor of digital image enhancemen...

Page 58: ...D 50 ABS_PKEY_REC_NOISE_ROBUSTNESS_TRIGGER 16 Specifies noise robustness trigger It determines how many consecutive bad swipes triggers noise robustness Zero means no triggering by bad swipes Default...

Page 59: ...20 Sensor security mode It specifies whether and how are encrypted communication data sent between the FM sensor and chipset or computer which processes them It can be set to any ABS_PVAL_SSM_xxxx co...

Page 60: ...he device was calibrated Especially low power modes may require calibration Therefore the information in the table below what FM models support which format is only for basic orientation ABS_PVAL_IFMT...

Page 61: ...with 3 4 sub sampling 381 x 381 DPI 8 bits pixel This mode internally uses the 508 x 254 scanning which supports faster finger movements at the cost of lower image quality Supported by ESS and TCD 50...

Page 62: ...l Sub sampling is done directly by the sensor using its native 381 scanning format Supported by ESS 2 2 with TCS3C and newer sensors and by TCD 50 ABS_PVAL_IFMT_381_381_8_LP 22 Grab the whole finger w...

Page 63: ...bits pixel Image is internally scanned using format 381 254 4 Supported only by some variants of SONLY ABS_PVAL_IFMT_381_381_8_BINARIZED_SCAN381_254_4 33 Grab the whole finger with 3 4 sub sampling e...

Page 64: ...would be longer than maximal allowed length only beginning of the image from the start on is returned ABS_PVAL_RTP_FINGERTIP 1 Fingertip image reconstruction termination policy If the scanned image w...

Page 65: ...2 Auto detection at the beginning of the swipe ABS_PVAL_SWIPEDIR_STANDARD_WARN 3 Standard swipe direction with warning If backward swipe is detected message ABS_MSG_QUALITY_BACKWARD is sent to callbac...

Page 66: ...of ABS_PKEY_SENSOR_SECURITY_MODE for more information ABS_PVAL_SSM_DISABLED 0 Sensor security mode is disabled ABS_PVAL_SSM_ENCRYPT 1 Sensor security is set to encryption mode ABS_PVAL_SSM_SIGN_ALL 2...

Page 67: ...ipes too fast the device is not able to process all the data ABS_SWIPE_FLAG_TOO_SKEWED 0x02 The swipe was too skewed ABS_SWIPE_FLAG_BACKWARDS_MOVEMENT 0x04 Swipe was in wrong direction Note that this...

Page 68: ...3 ABS_MSG_PROCESS_BEGIN ProcessID ABS_PROCESS_CAPTURE 4 ABS_MSG_PROCESS_BEGIN ProcessID ABS_PROCESS_GRAB 5 messages leading the user to correctly swipe his finger 6 ABS_MSG_PROCESS_END end of ABS_PRO...

Page 69: ...oot process of navigation ABSNavigate It typically consists of one sub process of type ABS_PROCESS_CONSOLIDATED_CAPTURE ABS_PROCESS_ENROLL 2 Root process of enrollment ABSEnroll It is typically compos...

Page 70: ...0 of 84 Page 70 of 84 ABS_PROCESS_MATCH 8 Process of matching template against set of templates ABS_PROCESS_GRAB 9 Process of sample image grab from scanner It s relatively low level process retrievin...

Page 71: ...es composing the identification If not supported by FM no output ABS_DATA are allocated and NULL is passed out ABS_DEVPROP_FIRMWARE_VARIANT 2 Identifies firmware variant Output ABS_DATA contains 4 byt...

Page 72: ...nt and 5 are supported ABS_PARAM_CONSOLIDATION_TYPE 2 Determines type of consolidation I e how multiple templates are mixed together to get one high quality template See description of parameter ABS_P...

Page 73: ...pecific error occurs with device e g communication error caused by ESD BSAPI automatically attempts to restore communication session with the device This parameter specifies maximal amount of time BSA...

Page 74: ...NT service compatible mode i e unless it is initialized with function ABSInitializeEx with flag ABS_INIT_FLAG_NT_SERVICE set If BSAPI is in NT service compatible mode the default value is zero Note th...

Page 75: ...d ABS_CONSOLIDATION_CONVENIENT 1 Convenient consolidation algorithm is used Similar to ABS_CONSOLIDATION_NORMAL policy with relaxed criteria for image template acceptance for entering the enrollment p...

Page 76: ...BS_MSG_PROCESS_BEGIN and ABS_MSG_PROCESS_END Between the two some other messages including nested sub process can arrive See description of ABS_PROCESS_xxxx constants for more information about the op...

Page 77: ...message before ABS_MSG_PROCESS_END Depending on the particular process nature it can use ABS_MSG_PROCESS_SUCCESS or ABS_MSG_PROCESS_FAILURE before ABS_MSG_PROCESS_END but some other processes do not c...

Page 78: ...ould center his finger on the sensor and press harder pMsgData is always NULL ABS_MSG_QUALITY_CENTER 0x31100000 Swipe quality is low User should center his finger on the sensor pMsgData is always NULL...

Page 79: ...quality is low The swipe is too skewed pMsgData is always NULL ABS_MSG_QUALITY_TOO_DARK 0x35000000 Swipe quality is low The swipe is too dark pMsgData is always NULL ABS_MSG_QUALITY_BACKWARD 0x3600000...

Page 80: ...ould be shown pMsgData is always NULL ABS_MSG_DLG_HIDE 0x52000000 Notifies that the feedback dialog should be hidden pMsgData is always NULL ABS_MSG_IDLE 0x0 Special message which gives the callback a...

Page 81: ...US_ALREADY_INITIALIZED 5003 BSAPI is not initialized ABS_STATUS_NOT_INITIALIZED 5004 Connection is already opened ABS_STATUS_ALREADY_OPENED 5005 Invalid parameter ABS_STATUS_INVALID_PARAMETER 5006 Inv...

Page 82: ...nger scan and the process finishes when BSAPI evaluates quality of the fingerprint template as sufficient This change required several changes in the API 8 2 1 Global Parameter ABS_PARAM_CONSOLIDATION...

Page 83: ...he template itself i e the member Data of ABS_BIR structure All internal template types are always preceded by ABS_BIR_HEADER when returned from BSAPI and also the ABS_BOR_HEADER preceding the data is...

Page 84: ...Services and Citrix This support is not yet included in current BSAPI version but there are some new aspects of BSAPI in order to make the change in the future smoother The support when implemented sh...

Search results

Summary of Contents for AET65

Reviews:

Related manuals for AET65

Brands by name

Popular brands

ACS AET65, Application Programming Interface

Search results

Summary of Contents for AET65

Reviews:

Related manuals for AET65

Brands by name

Popular brands