Information Security ID Module Software Development Kit (SDK

Information Security

ID Module Software

Development Kit (SDK)

Programmer’s Guide

Programmer’s Guide 1.05 Issued: 07.00

This Programmer’s Guide is subject to change without notice.

Important: For further information please contact:

MB fingerMetrica GmbH

Tel.: +49 – (0)9094 – 9210298

Fax: +49 – (0)9094 – 9210299

e-mail: [email protected]

Published by MB fingerMetrica GmbH

Bgm.-Templer-Ring 9, 86703 Rögling

© MB fingerMetrica GmbH 2000. All Rights Reserved.

FingerTIPTM is a registered trademark of Infineon Technologies AG.

ID Module SDK V1.05

MB fingerMetrica GmbH 3/103 Programmer's Guide V1.05 (07.00)

Contents

1 INTRODUCTION................................................................................................................................................... 6

1.1 VALIDITY OF THIS MANUAL................................................................................................................................... 6

1.2 RELATIONSHIP TO OTHER DOCUMENTS................................................................................................................. 6

1.3 TARGET GROUP..................................................................................................................................................... 6

1.4 STRUCTURE OF THE MANUAL................................................................................................................................ 7

2 ARCHITECTURE OF THE ID MODULE SDK SOFTWARE PACKAGE..................................................... 8

3 INSTALLATION, STARTUP AND MAINTENANCE..................................................................................... 10

3.1 SYSTEM REQUIREMENTS ..................................................................................................................................... 10

3.2 INSTALLATION INSTRUCTIONS ............................................................................................................................. 10

3.3 REGISTRY ENTRIES.............................................................................................................................................. 11

4 HANDLING OF THE ID MODULE SDK FUNCTIONS ................................................................................. 16

4.1 RETURN VALUES AND DEALING WITH EXCEPTIONS ............................................................................................ 16

4.1.1 ID Module Interface.................................................................................................................................. 16

4.1.2 Firmware file ............................................................................................................................................ 20

4.1.3 Registry entries ......................................................................................................................................... 20

4.1.4 Serial interface.......................................................................................................................................... 24

4.1.5 Interface parameter .................................................................................................................................. 25

4.1.6 Identification ID Module .......................................................................................................................... 27

4.1.7 Enumeration, Enrollment.......................................................................................................................... 27

4.1.8 System ....................................................................................................................................................... 27

4.2 REQUEST AND FREEING OF OBJECTS, CALL BACK............................................................................................... 29

4.3 DATA MODEL AND EXTERNAL DATA STRUCTURES............................................................................................. 30

4.3.1 Format of Serialized Data ........................................................................................................................ 30

4.3.2 Data Structures ......................................................................................................................................... 31

5 DETAILED DESCRIPTION OF THE ID MODULE SDK FUNCTIONS...................................................... 50

5.1 ID MODULE MANAGEMENT FUNCTIONS .............................................................................................................. 51

5.1.1 Function FAPIAcquireDevice................................................................................................................... 51

5.1.2 Function FAPIReleaseDevice................................................................................................................... 52

5.1.3 Function FAPIConfigIDModule ............................................................................................................... 52

5.1.4 Function FAPIChangeIDModuleOperationMode .................................................................................... 53

5.1.5 Function FAPIChangeIDModulePassword.............................................................................................. 54

5.1.6 Function FAPIReadConfigIDModule....................................................................................................... 55

5.1.7 Function FAPISelfTest.............................................................................................................................. 56

5.1.8 Function FAPIStateIDModule.................................................................................................................. 57

5.1.9 Function FAPIStateIDModuleFlash......................................................................................................... 57

5.1.10 Function FAPILoadFirmware .................................................................................................................. 58

5.2 BIOMETRIC FUNCTIONS ....................................................................................................................................... 58

5.2.1 Function FAPILiveIdentifyPerson ............................................................................................................ 58

5.2.2 Function FAPIExtractBioData ................................................................................................................. 60

5.2.3 Function FAPIEnrollment ........................................................................................................................ 61

5.3 ARCHIVE MANAGEMENT FUNCTIONS ................................................................................................................... 62

5.3.1 Function FAPIAcquireArchive ................................................................................................................. 63

5.3.2 Function FAPIReleaseArchive.................................................................................................................. 63

5.3.3 Function FAPIDeletePerson..................................................................................................................... 64

5.3.4 Function FAPIDeleteReferenceFromPerson ............................................................................................ 65

5.3.5 Function FAPIDeleteArchive.................................................................................................................... 66

5.3.6 Function FAPIGetPerson ......................................................................................................................... 67

5.3.7 Function FAPIGetPersonData ................................................................................................................. 68

ID Module SDK V1.05


5.3.8 Function FAPIGetReferenceFromPerson................................................................................................. 69

5.3.9 Function FAPIEnumPerson...................................................................................................................... 70

5.3.10 Function FAPIEnumPersonData.............................................................................................................. 70

5.3.11 Function FAPIEnumReferenceFromPerson ............................................................................................. 72

5.3.12 Function FAPIChangePersonData........................................................................................................... 73

5.3.13 Function FAPIAppendPerson................................................................................................................... 74

5.3.14 Function FAPIGetPersonID ..................................................................................................................... 75

5.4 TOOLS FUNCTIONS............................................................................................................................................... 75

5.4.1 Function FAPICreateDeviceConfiguration.............................................................................................. 75

5.4.2 Function FAPIUpdateConfigurationFromModule ................................................................................... 76

5.4.3 Function FAPIDeleteDeviceConfiguration .............................................................................................. 77

5.4.4 Function FAPISerialize ............................................................................................................................ 78

5.4.5 Function FAPIDeserialize ........................................................................................................................ 79

5.4.6 Function FAPIFreeSerialized................................................................................................................... 79

5.4.7 Function FAPIGetErrorText..................................................................................................................... 80

5.4.8 Function FAPIFree................................................................................................................................... 80

6 SCENARIOS FOR DEALING WITH ID MODULE CONFIGURATIONS................................................... 81

6.1 SCENARIO 1: NEW OR UNKNOWN ID MODULE MUST BE ACCESSED..................................................................... 81

6.2 SCENARIO 2: REGISTRY CONFIGURATION TO BE OVERWRITTEN BY FIRMWARE CONFIGURATION......................... 82

6.3 SCENARIO 3: FIRMWARE CONFIGURATION TO BE OVERWRITTEN BY REGISTRY CONFIGURATION......................... 82

6.4 SCENARIO 4: APPLICATION CHANGES THE CONFIGURATIONS BY OWN MEANS ..................................................... 83

6.5 SCENARIO 5: APPLICATION CHANGES THE UART CONFIGURATIONS BY OWN MEANS .......................................... 84

7 LITERATURE ...................................................................................................................................................... 86

8 TERMS .................................................................................................................................................................. 87

9 ABBREVIATIONS ............................................................................................................................................... 89

THE EXAMPLE CODE ................................................................................................................................................ 90

ID Module SDK V1.05


Document Management

History of changes

Version Status Date Reason for Change

V1.00 Invalid 05.00 ID Module SDK V1.00

V1.05 Released 07.00 ID Module SDK V1.05.

Added new Errorcodes based on [2]

ID Module SDK V1.05


1 Introduction

The ID Module SDK is the part of the ID Module SDK Software Package, that enables integration

of the Siemens ID Module into any end-user application. The ID Module SDK contains functions to

communicate with the ID Module via RS232 interface.

The main focus of the ID Module SDK Software Package Programmer's Guide is on programming

with the ID Module SDK. The ID Module SDK Software Package Programmer's Guide gives a

complete introduction to programming biometric software applications with the SIEMENS

biometric system. The functions of the ID Module SDK are fully explained: all components are

described in detail with respect to their functioning, calling parameters, results and interfaces.

Installation and deinstallation descriptions of the ID Module SDK Software Package V1.05 are

given in this manual as well. In contrast to the ID Module SDK User's Guide, special attention is

paid to the registry entries performed by the product.

The manual contains

Installation instructions and deinstallation instructions,

• Handling of the ID Module SDK functions,

• Complete description of the ID Module SDK functions, and

• Implementation issues of the ID Module SDK demo program.

1.1 Validity of this Manual

This manual was written for the ID Module SDK Software Package V1.05, and is valid only for this

product and its components: the ID Module SDK and the ID Module SDK demo program.

1.2 Relationship to Other Documents

This Programmer's Guide is intended to provide a thorough understanding especially of the

functions available in the ID Module SDK. An exact definition of each function's behavior is given

with respect to its input and output parameters, its behavior as well as existing error codes.

The User's Guide provides useful information about the philosophy of the whole ID Module SDK

Software Package. Additionally, a thorough description of the ID Module SDK Software Package's

demo program and a rough description of all callable ID Module SDK functions is presented in the

ID Module SDK Software Package document.

The ID Module Interface is described in [2].

1.3 Target Group

The ID Module SDK Software Package Programmer's Guide is written for all programmers and

system integrators who use the ID Module SDK Software Package to build generic fingerprint

biometrics or integrate biometric security into existing applications. Familiarity with the operating

system Windows 95, Windows 98, Windows NT 4.0 , Windows 2000 and C programming is

assumed, whereas no special knowledge of biometric algorithms is needed.

ID Module SDK V1.05


1.4 Structure of the Manual

Chapter 2 gives an overview of the ID Module SDK Software Package and its architecture. Chapter

3 explains the installation and startup of the product with a special focus on the registry entries.

Chapters 4 and 5 are especially important for application programmers. Chapter 4 gives an overview

of the function handling in the ID Module SDK. Herein error codes and messages as well as

external data structures are defined. Chapter 5 represents the main part of this Programmer's Guide

by giving and gives a complete description of all ID Module SDK functions. Chapter 6 covers

implementation issues of the ID Module SDK Software Package component "Demo Program".

Chapter 7, 8, 9 and 10 contain a list of related documents, definitions of terms and abbreviations as

well as an index.

ID Module SDK V1.05


2 Architecture of the ID Module SDK Software Package

The ID Module SDK Software Package is designed to support the integration of biometric

identification systems into various applications. Therefore, the ID Module SDK is a powerful tool

for component manufacturers as well as application programmers of high-level biometric

applications.

The ID Module SDK does not only enable the integration of biometric security based on fingerprints

into any end-user application, but also provides direct ID Module access.

A rough overview of biometrics and the SIEMENS biometric algorithms for fingerprint recognition

as implemented in the ID Module SDK is given in the ID Module SDK User's Guide.

This chapter gives a broad overview of the architecture of the ID Module SDK. Some of the basic

characteristics of the ID Module SDK are summarized here:

• Biometric and general processing functions are clearly distinguished. This results from strictly

following a modular software concept. Additionally, functions of the ID Module SDK are sub-

divided into components.

• All dependencies regarding external interfaces of the ID Module SDK functions are

encapsulated. This makes dealing with the functions easy for the programmer and user of the ID

Module SDK.

In addition to the ID Module SDK, the ID Module SDK Software Package also includes a demo

program and an example code.

The demo program demonstrates all functions of the ID Module SDK. The basic functions of the

demo program of ID Module SDK serve to aid visualization, and show the usage of the biometric

algorithms. Furthermore, the ID Module SDK demo program is an interactive program with a

Windows user interface. This is provided as an exe file without sources.

The example code – in form of well in-line documented C source-code – which is provided with

the ID Module SDK Software Package serves to illustrate the basic function calls of the ID Module

SDK.

ID Module SDK V1.05


ID Module SDK

RS232

FAPI

Setup

Example Code

FAPI

Demoprogram

Figure 2-1:

Block Level View of ID Module SDK

ID Module SDK V1.05


3 Installation, Startup and Maintenance

3.1 System Requirements

The following resources are necessary for using the ID Module SDK Software Package. The user

can develop new biometric PC applications, integrate biometric features into an existing PC

application with the ID Module SDK, or simply use the ID Module SDK demo.

Hardware requirements:

• PC, Intel Pentium Processor, min. 133 MHz, monitor with minimal resolution 800*600, main

storage min. 32 MB

• TopSec ID Module

Software requirements:

• Operating system Windows 95, Windows 98, Windows NT 4.0 or Windows 2000

• Microsoft Visual C++ 6.0 as development tool

3.2 Installation Instructions

By double-clicking on the executable ’Setup’, the installation wizard is started. The ID Module SDK

User's Guide provides a thorough description of the installation procedure. In the following sections

supplemental information is given.

The ‘Setup’ copies all files and data of the ID Module SDK Software Package into the selected

installation root directory. The default setting for this directory is C:\Program Files\IDModuleSDK

.

Figure 3-1 shows the directory structure created by the installation process.

It also denotes the components of the ID Module SDK Software Package, which are:

• ID Module SDK

• ID Module SDK demo program

• ID Module SDK example code and

• ID Module SDK documentation

In this diagram a shaded background indicates directories, whereas files are white.

ID Module SDK V1.05


Installation

directory

SDK demo sample doc

idmodule.lib

Export Library

idmodule.dll

ID Module SDK

idmodule.h

Export Header File

idmodule_demo.exeDemo Program

idmodule.dll

ID Module SDK

idmodule_bsp.cC- Sample Code

ProgrammersGuide

User Guideidmodule.bas

Visual Basic

readme.txt

Figure 3-1:

Directory structure of the installation

3.3 Registry Entries

Entries in the Windows registry are made using the path:

HKEY_LOCAL_MACHINE\<configpath>\<key>\Name

ID Module specific entries (one set of entries for each managed ID Module in subkeys of

HKEY_LOCAL_MACHINE\<configpath>\<module>. <configpath> corresponds to

FAPIConfigurationPath and <module> corresponds to FAPIModuleName. Both parameters are used

as parameters of particular FAPI functions to denote a specific ID Module.

The “Timeouts” section is an exception because it is a subdirectory positioned directly beneath the

registry root.

( path: HKEY_LOCAL_MACHINE\<configpath>\Timeouts )

This section is valid for all modules belonging to this particular registry root.

Name <key> value Comment

0x1101 Timeouts Type: DWORD Timeout in ms for the command

ID Module SDK V1.05


Name <key> value Comment

Default: 5000 “Connect”

0x1102 Timeouts Type: DWORD

Default: 5000

Timeout in ms for the command

“GetModuleStatus”


Default: 5000


“SetModuleConfig”


Default: 5000


“GetModuleConfig”


Default: 5000


“GetFlashStatus”

0x1106 Type: DWORD

Default: 5000


“ModuleSelfTest”


Default: 5000


“StartFwDownload”


Default: 5000


“ResumeFwCode”


Default: 5000


“ResumeFwCheckSum”


Default: 5000

Timeout in ms for the command “

OnlineIdentify ”


Default: 5000


“OnlineEncode”


Default: 5000


“StartEnroll”


Default: 5000


“ResumeEnrollFinger”


Default: 5000


“ResumeEnrollPerson”


Default: 5000


“AddPerson”


Default: 5000


“GetPerson”


Default: 5000


“DeletePerson”


Default: 5000


“ChangePersonData”


Default: 5000


“GetPersonID”

ID Module SDK V1.05


name <module>/

<key>

value comment

BuildNumber Version Type: REG_SZ

Default: “1450“

For internal use only

VersionNumber Version Type: REG_SZ

Default: “1.05“

For internal use only

SerialNumber Identity Type: REG_BINARY

Default: 0 for unset”

Contains the serial number of the specified ID

Module and corresponds to

FAPIStateResponse.dModuleId

Default: dModuleId[Index] = 0

Index=0..3

The default value is a reserved value to denote the

state “unset”

ConnectionID Identity Type: DWORD

Default: 0 for “unset”

Range: 0 .. 255

For internal use only -

0 means a value reserved to denote the state

“unset”.

PersonDataSize Archive Type: DWORD

Default: 256

Range: 128, 256, 512, 1024,

2048, 4096, 8192, 16384

Corresponds to FAPIArchiveConfigData.dPerson-

DataSize

Values must be exact powers of 2

CountEncodedFP Archive Type: DWORD

Default: 3

Range: 1..5

Corresponds to

FAPIArchiveConfigData.dCount-

EncodedFP

IdentificationMode Identification Type: DWORD

Default: 0

Range: 0..1

Corresponds to FAPIIdentificationMode

Values:

0 full identification

1 fast identification

MatchSecurityMode Identification Type: DWORD

Default: 2

Range: 0..2

Corresponds to FAPIMatchSecurityMode

Values:

0 low security level

1 medium security level

2 high security level

CaptureMode Sensor Type: DWORD

Default: 0

Range: 0..1

Corresponds to FAPICaptureMode

Values:

0 single mode

1 trigger mode

DynamicMode Sensor Type: DWORD

Default: 1

Range: 0..1

Corresponds to FAPIDynamicMode

Values:

0 low dynamic

ID Module SDK V1.05


name <module>/

<key>

value comment

1 high dynamic

Line1Delay Release Type: DWORD

Default: 0

Corresponds to

FAPIReleaseConfigData.dLine1Delay

Sets delay timeout in milliseconds for Line 1 /

Release 1

Line1Duration Release Type: DWORD

Default: 100

Corresponds to

FAPIReleaseConfigData.dLine1Duration

Sets duration timeout in milliseconds for Line 1 /

Release 1

Line2Delay Release Type: DWORD

Default: 0

Corresponds to

FAPIReleaseConfigData.dLine2Delay

Sets delay timeout in milliseconds for Line 2 /

Release 2

Line2Duration Release Type: DWORD

Default: 100

Corresponds to

FAPIReleaseConfigData.dLine2Duration

Sets duration timeout in milliseconds for Line 2 /

Release 2

BaudMnt Uart Type: DWORD

Default: 57600

Range: 9600

19200

57600

115200

Corresponds to

FAPIUartConfigData.dBaudMnt

Baudrate for connection ID Module ID Module

SDK

BaudAci Uart Type: DWORD

Default: 9600

Range: 0 (Autobaud)

9600

19200

57600

115200

Corresponds to

FAPIUartConfigData.dBaudAci

ComPort Uart Type: REG_SZ

Default: “COM1”

Range: “COM1”

”COM2”

...

Serial Port for connection ID Module ID Module

SDK

OperationMode Module

Security

Type: DWORD

Default: 0

Range: 0x0000

0x0001

0x0002

0x0003

0x00FF

Corresponds to FAPIModuleOperationMode

Values:

0 Fully host controlled operation

1 Host controlled with enrollment

2 Host controlled without enrollment

3 Encoder mode

FF Autonomous mode

IdleTimeout PowerMgmt Type: DWORD Corresponds to

ID Module SDK V1.05


name <module>/

<key>

value comment

Default: 5000 FAPIPowerMgmtConfigData.dActive-ToIdle

Sets timeout in milliseconds

OffTimeout PowerMgmt Type: DWORD

Default: 30000

Corresponds to

FAPIPowerMgmtConfigData.dIdleToOff

Sets timeout in milliseconds

Table 3-1: Registry entries invoked by the function “FAPICreateDeviceConfiguration”

The user may manually edit the entries in the registry. This is possible by typing “redt32”in the DOS

command line under NT 4.0 and “regedit” under Windows 95 / 98 / 2000.

ID Module SDK V1.05


4 Handling of the ID Module SDK Functions

In the following sections, the behavior of the functions of the ID Module SDK is described. One

feature characterizing the functions’ behavior are their return values. However, the end-user

application decides what reaction is triggered by a specific return value. Additionally, general ID

Module SDK function dependencies and the data structures defined for all input parameters of the

ID Module SDK functions are discussed in this chapter.

4.1 Return Values and Dealing with Exceptions

ID Module SDK error information is described in the form of error codes. In the case of an internal

error, the respective error number is transferred a return value to the calling program. A properly

terminated function, however, returns a zero.

Every calling function can either transfer this error number to its calling function or react to the

error number. The error number finally is passed to the application via the FAPI-Control-Interface.

A respective error message can be retrieved by calling the function "FAPIGetErrorText" with the

number generating the error.

The following table (table 4-1) denotes all return values used by the ID Module SDK functions.

Table 4-1 represents the error codes returned by FAPIFunctions

Name of Error Code Number Short Explanation

FAPI_OK 0 General return value, if the

executing function is terminated

without errors; this error code is

expected from each FAPIFunction.

4.1.1 ID Module Interface

The following error codes correspond to the error codes defined in [2].


FAPI_IDMODULE_LEAD_DYNAMIC_LOW 0xC2021080 "LEAD wasn't able to encode

recorded fingerprint due to

insufficient dynamic of the

fingerprint. Possible problem: No

finger on sensor."

FAPI_IDMODULE_LEAD_INVALID_PIXEL 0xC2021081 "LEAD wasn't able to encode

ID Module SDK V1.05



recorded fingerprint because of

too many invalid pixels in the

recorded fingerprint. Possible

problem: Sensor damaged."

FAPI_IDMODULE_LEAD_AREA_COVERED_LO

W 0xC2021082 "LEAD wasn't able to encode

recorded fingerprint because the

area covered by the recorded

fingerprint was too small. Possible

problem: Finger coverage in-

sufficient."

FAPI_IDMODULE_LEAD_DENSITY_LOW 0xC2021084 "LEAD wasn't able to encode

recorded fingerprint because the

density of the fingerprint was too

low. Possible problem: Dry finger

or finger coverage insufficient."

FAPI_IDMODULE_LEAD_MINUTIA_COUNT_L

OW 0xC2021083 "LEAD wasn't able to encode

recorded fingerprint because count

of extracted minutiae was too low.

Possible problem: Finger coverage

insufficient."

FAPI_IDMODULE_LEAD_MINUTIA_COUNT_HI

GH 0xC2021085 "LEAD wasn't able to encode

recorded fingerprint because count

of extracted minutiae was too

high."

FAPI_IDMODULE_LEAD_NOT_RUNNING 0xC202F001 "The command couldn't be

executed because the LEAD is not

running."

FAPI_IDMODULE_LEAD_NO_RESPONSE 0xC202F002 "The command couldn't be

executed because the LEAD is not

responding."

FAPI_IDMODULE_LEAD_ENCODE_ERROR 0xC202F003 "Fatal system error during the

encoding process."

FAPI_IDMODULE_LEAD_MATCH_ERROR 0xC202F004 "Fatal system error during the

matching process."

FAPI_IDMODULE_SENSOR_RESET 0xC203F001 "An error occurred while resetting

the sensor. Possible problem:

Sensor damaged."

FAPI_IDMODULE_SENSOR_READ 0xC203F002 "An error occurred while reading

the sensor. Possible problem:

Sensor damaged."

FAPI_IDMODULE_SENSOR_LINE_END_MARK 0xC203F003 "Checking line end mark failed.

Possible problem: Sensor

damaged."

ID Module SDK V1.05



FAPI_IDMODULE_FLASH_RESET 0xC204F002 "An error occured while reseting

the flash memory."

FAPI_IDMODULE_FLASH_RESET 0xC204F001 "An error occured while writing

into the flash memory."

FAPI_IDMODULE_AR_ARCHIVE_CREATION_F

AILED 0xC4010001 "The ID Module couldn't create an

archive in the Flash Memory."

FAPI_IDMODULE_AR_ARCHIVE_ALREADY_P

RESENT 0xC4010002 "The ID Module couldn't create an

archive in the Flash Memory due

to a pre-existing archive."

FAPI_IDMODULE_AR_NO_ARCHIVE_EXISTIN

G 0xC4010003 "No archive exists in the ID

Module's Flash Memory."

FAPI_IDMODULE_AR_PERSON_ALREADY_EX

ISTING 0xC4010004 "The requested person has already

been stored in the ID Module's

Flash Memory."

FAPI_IDMODULE_AR_PERSON_NOT_FOUND

0xC4010006 "The requested person isn't stored

in the ID Module's Flash

Memory."

FAPI_IDMODULE_AR_REFERENCE_ALREADY

_EXISTING 0xC4010007 "The requested reference for a

person is already stored in the ID


FAPI_IDMODULE_AR_REFERENCE_NOT_FOU

ND 0xC4010008 "The requested reference for a

person isn't stored in the ID


FAPI_IDMODULE_CMD_INVALID_COMMAND 0xC6000001 "The requested command is un-

known."

FAPI_IDMODULE_CMD_ENROLLMENT_ACTIV

E 0xC6000002 "Command failed. The enrollment

process is active."

FAPI_IDMODULE_CMD_INVALID_PARAMETE

R 0xC6000003 "The parameters provided by the

command are invalid."

FAPI_IDMODULE_CMD_INVALID_CAPTURE_

MODE 0xC6000004 "Invalid capture mode."

FAPI_IDMODULE_CMD_ENROLLMENT_NOT_

ACTIVE 0xC6000005 "Command failed. The processing

of a command failed because the

enrollment process was not started

with the command ‘StartEnroll’."

FAPI_IDMODULE_CMD_ACCESS_DENIED 0xC6000006 "A request to change the

ModuleSecurity failed due to a

missing or invalid parameter."

FAPI_IDMODULE_CMD_INVALID_CID 0xC6100110 "Invalid Connection ID. Check ID

Module."

ID Module SDK V1.05



FAPI_IDMODULE_CMD_INVALID_CHECKSUM 0xC61001F1 "The checksum of the firmware

code is invalid"

FAPI_IDMODULE_CMD_INVALID_CHECKSUM

_TYPE 0xC61001F0 "The checksum type of the

firmware code is invalid."

FAPI_IDMODULE_CMD_INVALID_CODE_SIZE 0xC61001E1 "The size of the firmware code is

invalid."

FAPI_IDMODULE_CMD_INVALID_CODE_TYP

E 0xC61001E0 "The type of the firmware code is

not valid."

FAPI_IDMODULE_CMD_INVALID_CFGFLAG

0xC6100130 "Invalid FAPIConfigFlag."

FAPI_IDMODULE_CMD_INVALID_ARCHIVE_C

FG 0xC6100132 "Invalid FAPIArchiveConfigData

structure entries."

FAPI_IDMODULE_CMD_INVALID_IDENTIFY_

CFG 0xC6100133 "Invalid FAPIIdentConfigData

structure entries."

FAPI_IDMODULE_CMD_INVALID_SENSOR_CF

G 0xC6100134 "Invalid FAPISensorConfigData

structure entries."

FAPI_IDMODULE_CMD_INVALID_RELEASE_C

FG 0xC6100135 "Invalid FAPIReleaseConfigData

structure entries."

FAPI_IDMODULE_CMD_INVALID_UART_CFG 0xC6100136 "The entries in the UartConfig

structure are not valid."

FAPI_IDMODULE_CMD_INVALID_MODULE_M

ODE 0xC6100137 "Invalid

FAPIModuleOperationMode."

FAPI_IDMODULE_CMD_INVALID_POWER_CF

G 0xC6100138 "Invalid

FAPIPowerMgmtConfigData

structure entries."

FAPI_IDMODULE_CMD_INVALID_POWER_CF

G 0xC6100139 "The password is invalid."

FAPI_IDMODULE_CMD_INVALID_TESTFLAG 0xC6100160 "Invalid FAPITestFlag."

FAPI_IDMODULE_CMD_NO_MATCH 0xC6200210 Note: This errorcode is mapped to

FAPI_OK and FAPI_Result is set

to FAPI_UNKNOWN

FAPI_IDMODULE_CMD_INVALID_PERSONID 0xC6400401 "FAPIPersonID out of range.

Check specification."

FAPI_IDMODULE_CMD_INVALID_REFERENC

EID 0xC6400402 "FAPIPerfenceID out of range.

Check specification.

FAPI_IDMODULE_CMD_INVALID_REQUEST

0xC6400403 "Fatal system error.

FAPI_IDMODULE_CMD_INVALID_PERSON_D

ATA 0xC6400404 "Invalid person specific data."

ID Module SDK V1.05



FAPI_IDMODULE_CMD_INVALID_REFERENC

E 0xC6400410 "Invalid reference."

FAPI_IDMODULE_CMD_LAST_REFERENCE 0xC6400430 "The requested reference wasn't

deleted because there is only one

reference stored for the person in

the ID Module. Call

‘FAPIDeletePerson’ to delete the

person."

FAPI_IDMODULE_CMD_RESUME_ENROLL_PE

RSON_EXPECTED 0xC68004E0 "Fatal system error. Resume

Enroll person expected"

FAPI_IDMODULE_CMD_INVALID_RESUMEFL

AG 0xC68004E1 "Fatal system error. Invalid

Resume flag."

FAPI_IDMODULE_CMD_RESUME_ENROLL_FI

NGER_EXPECTED 0xC68004F0 "Fatal system error. Resume

Enroll finger expected."

4.1.2 Firmware file


FAPI_IDMODULESDK_FWF_FILE_EMPTY 0xC0100260 "The requested firmware file is

empty."

FAPI_IDMODULESDK_FWF_FILE_OPEN_F

AILED

0xC0100261 "Firmware file open failed."

FAPI_IDMODULESDK_FWF_TOO_MANY_P

ACKETS

0xC0100262 "Too many packets."

FAPI_IDMODULESDK_FWF_WRONG_CHE

CKSUM

0xC0100263 "Wrong checksum."

FAPI_IDMODULESDK_FWF_FILE_CORRUP

TED

0xC0100264 "The requested firmware file is

empty or corrupted."

TEXT_FAPI_IDMODULESDK_FWF_FUNC_I

NVALID_BAUDRATE

0xC0100270 "Invalid MNT Baudrate for

Firmware Download. Only

MNT Baudrate 57600 allowed."

4.1.3 Registry entries

The following error texts have the following schema:

*_CONF_*_MISSING: “The configuration parameter XX in section YY is missing.”

*_CONF_*_INVALID: “The configuration parameter XX in section YY is invalid.”

ID Module SDK V1.05


*_CONF_*_UPDATE_*: “Update section YY failed.”

Parameter XX and section YY correspond to the registry entries defined in chapter 3.3.


FAPI_IDMODULESDK_CONF_MISSING 0xC0209211 "Requested ID Module registry

path doesn't exist."

FAPI_IDMODULESDK_CONF_ALREADY_EXIT

S 0xC0209212 "Requested ID Module registry

path already exists."

FAPI_IDMODULESDK_CONF_VERSION_UPDA

TE_FAILED 0xC0209214 See schema.

FAPI_IDMODULESDK_CONF_BUILDNR_MISSI

NG 0xC0209215 See schema.

FAPI_IDMODULESDK_CONF_VERSIONNR_MI

SSING 0xC0209217 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_UPDA


FAPI_IDMODULESDK_CONF_TIMEOUT_CONN

ECT_MISSING 0xC0209219 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_GETM

ODSTATUS_MISSING 0xC0209221 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_SETM

ODCONFIG_MISSING 0xC0209223 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_GETM

ODCONFIG_MISSING 0xC0209225 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_GETF

LASHSTATUS_MISSING 0xC0209227 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_SELF

TEST_MISSING 0xC0209229 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_STAR

TFWL_MISSING 0xC0209231 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_DOW

NLFW_MISSING 0xC0209233 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_FINIS

HFWL_MISSING 0xC0209235 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_IDEN

T_MISSING 0xC0209237 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_ENCO

DE_MISSING 0xC0209239 See schema.

ID Module SDK V1.05


FAPI_IDMODULESDK_CONF_TIMEOUT_STAR

TENROLL_MISSING 0xC0209241 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_ENRO

LLFINGER_MISSING 0xC0209242 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_ENRO

LLPERSON_MISSING 0xC0209243 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_ADDP

ERSON_MISSING 0xC0209245 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_GETP


FAPI_IDMODULESDK_CONF_TIMEOUT_DELP


FAPI_IDMODULESDK_CONF_TIMEOUT_CHAN

GEPERSON_MISSING 0xC0209251 See schema.

FAPI_IDMODULESDK_CONF_TIMEOUT_GETP

ERSONID_MISSING 0xC0209253 See schema.

FAPI_IDMODULESDK_CONF_ID_UPDATE_FAI

LED 0xC0209310 See schema.

FAPI_IDMODULESDK_CONF_ID_SERNR_MISSI

NG 0xC0209311 See schema.

FAPI_IDMODULESDK_CONF_ID_CONNID_MIS

SING 0xC0209313 See schema.

FAPI_IDMODULESDK_CONF_ARCHIVE_UPDA


FAPI_IDMODULESDK_CONF_ARCHIVE_PERS

ONDATASIZE_MISSING 0xC0209321 See schema.

FAPI_IDMODULESDK_CONF_ARCHIVE_PERS

ONDATASIZE_INVALID 0xC0209322 See schema.

FAPI_IDMODULESDK_CONF_ARCHIVE_COUN

TENCFP_MISSING 0xC0209323 See schema.

FAPI_IDMODULESDK_CONF_ARCHIVE_COUN

TENCFP_INVALID 0xC0209324 See schema.

FAPI_IDMODULESDK_CONF_IDENT_UPDATE_

FAILED 0xC0209330 See schema.

FAPI_IDMODULESDK_CONF_IDENT_IDENTM

ODE_MISSING 0xC0209331 See schema.

FAPI_IDMODULESDK_CONF_IDENT_IDENTM

ODE_INVALID 0xC0209332 See schema.

FAPI_IDMODULESDK_CONF_IDENT_SECMOD

E_MISSING 0xC0209333 See schema.

ID Module SDK V1.05


FAPI_IDMODULESDK_CONF_IDENT_SECMOD

E_INVALID 0xC0209334 See schema.

FAPI_IDMODULESDK_CONF_SENSOR_UPDAT

E_FAILED 0xC0209340 See schema.

FAPI_IDMODULESDK_CONF_SENSOR_CAPMO

DE_MISSING 0xC0209341 See schema.

FAPI_IDMODULESDK_CONF_SENSOR_CAPMO

DE_INVALID 0xC0209342 See schema.

FAPI_IDMODULESDK_CONF_SENSOR_DYNM

ODE_MISSING 0xC0209343 See schema.

FAPI_IDMODULESDK_CONF_SENSOR_DYNM

ODE_INVALID 0xC0209344 See schema.

FAPI_IDMODULESDK_CONF_REL_UPDATE_F

AILED 0xC0209350 See schema.

FAPI_IDMODULESDK_CONF_REL_LINE1DELA

Y_MISSING 0xC0209351 See schema.

FAPI_IDMODULESDK_CONF_REL_LINE1DUR

ATION_MISSING 0xC0209353 See schema.

FAPI_IDMODULESDK_CONF_REL_LINE2DELA

Y_MISSING 0xC0209355 See schema.

FAPI_IDMODULESDK_CONF_REL_LINE2DUR

ATION_MISSING 0xC0209357 See schema.

FAPI_IDMODULESDK_CONF_UART_UPDATE_

FAILED 0xC0209360 See schema.

FAPI_IDMODULESDK_CONF_UART_BAUDRA

TE1_MISSING 0xC0209361 See schema.


TE1_INVALID 0xC0209362 See schema.


TE2_MISSING 0xC0209363 See schema.


TE2_INVALID 0xC0209364 See schema.

FAPI_IDMODULESDK_CONF_UART_COMPOR

T_MISSING 0xC0209365 See schema.

FAPI_IDMODULESDK_CONF_UART_COMPOR

T_INVALID 0xC0209366 See schema.

FAPI_IDMODULESDK_CONF_OP_UPDATE_FAI

LED 0xC0209370 See schema.

FAPI_IDMODULESDK_CONF_OP_OPMODE_MI

SSING 0xC0209371 See schema.

ID Module SDK V1.05


FAPI_IDMODULESDK_CONF_OP_OPMODE_IN

VALID 0xC0209372 See schema.

FAPI_IDMODULESDK_CONF_PMTIMEOUT_UP

DATE_FAILED 0xC0209380 See schema.

FAPI_IDMODULESDK_CONF_PMTIMEOUT_A2

I_MISSING 0xC0209381 See schema.

FAPI_IDMODULESDK_CONF_PMTIMEOUT_I2

O_MISSING 0xC0209383 See schema.

4.1.4 Serial interface


FAPI_IDMODULESDK_SERIAL_DEVICE_ERRO

R 0xC0308001 "Serial device error. Possible

problem: Selected comport

doesn't exist on your computer."

FAPI_IDMODULESDK_SERIAL_INVALID_DEVI

CE_NAME 0xC0308002 "The serial device name for the

serial device is not valid."

FAPI_IDMODULESDK_SERIAL_INVALID_DEVI

CE_SETTINGS 0xC0308003 "Unable to set serial device

parameters."

FAPI_IDMODULESDK_SERIAL_DEVICE_OPEN

_ERROR 0xC0308004 "Unable to open the serial

device. Possible problem:

Selected comport doesn't exist

on your computer."

FAPI_IDMODULESDK_SERIAL_DEVICE_NOT_

OPEN 0xC0308005 "Serial device not open."

FAPI_IDMODULESDK_SERIAL_READ_TIMEOU

T 0xC0308006 "Read timeout occured."

FAPI_IDMODULESDK_SERIAL_WRITE_TIMEO

UT 0xC0308007 "Write timeout occured."

FAPI_IDMODULESDK_DATA_TRANSMISSION

_ACK_ERROR 0xC0301003 "Transmission

AcknowledgeState error.

Possible problem: ID Module is

not connected or corrupt."

FAPI_IDMODULESDK_DATA_TRANSMISSION

_ERROR 0xC0301001 "Transmission error."

FAPI_IDMODULESDK_RECEIVE_TIMEOUT 0xC0301002 "Receive timeout occurred."

ID Module SDK V1.05


4.1.5 Interface parameter


FAPI_IDMODULESDK_CONF_ROOT_INVALID_

PARAM 0xC0409001 "Invalid

FAPIConfigurationPath

parameter."

FAPI_IDMODULESDK_MODULENAME_INVAL

ID_PARAM 0xC0409002 "Invalid FAPIModuleName

parameter."

FAPI_IDMODULESDK_COMPORT_INVALID_P

ARAM 0xC0409003

"Invalid FAPIModulePort

parameter."

FAPI_IDMODULESDK_BIODATA_INVALID_M

EMBLOCK 0xC0409011 "Invalid

FAPIBiometricMemBlock."

FAPI_IDMODULESDK_BIODATA_CORRUPTED 0xC0409012 "FAPIBiometricMemBlock

corrupted."

FAPI_IDMODULESDK_BIODATA_NOREFEREN

CE 0xC0409013 "FAPIBiometricMemBlock

contains no valid reference."

FAPI_IDMODULESDK_CONFIGPASSWORD_IN

VALID_PARAM 0xC0409015 "Invalid FAPIModulePassword

parameter."

FAPI_IDMODULESDK_MODULEPASSWORD_I

NVALID_PARAM 0xC0409016 "Invalid FAPIModulePassword

parameter."

FAPI_IDMODULESDK_MODULEOPMODE_INV

ALID_PARAM 0xC0409017 "Invalid

FAPIModuleOperationMode

parameter."

FAPI_IDMODULESDK_REFERENCE_INVALID_

MEMBLOCK 0xC0409020 "Invalid

FAPIReferenceMemBlock."

FAPI_IDMODULESDK_REFITER_INVALID_PA

RAM 0xC0409025 "Invalid FAPIReferenceIterator

parameter. Possible problem:

Out of range. Check

specification."

FAPI_IDMODULESDK_PERSONITER_INVALID

_PARAM 0xC0409026 "Invalid FAPIPersonIterator

parameter. Possible problem:

Out of range. Check

specification."

FAPI_IDMODULESDK_PERSON_INVALID_ME

MBLOCK 0xC0409030 "Invalid

FAPIPersonMemBlock."

FAPI_IDMODULESDK_PERSON_CORRUPTED 0xC0409031 "FAPIPersonMemBlock

corrupted."

FAPI_IDMODULESDK_PERSONDATA_INVALI 0xC0409040 "Invalid

ID Module SDK V1.05


D_MEMBLOCK FAPIPersonDataMemBlock."

FAPI_IDMODULESDK_PERSONID_INVALID_P

ARAM 0xC0409050 "Invalid FAPIPersonID

parameter."

FAPI_IDMODULESDK_PERSONID_INVALID 0xC0409051 "Invalid FAPIPersonID.

Possible problem: Out of range.


FAPI_IDMODULESDK_REFID_INVALID_PARA

M 0xC0409052 "Invalid FAPIReferenceID

parameter."

FAPI_IDMODULESDK_REFID_INVALID 0xC0409053 "Invalid FAPIReferenceID.



FAPI_IDMODULESDK_RESULT_INVALID_PAR

AM 0xC0409054 "Invalid FAPIResult

parameter."

FAPI_IDMODULESDK_CAPTURE_INVALID_PA

RAM 0xC0409056 "Invalid FAPICaptureMode

parameter."

FAPI_IDMODULESDK_CALLBACKENROLL_IN

VALID_PARAM 0xC0409058 "Invalid FAPICallBackEnroll

parameter."

FAPI_IDMODULESDK_SERDATA_INVALID_PA

RAM 0xC0409060 "Invalid Serialize Data

parameter."

FAPI_IDMODULESDK_SERDATALENGTH_INV

ALID_PARAM 0xC0409061 "Invalid Serialize Data length

parameter."

FAPI_IDMODULESDK_STATE_INVALID_PARA

M 0xC0409070 "Invalid FAPIStateResponse

parameter."

FAPI_IDMODULESDK_FLASH_INVALID_PARA

M 0xC0409075 "Invalid FAPIFlashResponse

parameter."

FAPI_IDMODULESDK_CONFIGDATA_INVALID

_PARAM 0xC0409080 "Invalid FAPIConfigData

parameter."

FAPI_IDMODULESDK_CONFIGFLAG_INVALID

_PARAM 0xC0409081 "Invalid FAPIConfigFlag

parameter."

FAPI_IDMODULESDK_TESTRESULT_INVALID

_PARAM 0xC0409085 "Invalid FAPITestResult

parameter."

FAPI_IDMODULESDK_TESTFLAG_INVALID_P

ARAM 0xC0409086 "Invalid FAPITestFlag

parameter."

FAPI_IDMODULESDK_FIRMWAREFILE_INVAL

ID_PARAM 0xC0409090 "Invalid FAPIFileName

parameter."

FAPI_IDMODULESDK_FWCODETYPE_INVALI

D_PARAM 0xC0409091 "Invalid FAPIFwCodeType

parameter."

FAPI_IDMODULESDK_IF_INVALID_HANDLE 0xC0509002 "Invalid Handle parameter."

ID Module SDK V1.05


FAPI_IDMODULESDK_IF_DEVICE_INVALID_H

ANDLE 0xC0509003 "Invalid FAPIDeviceHandle

parameter."

FAPI_IDMODULESDK_IF_ARCHIVE_INVALID_

HANDLE 0xC0509004 "Invalid FAPIArchiveHandle

parameter."

FAPI_IDMODULESDK_IF_INVALID_HANDLE_

TYPE 0xC0509005 "Invalid FAPIMemBlockType

parameter."

FAPI_IDMODULESDK_IF_VALID_HANDLE 0xC0509006 "Valid Handle. Call function

FAPIFree first."

FAPI_IDMODULESDK_IF_INVALID_MEMBLOC

K 0xC0509010 "Invalid FAPIMemBlock

parameter."

4.1.6 Identification ID Module


FAPI_IDMODULESDK_WRONG_SRNR 0xC0609103 "Serial numbers don't match.

Check registry and connected

ID Module."

4.1.7 Enumeration, Enrollment


FAPI_ITERATION_NO_MORE_DATA 0xC0704000 "Last reference."

FAPI_ITERATION_WRONG_REFERENCEID 0xC0704001 "Invalid FAPIReferenceIterator.



FAPI_CALLBACK_CANCEL 0xC0901000 "User interaction function exit

with Cancel."

4.1.8 System


FAPI_IDMODULE_BUSY 0xC0902000 "ID Module is busy."

FAPI_IDMODULESDK_FUNC_ERROR 0xC0909000 "General function error."

FAPI_IDMODULESDK_SYSTEM_MEMORY 0xC090FFFE "Memory error."

ID Module SDK V1.05


FAPI_IDMODULESDK_SYSTEM_ERROR 0xC090FFFF "Fatal system error."

FAPI_IDMODULESDK_FUNC_ERROR 0xC0909000 "General function error."

FAPI_IDMODULESDK_FUNC_CONNECT_ERRO

R 0xC0909001 "General CONNECT function

error."

FAPI_IDMODULESDK_FUNC_GETMODULEST

ATUS_ERROR 0xC0909002 "General

GETMODULESTATUS

function error."

FAPI_IDMODULESDK_FUNC_SETMODULECO

NFIG_ERROR 0xC0909003 "General

SETMODULECONFIG

function error."

FAPI_IDMODULESDK_FUNC_GETMODULECO

NFIG_ERROR 0xC0909004 "General

GETMODULECONFIG

function error."

FAPI_IDMODULESDK_FUNC_GETFLASHSTAT

US_ERROR 0xC0909005 "General GETFLASHSTATUS

function error."

FAPI_IDMODULESDK_FUNC_MODULESELFTE

ST_ERROR 0xC0909006 "General MODULESELFTEST

function error."

FAPI_IDMODULESDK_FUNC_STARTFWDWN_

ERROR 0xC0909010 "General STARTFWDWN

function error."

FAPI_IDMODULESDK_FUNC_RESUMEFWCOD

E_ERROR 0xC0909011 "General RESUMEFWCODE

function error."

FAPI_IDMODULESDK_FUNC_RESUMEFWCHE

CKSUM_ERROR 0xC0909012 "General

RESUMEFWCHECKSUM

function error."

FAPI_IDMODULESDK_FUNC_IDENTIFY_ERRO

R 0xC0909020 "General IDENTIFY function

error."

FAPI_IDMODULESDK_FUNC_ONLINEENCODE

_ERROR 0xC0909021 "General ONLINEENCODE

function error."

FAPI_IDMODULESDK_FUNC_RESUME_ENROL

L_ERROR 0xC0909022 "General RESUME_ENROLL

function error."

FAPI_IDMODULESDK_FUNC_START_ENROLL

_ERROR 0xC0909023 "General START_ENROLL

function error."

FAPI_IDMODULESDK_FUNC_ENROLLPERSON

_ERROR 0xC0909024 "General ENROLLPERSON

function error."

FAPI_IDMODULESDK_FUNC_ENROLLREF_ER

ROR 0xC0909025 "General ENROLLREF

function error."

FAPI_IDMODULESDK_FUNC_ADDPERSON_ER

ROR 0xC0909030 "General ADDPERSON

function error."

ID Module SDK V1.05


FAPI_IDMODULESDK_FUNC_GETPERSON_ER

ROR 0xC0909031 "General GETPERSON

function error."

FAPI_IDMODULESDK_FUNC_DELETEPERSON

_ERROR 0xC0909032 "General DELETEPERSON

function error."

FAPI_IDMODULESDK_FUNC_CHANGEPERSO

N_ERROR 0xC0909033 "General CHANGEPERSON

function error."

FAPI_IDMODULESDK_FUNC_GETPERSONID_E

RROR 0xC0909034 "General GETPERSONID

function error."

Table 4-1a: List of External Error Codes for the ID Module SDK

4.2 Request and Freeing of Objects, Call Back

Crucial to any ID Module SDK application are handle management, structure allocation /

deallocation and the call back mechanism which is implemented by the application programmer.

These topics are discussed in the following two sections.

4.2.1.1 Handles and Memblocks

• Handles

The ID Module SDK V1.0 and SDK V1.05 use a handle-oriented concept to transfer data to/from

the calling host application. Such handles generally consist of data that is returned to the host

application built by the SDK (implicitly allocating memory) and occasionally but regularly passed to

the SDK (e.g. FAPIDeviceHandle)

The following handles are defined:

FAPIArchiveHandle

FAPIDeviceHandle

FAPIGenericHandle

Handle data generally contains memory allocated by the SDK that must be freed explicitly by the

host application by calling the function FAPIReleaseArchive or FAPIReleaseDevice.

• Memblocks

The ID Module SDK provides so-called “Memblocks” which contain data as a BYTE Array to be

transferred over a FAPI interface.

Memblocks can be allocated by the SDK or by the application. If Memblocks are allocated by the

SDK, the application must call the function FAPIFree to free this memory. Otherwise the

application is responsible for freeing the allocated memory itself.

ID Module SDK V1.05


The following Memblocks are defined:

FAPIBiometricMemBlock

FAPIPersonDataMemBlock

FAPIPersonMemBlock

FAPIReferenceMemBlock

• Serialized Data

Serialized Data is a BYTE block representation of the previously mentioned Memblocks. The

FapiFunctions “FAPISerialize” and “FAPIDeserialize” are used to convert the Memblock

representation into a serialized representation (“FAPISerialize”) or vice versa (“FAPIDeserialize”).

Both calls allocate memory. Therefore the memory allocated by the “FAPISerialize” call may only

be freed by a call of “FAPIFreeSerialized” and memory allocated by “FAPIDeserialize” may only

be freed by a call of “FAPIFree”.

4.2.1.2 Call Back

For the function "FAPIEnrollment”, a pointer of type "FAPICallBackEnroll" must be provided by

the application for communication with the user. Furthermore, an application programmer may

define functions for interaction with the end user. These could be, for instance, message boxes.

The implementation of these functions is entirely the decision of the application programmer. Thus,

the application is responsible for the representation of communication. Nevertheless,

implementation must still be compliant with function parameters as defined in the ID Module SDK.

4.3 Data Model and External Data Structures

In the following section a description of the data transferred at the FAPI-Interface as well as that

transferred between components is given. The data structures defined for the corresponding

functions of the ID Module SDK are illustrated in Table 4-2 in chapter 4.3.2.

The format of serialised data is outlined in section 4.3.1..

4.3.1 Format of Serialized Data

PersonData:

Total length : PersonDataLength (pdlen)

Personid 2 BYTE

Reserved 2 BYTE

Persondata-Rest (pdlen-4) BYTE

ID Module SDK V1.05


Reference:

Total length : ReferenceLength (reflen)

Refid 2 BYTE

Reference-Rest (reflen-2) BYTE

BioData:

Total length : BioDataLength (biolen)

Referencecount (n) 2 BYTE

Reference1 See “Reference“

...

Referencen See “Reference“

Person:

Total length : PersonLength (perslen = pdlen+biolen +4 )

Pdlen 2 BYTE

Persondata pdlen BYTE

Biolen 2 BYTE

Biodata biolen BYTE

The FAPIFunctions “FAPISerialize“ and “FAPIDeserialize“ use the outlined formats of

“serialized“ data. It should be noted that the “total lengths“ are passed to the FAPIFunctions as

separate parameters and therefore NOT regarded as part of the serialized data.

4.3.2 Data Structures

FAPI_HANDLE_TAG

Definition char[10+1],

\0 terminated

Used By All handles

Values Is used internally, no changes are allowed

Description Characterizes a handle as valid or invalid and indicates the data is

represented by this handle.

ID Module SDK V1.05


The concerned handle types and corresponding tag names are:

FAPIDeviceHandle DEVICE

FAPIArchiveHandle ARCHIVE

FAPIPersonMemBlock PERSON

FAPIPersonDataMemBlock PERSONDATA

FAPIReferenceMemBlock REFERENCE

FAPIBiometricMemBlock BIOMETRIC

The function “FAPIFree” uses the tag to set the

FAPIGenericHandle to the explicit FAPIType and to call the

appropriate free function of the component Tools.

FAPIArchiveConfigData

Definition struct {

WORD dPersonDataSize;

WORD dCountEncodedFP;

}

Used By FAPIConfigData

Values

Description This data structure contains the archive specific configurable

parameters of the ID Module.

The type corresponds to the data type “ArchiveConfig” described

in [2].

FAPIArchiveHandle

Definition struct{

FAPI_HANDLE_TAG dTag;

void* dpPrivate;

}

Used By FAPIAcquireArchive

FAPIReleaseArchive

FAPILiveIdentifyPerson

FAPIEnrollment

FAPIDeletePerson

FAPIDeleteReferenceFromPerson

FAPIDeleteArchive

FAPIGetPerson

FAPIGetPersonData

FAPIGetReferenceFromPerson

FAPIEnumPerson

FAPIEnumPersonData

ID Module SDK V1.05


FAPIEnumReferenceFromPerson

FAPIChangePersonData

FAPIAppendPerson

FAPIGetPersonID

Values Serves as handle to a ID Module (rather ID Module archive)

The respective tag name is ARCHIVE.

Us used like FAPIDeviceHandle.

Description


Definition Struct {


WORD dCount;

FAPIReferenceMemBlock* dpReferences;

}

Used By FAPIPersonMemBlock

Values

Description The respective tag name is BIOMETRIC.

The FAPIReferenceMemBlock * will contain a pointer to an array of

“count” FAPIReferenceMemBlock-structures.

The array usually corresponds to the structure “BiometricData”

described in [2] but without “Number of References” field that is held

in “count”.

FAPICallBackEnroll

Definition long (*FAPICallBackEnroll)(FAPICallBackTyp*)

Used By FAPIEnrollment

Values The expected return values are

FAPI_OK read next fingerprint image

FAPI_CALLBACK_CANCEL: to stop enrollment process

Description Pointer to the function (function must be generated by the

application)

FAPICallBackTyp

Definition enum {

FAPI_NEW_IMAGE = 1,

FAPI_RETRY_IMAGE = 2

}

ID Module SDK V1.05


Used By FAPIEnrollment

Values See [2]

Description Denotes the type of the callback function

FAPI_NEW_IMAGE:

Notification to put the finger onto the sensor

FAPI_RETRY_IMAGE:

Rejection during the execution of the enrollment, a new

trial must be started

FAPICaptureMode

Definition Enum {

FAPI_SINGLE_MODE,

FAPI_ TRIGGER _MODE

}

Used By FAPILiveIdentifyPerson

FAPIExtractBioData

FAPIEnrollment

FAPISensorConfigData

Values

Description Acquisition mode for sensor

If capture mode “Single” is set, only one image is captured,

otherwise images are read until a defined picture quality or

trigger timeout is reached.

FAPIConfigBits

Definition enum {

FAPI_USE_ARCHIVE_CONFIG = 0x0001,

FAPI_USE_IDENT_CONFIG = 0x0002,

FAPI_USE_SENSOR_CONFIG = 0x0004,

FAPI_USE_RELEASE_CONFIG = 0x0008,

FAPI_USE_UART_CONFIG = 0x0010,

FAPI_USE_MODULE_CONFIG = 0x0020,

FAPI_USE_POWERMGMT_CONFIG = 0x0040

}

Used By FAPIConfigFlag

Values

Description List of FAPIConfigData sub structures relevant when the corresponding

bit is “set”:

FAPI_USE_ARCHIVE_CONFIG FAPIArchiveConfigData

ID Module SDK V1.05


FAPI_USE_IDENT_CONFIG FAPIIdentConfigData

FAPI_USE_SENSOR_CONFIG FAPISensorConfigData

FAPI_USE_RELEASE_CONFIG FAPIReleaseConfigData

FAPI_USE_UART_CONFIG FAPIUartConfigData

FAPI_USE_MODULE_CONFIG FAPIModuleOperationMode

FAPI_USE_POWERMGMT_CONFIG FAPIPowerMgmtConfigData

The values correspond to the valid values of the data type “ConfigFlag”

described in [2].

The values may be altered due to changes in a future version of [2].

FAPIConfigData

Definition struct {

FAPIConfigFlag dConfigFlag;

FAPIArchiveConfigData dArchiveConfigData

FAPIIdentConfigData dIdentConfigData;

FAPISensorConfigData dSensorConfigData;

FAPIReleaseConfigData dReleaseConfigData;

FAPIUartConfigData dUartConfigData;

FAPIModuleSecurityData dModuleSecurity;

FAPIPowerMgmtConfigData dPowerMgmtConfigData;

}

Used By FAPIReadConfigIDModule

FAPIConfigIDModule (implicitly)

Values

Description This data structure contains the data of all configurable parameters of the

ID Module.

The type corresponds to the data type “ModuleConfig” described in [2].

The sequence of the structure’s members may be changed due to changes

in a future version of [2].

FAPIConfigFlag

Definition WORD

Used By FAPIConfigIDModule

FAPIConfigData

Values OR-combination of values of type FAPIConfigBits

Description Serves as bitmask to indicate which parts of the

FAPIConfigData-structure contain relevant data to be set in the

ID Module archive when calling FAPIConfigIDModule or to be

read from the ID Module archive when calling

ID Module SDK V1.05


FAPIReadConfigIDModule.

The type corresponds to the data type “ConfigFlag” described in

[2].

FAPIDeviceHandle

Definition Struct{


void* dpPrivate;

}

Used By FAPIAcquireDevice

FAPIReleaseDevice


FAPIExtractBioData

FAPIConfigIDModule

FAPIReadConfigIDModule

FAPISelfTest

FAPIStateIDModule

FAPIStateIDModuleFlash

FAPILoadFirmware

FAPIEnrollment

FAPIChangeIDModuleOperationMode

FAPIChangeIDModulePassword

Values

Description Serves as handle to a ID Module

The respective tag name is DEVICE.

The void* will contain a pointer to an object of the class.

IDModuleConfig (component configuration)

FAPIDynamicMode

Definition Enum {

FAPI_LOW_DYNAMIC,

FAPI_HIGH_DYNAMIC

}

Used By FAPISensorConfigData

Values

Description This type defines the valid values of the corresponding sensor

specific configurable parameter of the ID Module.

The values correspond to the values of the data type

“SensorDynamicMode” described detailed in [2].

ID Module SDK V1.05


FAPIError

Definition Long

Used By All FAPI-Functions

Values

Description Error number

FAPIErrorText

Definition Char[255+1];

\0 terminated

Used By FAPIGetErrorText

Values

Description Error Text

FAPIFileName

Definition Char*,

\0 terminated

Used By FAPILoadFirmware

Values

Description Usually filename of the ID Module firmware file to be

downloaded to the ID Module.

The filename can include the entire directory path.

FAPIFlashResponse

Definition Struct {

DWORD dFreeMemory;

DWORD dAllocatedMemory;

WORD dNumberOfPersons;

WORD dNumberOfRefs;

}

Used By FAPIStateIDModuleFlash

Values

Description This data structure contains the status information of the

particular ID Module Flash components depicted in the structure.

The type corresponds to the data type “FlashStatus” described

detailed in [2].

ID Module SDK V1.05


FAPIFwCodeType

Definition enum {

FAPI_APPLICATION_CODE = 0x0001

}

Used By FAPILoadFirmware

Values

Description The FwCodeType specifies the type of the firmware that should

be downloaded to the ID Module

FAPIGenericHandle

Definition Void*

Used By FAPIFree

Values

Description Every handle can be set to this generic type; serves to reduce the

number of different freeing functions.

See also FAPI_HANDLE_TAG

FAPIIdentConfigData

Definition struct {

FAPIIdentificationMode dIdentMode;

FAPIMatchSecurityMode dMatchMode;

}


Values

Description This data structure contains the identification specific

configurable parameters of the ID Module.

The type corresponds to the data type “IdentificationConfig”

described in [2].

FAPIIdentificationMode

Definition enum {

FAPI_FULL_IDENTIFICATION,

FAPI_FAST_IDENTIFICATION

}

Used By FAPIIdentConfigData

ID Module SDK V1.05


Values See [2]

Description This type defines the valid values for the corresponding

identification specific configurable parameter of the ID Module.

The values correspond to the values of the data type.

“IdentificationMode” described in [2].

FAPIMatchSecurityMode

Definition enum {

FAPI_LOW_SECURITY_LEVEL,

FAPI_MEDIUM_SECURITY_LEVEL,

FAPI_HIGH_SECURITY_LEVEL

}

Used By FAPIIdentConfigData

Values

Description This type defines the valid values of the corresponding

identification specific configurable parameter of the ID Module.

The values correspond to the values of the data type

“MatchSecurityLevel” described in [2].

FAPIMemBlockType

Definition enum {

FAPI_PERSON,

FAPI_PERSONDATA,

FAPI_BIODATA,

FAPI_REFERENCE

}

Used By FAPIDeserialize

Values

Description Tbd

FAPIModuleName

Definition char [255+1],

\0 terminated


FAPIAcquireArchive

FAPICreateDeviceConfiguration

FAPIUpdateConfigurationFromModule

FAPIDeleteDeviceConfiguration

ID Module SDK V1.05


Values

Description Serves as logical ID Module name as well as a registry sub-key

of FAPIConfigurationPath to reach the corresponding registry

entries where all needed ID Module (configuration-

,communication-,identification-) parameters for the denoted ID

Module are held.


Definition enum {

FAPI_FULLYHOSTCONTROLLED_MODE = 0,

FAPI_WITHENROLLMENT_MODE = 1,

FAPI_WITHOUTENROLLMENT_MODE = 2,

FAPI_ENCODER_MODE = 3,

FAPI_AUTONOMOUS_MODE = 0xFF,

FAPI_MODE_IGNORED = 0xFFFF

}



Values See [2]

Description This data structure contains the configurable module operation

mode parameter of the ID Module.

The type and values correspond to the data type

“ModuleOperationMode” described in [2].

FAPIModulePassword

Definition char [15+1]

\0 terminated

Used By FAPIModuleSecurityMode



Values

Description This data structure contains the configurable module password

parameter of the ID Module. Once set, this module password

works as the “configuration password” necessary for the

concerned FAPIFunctions configuring the “module security” data

in the ID Module.

The type and values correspond to the data type

“ModulePassword” described in [2].

ID Module SDK V1.05


FAPIModulePort

Definition char*,

\0 terminated


FAPIAcquireArchive



Values

Description Serves as port number to overwrite the corresponding registry

entry for a ID Module or as an explicitly defined port to be used

for the RS232 serial interface to communicate with the ID

Module.

FAPIModuleSecurityData

Definition struct {

FAPIModuleOperationMode dModuleOperationMode,

FAPIModulePassword dModulePassword

}


Values

Description This data structure contains the “module security” specific

configurable parameters of the ID Module. The configuration of

this data is only allowed by transferring the valid configuration

password in calls of either

“FAPIChangeIDModuleOperationMode” or

“FAPIChangeIDModulePassword”.

Note: After calling “FAPIChangeIDModulePassword” the passed

ID Module password becomes the “new” configuration password

to be used in subsequent calls of the “module security” related

FAPIFunctions.


Definition struct {


WORD dLength;

BYTE* dpPersonData;

}

ID Module SDK V1.05


Used By FAPIEnrollmentNewPerson

FAPIGetPersonData


FAPIEnumPersonData



FAPIPersonMemBlock

Values

Description The respective tag name is PERSONDATA.

The void* will contain a pointer to a byte block of “length” bytes.

The byte block usually corresponds to the structure “PersonData”

described in [2].

The memory of the byte block is allocated by the ID Module

SDK, if one of the functions

“FAPIGetPersonData”

“FAPIGetReferenceFromPerson”

“FAPIEnumPersonData”

“FAPIEnumReferenceFromPerson”

“FAPIDeserialize”

is called.

The memory of the byte block must be allocated by the host

application if one of the functions

“FAPIEnrollment”

“FAPIChangePersonData”

is called.

The tag value need not to be set by the host application.

FAPIPersonID

Definition WORD


FAPIEnrollment

FAPIDeletePerson


FAPIGetPerson

FAPIGetPersonData


FAPIGetPersonID

FAPIReferenceIterator

Values 1.. 65000 valid PersonIDs

Description FAPIPersonID is used to identify a person in the ID Module

archive.

ID Module SDK V1.05


The type corresponds to the data type “PersonID” described in

[2].

FAPIPersonIterator

Definition WORD

Used By FAPIEnumPerson

FAPIEnumPersonData

Values 0 indicates “beginning of iteration”

Description FAPIPersonIterator is used by the “enum” functions and must be

initialized once at the start of the iterations and is updated inside

the functions to point to the next person in the ID Module

archive.

FAPIPersonMemBlock

Definition struct {


FAPIPersonDataMemBlock dPersonData;

FAPIBiometricMemBlock dBiometricData;

}

Used By FAPIEnumPerson

FAPIGetPerson

FAPIAppendPerson

Values

Description The respective tag name is PERSON.

The 2 combined records PersonData and BiometricData usually

correspond to the structure “Person” described in [2] without fields

“PersonDataLength” and “BioLength”.

Memory of the byte blocks inside is allocated by the ID Module

SDK if one of the functions:

“FAPIEnumPerson”

“FAPIGetPerson”

“FAPIDeserialize”

is called.

The memory of the byte blocks must be allocated by the host

application if the function “FAPIAppendPerson” is called.

The tag value need not to be set by the host application. When

building FAPIPersonMemBlock the correct memory allocation must

be the following:

- allocation of FAPIPersonDataMemBlock.dPersondata

- allocation of FAPIBiometricMemBlock.dpReferences

ID Module SDK V1.05


- allocation of FAPIReferenceMemBlock.dpReference

for each structure in the “dpReferences” array.

This should also be considered when realizing the appropriate free

functions in the component “Tools”.

FAPIPowerMgmtConfigData

Definition struct {

DWORD dActiveToIdle;

DWORD dIdleToOff;

}


Values

Description This data structure contains the “power management timeout “

specific configurable parameters of the ID Module.

The type corresponds to a data type to be defined in a future

version of [2].

FAPIReferenceID

Definition enum {

FAPI_START_ITERATION = -1,

FAPI_LEFT_LITTLE_FINGER= 0

FAPI_LEFT_RING_FINGER = 1,

FAPI_LEFT_MIDDLE_FINGER = 2,

FAPI_LEFT_INDEX_FINGER = 3,

FAPI_LEFT_THUMB = 4,

FAPI_RIGHT_THUMB = 5,

FAPI_RIGHT_INDEX_FINGER = 6,

FAPI_RIGHT_MIDDLE_FINGER = 7,

FAPI_RIGHT_RING_FINGER = 8,

FAPI_RIGHT_LITTLE_FINGER = 9

}


FAPIEnrollment




Values See [2]

Description FAPIReferenceID is used to identify one finger or special values

in requests to the ID Module.

The type and values correspond to the data type “ReferenceId”

described in [2].

ID Module SDK V1.05


According to [2] there are additional values that are used

internally to define the following:

“All Fingers” 0x000A

“No Finger” 0x00FF

The value FAPI_START_ITERATION is only used to initialize a

FAPIReferenceIterator for the start of a

FAPIEnumReferenceFromPerson sequence.


Definition struct {

FAPIPersonID dPersonID;

FAPIReferenceID dReferenceID;

}

Used By FAPIEnumReferenceFromPerson

Values FAPIReferenceID == FAPI_START_ITERATION indicates

“beginning of iteration”

Description FAPIReferenceIterator is used by

“FAPIEnumReferenceFromPerson” and must be initialized once

at the start of the iterations and are updated inside the functions

to point to the next person in the ID Module archive.


Definition struct {


WORD dLength;

BYTE* dpReference;

}

Used By FAPIExtractBioData




FAPIDeserialize

Values

Description The respective tag name is REFERENCE

The void* will contain a pointer to a byte block of “dLength”

bytes.

The byte block usually corresponds to the structure “Reference”

described in [2] but without length field that is held in

“dLength”.

The memory for the byte block is allocated by the ID Module

ID Module SDK V1.05


SDK when above indicated functions are called.

FAPIConfigrurationRath

Definition char*,

\0 terminated


FAPIAcquireArchive




Values

Description Path to the registry entries for global SDK configuration

parameters and ID Module specific sub entries.

FAPIReleaseConfigData

Definition struct {

WORD dLine1Delay;

WORD dLine1Duration;

WORD dLine2Delay;

WORD dLine2Duration;

}


Values

Description This data structure contains the release specific configurable


The type corresponds to the data type “ReleaseConfig” described

in [2].

FAPIResult

Definition enum {

FAPI_KNOWN,

FAPI_UNKNOWN

}


Values See [2]

Description Result of identification

ID Module SDK V1.05


FAPISensorConfigData

Definition struct {

FAPICaptureMode dCaptureMode;

FAPIDynamicMode dDynamicMode;

}


Values

Description This data structure contains the sensor specific configurable


The type corresponds to the data type “SensorConfig” described

in [2].

FAPIStateResponse

Definition struct {

WORD dModuleState;

DWORD dARMFwVersion;

DWORD dLEADFwVersion;

WORD dModuleId[4;]

}

Used By FAPIStateIDModule

Values The ModuleState values is to be defined by the ID Module.

Description This data structure contains the state information of the particular

ID Module components depicted in the structure.

The type corresponds to the data type “ModuleStatus” described

detailed in [2].

FAPITestBits

Definition enum {

FAPI_TEST_SENSOR = 0x0001,

FAPI_TEST_LEAD = 0x0002,

FAPI_TEST_SIP = 0x0004,

FAPI_TEST_ARCHIVE = 0x0010,

FAPI_TEST_FIRMWARE = 0x0020,

FAPI_TEST_LEDS = 0x0040

}

Used By FAPITestFlag

Values

Description List of FAPITestResult fields relevant when the corresponding

ID Module SDK V1.05


bit is “set”:

FAPI_TEST_SENSOR SensorState

FAPI_TEST_LEAD LeadState

FAPI_TEST_SIP SIPState

FAPI_TEST_ARCHIVE ArchiveState

FAPI_TEST_FIRMWARE FirmwareState

The corresponding tests are obvious.

The values correspond to the valid values of the data type

“TestFlag” described in [2].

The values may be changed due to changes in a future version of

[2].

FAPITestFlag

Definition WORD;

Used By FAPITestResult

Values OR-combination of values of type FAPITestBits

Description Serves as bitmask to indicate which parts of the FAPITestResult-

structure contain relevant results of particular tests to be read

from the ID Module archive when calling FAPISelfTest.

The type corresponds to the data type “TestFlag” described in

[2].

FAPITestResult

Definition struct {

FAPITestFlag dTestFlag;

WORD dSensorState;

WORD dLeadState;

WORD dSIPState;

WORD dArchiveState;

WORD dFirmwareState;

}

Used By FAPISelfTest

Values The result values are to be defined by the ID Module.

Description This data structure contains the results of the particular tests

summarized as ID Module self-test.

The type corresponds to the data type “TestResult” described in

[2].

ID Module SDK V1.05


FAPIUartConfigData

Definition struct {

DWORD dBaudMnt;

DWORD dBaudAci;

}


Values

Description This data structure contains the UART specific configurable


The type corresponds to the data type “UartConfig” described in

[2].

Table 4-2: External Data Structures of All User-Relevant ID Module SDK Functions

ID Module SDK V1.05


5 Detailed Description of the ID Module SDK Functions

This chapter describes all available ID Module SDK functions, contains a description of the tasks

they perform and divides them into 4 groups. Additionally, the functional interfaces for the external

communication for all functions are presented. Thus, the following sections provide information

about the

� the ID Module management functions,

� the biometric functions,

� the archive management functions and

� the tools functions.

ID Module SDK V1.05


5.1 ID Module management functions

5.1.1 Function FAPIAcquireDevice

FAPIAcquireDevice

Descripton This function initializes the FAPIDeviceHandle connections to

the ID Module via FAPIModulePort. It also checks whether the

ID Module corresponds to FAPIModuleName’s serial number

and that it has been registered already. The returned

FAPIDeviceHandle is then valid for subsequent FAPI function

calls by the host application when required as input parameter. It

must be explicitly released by a call of “FAPIReleaseDevice”.

Input parameters FAPIConfigurationPath

FAPIModuleName

FAPIModulePort

Output parameters FAPIDeviceHandle*

Return code 0 ok

<>0 FAPIError

FAPI_IDMODULESDK_CONF_ROOT_INVALID_PARAM

FAPI_IDMODULESDK_MODULENAME_INVALID_PARAM

FAPI_IDMODULESDK_IF_DEVICE_INVALID_HANDLE

FAPI_IDMODULESDK_COMPORT_INVALID_PARAM

FAPI_IDMODULESDK_CONF_MISSING

FAPI_IDMODULESDK_SYSTEM_MEMORY

FAPI_IDMODULESDK_CONF_***_MISSING

FAPI_IDMODULESDK_CONF_***_INVALID

FAPI_IDMODULESDK_SYSTEM_ERROR

FAPI_IDMODULESDK_WRONG_SRNR

FAPI_IDMODULESDK_CONF_ID_UPDATE_FAILED

FAPI_IDMODULESDK_FUNC_*

FAPI_IDMODULE_CMD_ENROLLMENT_ACTIVE

FAPI_IDMODULE_CMD_INVALID_CID

FAPI_IDMODULE_CMD_INVALID_PARAMETER

FAPI_IDMODULESDK_RECEIVE_TIMEOUT

FAPI_IDMODULESDK_DATA_TRANSMISSION_ERROR

FAPI_IDMODULE_BUSY

and occasionally return codes caused by “FAPIStateIDModule”

Comment FAPI_HANDLE_TAG is set to DEVICE

ID Module SDK V1.05


5.1.2 Function FAPIReleaseDevice

FAPIReleaseDevice

Descripton This function frees resources allocated by the FAPIDeviceHandle

in a previous FAPIAcquireDevice call.

Input parameters FAPIDeviceHandle*

Output parameters

Return code 0 ok

<>0 FAPIError

FAPI_IDMODULESDK_IF_INVALID_HANDLE

Comment The FAPIDeviceHandle is invalid after a successful function call.

FAPI_HANDLE_TAG is set to INVALID.

5.1.3 Function FAPIConfigIDModule

FAPIConfigIDModule

Descripton This function enables the host application to configure the ID

Module. The configurable parameters are contained by the

FAPIDeviceHandle set by a previous FAPIAcquireDevice call

with values from the registry.


FAPIConfigFlag

Output parameters

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_CONFIGFLAG_INVALID_PARAM




FAPI_IDMODULE_AR_ARCHIVE_ALREADY_PRESENT

FAPI_IDMODULE_AR_ARCHIVE_CREATION_FAILED

FAPI_IDMODULE_CMD_ACCESS_DENIED


FAPI_IDMODULE_CMD_INVALID_ARCHIVE_CFG


FAPI_IDMODULE_CMD_INVALID_IDENTIFY_CFG

FAPI_IDMODULE_CMD_INVALID_MODULE_MODE


FAPI_IDMODULE_CMD_INVALID_POWER_CFG

FAPI_IDMODULE_CMD_INVALID_RELEASE_CFG

ID Module SDK V1.05


FAPI_IDMODULE_CMD_INVALID_SENSOR_CFG

FAPI_IDMODULE_CMD_INVALID_UART_CFG

FAPI_IDMODULE_CMD_WRONG_PWD



FAPI_IDMODULE_BUSY

Comment The configurable parameters are outlined in the data structure

FAPIConfigData and the associated sub-structures.

The FAPIConfigFlag parameter decides which parameters of the

FAPIConfigData structure are to be set effectively in the ID

Module.

5.1.4 Function FAPIChangeIDModuleOperationMode


Descripton Configures the ID Module’s module operation mode (module security

data)


FAPIModulePassword


Output parameters

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_CONFIGPASSWORD_INVALID_PARAM

FAPI_IDMODULESDK_MODULEOPMODE_INVALID_PARAM


















ID Module SDK V1.05



FAPI_IDMODULE_BUSY

Comment The current, valid ID Module password must be transferred as a

FAPIModulePassword parameter.

5.1.5 Function FAPIChangeIDModulePassword


Descripton Changes the ID Module’s module password

(module security data)


FAPIModulePassword (old password)

FAPIModulePassword (new password)

Output parameters

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_CONFIGPASSWORD_INVALID_PARAM

FAPI_IDMODULESDK_MODULEPASSWORD_INVALID_PARAM



















FAPI_IDMODULE_BUSY

Comment The current, valid ID Module password must be transferred as a first

FAPIModulePassword parameter (configuration password).

In subsequent calls of

“FAPIChangeIDModulePassword” and

ID Module SDK V1.05


“FAPIChangeIDModuleOperationMode” the new password must be

used as a configuration password.

5.1.6 Function FAPIReadConfigIDModule

FAPIReadConfigIDModule

Descripton This function reads the configurable parameters from the ID

Module. The configurable parameters are returned in the

FAPIConfigData parameter.


Output parameters FAPIConfigData* (contains input FAPIConfigFlag)

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_CONFIGDATA_INVALID_PARAM

FAPI_IDMODULESDK_CONFIGFLAG_INVALID_PARAM








FAPI_IDMODULE_BUSY

Comment The FAPIConfigFlag parameter decides which parameters of the

FAPIConfigData structure are to be read effectively by the ID

Module.

ID Module SDK V1.05


5.1.7 Function FAPISelfTest

FAPISelfTest

Descripton Activates some tests on the ID Module. The FAPITestFlag field

of the FAPITestResult structure indicates which tests are to be

processed. The results of the relevant tests are returned in the

corresponding fields of the FAPITestResult structure.


Output parameters FAPITestResult* (also input)

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_TESTRESULT_INVALID_PARAM

FAPI_IDMODULESDK_TESTFLAG_INVALID_PARAM





FAPI_IDMODULE_CMD_INVALID_TESTFLAG



FAPI_IDMODULE_BUSY

Comment The meaning of the particular test result values is defined by the

ID Module Interface Description

ID Module SDK V1.05


5.1.8 Function FAPIStateIDModule

FAPIStateIDModule

Descripton Asks for the current state of the ID Module. This information is

returned in FAPIStateResponse structure.


Output parameters FAPIStateResponse*

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_STATE_INVALID_PARAM






FAPI_IDMODULE_BUSY

Comment The interpretation of the particular result values is defined by ID

Module Interface Description.

5.1.9 Function FAPIStateIDModuleFlash

FAPIStateIDModuleFlash

Descripton Asks for the current state of the ID Module FlashROM. This

information is returned in FAPIFlashResponse structure.


Output parameters FAPIFlashResponse*

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_FLASH_INVALID_PARAM






FAPI_IDMODULE_BUSY

Comment The interpretation of the particular result values is defined by ID

Module Interface Description.

ID Module SDK V1.05


5.1.10 Function FAPILoadFirmware

FAPILoadFirmware

Descripton Loads ID Module firmware


FAPIFileName

FAPIFwCodeType

Output parameters

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_FIRMWAREFILE_INVALID_PARAM

FAPI_IDMODULESDK_FWCODETYPE_INVALID_PARAM


FAPI_IDMODULESDK_FWF_FILE_EMPTY

FAPI_IDMODULESDK_FWF_FILE_OPEN_FAILED

FAPI_IDMODULESDK_FWF_TOO_MANY_PACKETS

FAPI_IDMODULESDK_FWF_WRONG_CHECKSUM

FAPI_IDMODULESDK_FWF_FILE_CORRUPTED


FAPI_IDMODULESDK_FUNC_ERROR



FAPI_IDMODULE_BUSY

FAPI_IDMODULE_CMD_INVALID_CODE_SIZE

FAPI_IDMODULE_CMD_INVALID_CODE_TYPE


FAPI_IDMODULE_CMD_INVALID_CHECKSUM

FAPI_IDMODULE_CMD_INVALID_CHECKSUM_TYPE

FAPI_IDMODULE_CMD_FLASH_WRITE

FAPI_IDMODULE_CMD_FLASH_RESET

Comment

5.2 Biometric functions

5.2.1 Function FAPILiveIdentifyPerson


Descripton A complete identification of a person is performed. This includes

image acquisition, generation of biometric data and identification

of the person in the ID Module archive.


ID Module SDK V1.05


FAPICaptureMode

FAPIArchiveHandle*

Output parameters FAPIPersonID*

FAPIReferenceID*

FAPIResult*

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_IF_ARCHIVE_INVALID_HANDLE

FAPI_IDMODULESDK_CAPTURE_INVALID_PARAM

FAPI_IDMODULESDK_PERSONID_INVALID_PARAM

FAPI_IDMODULESDK_REFID_INVALID_PARAM

FAPI_IDMODULESDK_RESULT_INVALID_PARAM



FAPI_IDMODULE_AR_NO_ARCHIVE_EXISTING



FAPI_IDMODULE_CMD_INVALID_CAPTURE_MODE


FAPI_IDMODULE_CMD_NO_MATCH

FAPI_IDMODULE_LEAD_AREA_COVERED_LOW

FAPI_IDMODULE_LEAD_DENSITY_LOW

FAPI_IDMODULE_LEAD_DYNAMIC_LOW

FAPI_IDMODULE_LEAD_ENCODE_ERROR

FAPI_IDMODULE_LEAD_INVALID_PIXEL

FAPI_IDMODULE_LEAD_MATCH_ERROR

FAPI_IDMODULE_LEAD_MINUTIA_COUNT_LOW

FAPI_IDMODULE_LEAD_NO_RESPONSE

FAPI_IDMODULE_LEAD_NOT_RUNNING

FAPI_IDMODULE_SENSOR_LINE_END_MARK

FAPI_IDMODULE_SENSOR_READ

FAPI_IDMODULE_SENSOR_RESET



FAPI_IDMODULE_BUSY

Comment

ID Module SDK V1.05


5.2.2 Function FAPIExtractBioData

FAPIExtractBioData

Descripton The extraction of an encoded fingerprint of the finger actually on the

ID Module sensor is processed without any matching. The

matching/processing of the returned biometric data is the

responsibility of the host application.


FAPICaptureMode

Output parameters FAPIReferenceMemBlock*

Return code 0 ok

<>0 FAPIError

FAPI_IDMODULESDK_REFERENCE_INVALID_MEMBLOCK



FAPI_IDMODULESDK_IF_VALID_HANDLE







FAPI_IDMODULE_LEAD_AREA_COVERED_LOW

FAPI_IDMODULE_LEAD_DENSITY_LOW

FAPI_IDMODULE_LEAD_DYNAMIC_LOW


FAPI_IDMODULE_LEAD_INVALID_PIXEL

FAPI_IDMODULE_LEAD_MINUTIA_COUNT_LOW



FAPI_IDMODULE_SENSOR_LINE_END_MARK





FAPI_IDMODULE_BUSY

FAPI_IDMODULESDK_BIODATA_INVALID_MEMBLOCK

FAPI_IDMODULESDK_BIODATA_CORRUPTED

FAPI_IDMODULESDK_BIODATA_NOREFERENCE


Comment FAPI_HANDLE_TAG is set to REFERENCE.

ID Module SDK V1.05


5.2.3 Function FAPIEnrollment

FAPIEnrollment

Descripton Enrollment of a new person or a new reference of an existing person: The

FAPIPersonID and person specific data is provided by the calling

application via FAPIPersonDataMemBlock.


FAPIArchiveHandle*

FAPICaptureMode

FAPIPersonDataMemBlock*

FAPIReferenceID

FAPICallBackEnroll

Output parameters

Return code 0 ok

<>0 FAPIError




FAPI_IDMODULESDK_PERSONDATA_INVALID_MEMBLOCK

FAPI_IDMODULESDK_REFID_INVALID

FAPI_IDMODULESDK_CALLBACKENROLL_INVALID_PARAM


FAPI_CALLBACK_CANCEL



FAPI_IDMODULE_AR_PERSON_ALREADY_EXISTING

FAPI_IDMODULE_AR_REFERENCE_ALREADY_EXISTING




FAPI_IDMODULE_CMD_INVALID_PERSONID

FAPI_IDMODULE_CMD_INVALID_REFERENCEID

FAPI_IDMODULE_CMD_RESUME_ENROLL_PERSON_EXPECTED

FAPI_IDMODULE_CMD_RESUME_ENROLL_FINGER_EXPECTED


FAPI_IDMODULE_CMD_ENROLLMENT_NOT_ACTIVE

FAPI_IDMODULE_CMD_INVALID_PERSONDATA


FAPI_IDMODULE_CMD_INVALID_RESUMEFLAG







ID Module SDK V1.05



FAPI_IDMODULE_AR_REFERENCE_NOT_FOUND




FAPI_IDMODULE_BUSY

Comment If the person already exists in the system, the person specific data is

updated automatically.

5.3 Archive management functions

ID Module SDK V1.05


5.3.1 Function FAPIAcquireArchive

FAPIAcquireArchive

Descripton This function initializes the FAPIArchiveHandle, connects to the

ID Module via FAPIModulePort, and checks whether the ID

Module corresponds to FAPIModuleName’s serial number which

must have been previously registered. The returned

FAPIArchiveHandle is then valid for subsequent FAPI function

calls by the host application when required as input parameter. It

must be explicitly released by a call of “FAPIReleaseArchive”.


FAPIModuleName

FAPIModulePort

Output parameters FAPIArchiveHandle*

Return code 0 ok

<>0 FAPIError

same return codes as caused by “FAPIAcquireDevice”

Comment This function internally calls “FAPIAcquireDevice”.

FAPI_HANDLE_TAG is set to ARCHIVE.

5.3.2 Function FAPIReleaseArchive

FAPIReleaseArchive

Descripton See FAPIReleaseDevice

Input parameters FAPIArchiveHandle*

Output parameters

Return code 0 ok

<>0 FAPIError

same return codes as caused by “FAPIReleaseDevice”

Comment This function internally calls “FAPIReleaseDevice”.


ID Module SDK V1.05


5.3.3 Function FAPIDeletePerson

FAPIDeletePerson

Descripton Deletes a person identified by FAPIPersonID in the ID Module

archive.


FAPIPersonID

Output parameters

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_PERSONID_INVALID











FAPI_IDMODULE_CMD_LAST_REFERENCE



FAPI_IDMODULE_BUSY

Comment

ID Module SDK V1.05


5.3.4 Function FAPIDeleteReferenceFromPerson


Descripton Deletes a specific reference (finger) identified by

FAPIReferenceID of a person identified by FAPIPersonID in the

ID Module archive.


FAPIPersonID

FAPIReferenceID

Output parameters

Return code 0 ok

<>0 FAPIError

















FAPI_IDMODULE_BUSY

Comment This function corresponds to [2] chapter 3.4.2.12.

Note: If the person only contains one reference, the call fails

because the ID Module does not manage persons without at least

one reference.

Calling/using See flow chart and corresponding Detailed Design Specification

Called by Primarily host application

ID Module SDK V1.05


5.3.5 Function FAPIDeleteArchive

FAPIDeleteArchive

Descripton Deletes the whole ID Module archive.


Output parameters

Return code 0 ok

<>0 FAPIError















FAPI_IDMODULE_BUSY

Comment

ID Module SDK V1.05


5.3.6 Function FAPIGetPerson

FAPIGetPerson

Descripton Reads a person (person specific and biometric data) identified by

FAPIPersonID from the ID Module archive.

The data is returned in the FAPIPersonMemBlock structure.


FAPIPersonID

Output parameters FAPIPersonMemBlock*

Return code 0 ok

<>0 FAPIError



FAPI_IDMODULESDK_PERSON_INVALID_MEMBLOCK















FAPI_IDMODULE_BUSY





Comment FAPI_HANDLE_TAG is set to PERSON

ID Module SDK V1.05


5.3.7 Function FAPIGetPersonData

FAPIGetPersonData

Descripton Reads the person specific data of a person identified by FAPIPersonID

from the ID Module archive.

The data is returned in the FAPIPersonDataBlock structure.


FAPIPersonID

Output parameters FAPIPersonDataMemBlock*

Return code 0 ok

<>0 FAPIError


















FAPI_IDMODULE_BUSY


Comment FAPI_HANDLE_TAG is set to PERSONDATA.

ID Module SDK V1.05


5.3.8 Function FAPIGetReferenceFromPerson


Descripton Reads the person specific data of a person identified by FAPIPersonID

and one reference identified by FAPIReferenceID from the ID Module

archive.

The data is returned in the FAPIPersonDataBlock and

FAPIReferenceMemBlock structures.


FAPIPersonID

FAPIReferenceID


FAPIReferenceMemBlock*

Return code 0 ok

<>0 FAPIError




















FAPI_IDMODULE_BUSY





Comment FAPI_HANDLE_TAG is set to PERSONDATA and REFERENCE

ID Module SDK V1.05


5.3.9 Function FAPIEnumPerson

FAPIEnumPerson

Descripton Reads a person (person specific and biometric data) from the ID

Module archive. The data is returned in the

FAPIPersonMemBlock structure. The parameter

FAPIPersonIterator contains information about the “next” person

to be read. Therefore by subsequently calling the function, it is

possible to read all persons from the archive.

To read the first person it is necessary to set the contents of

FAPIPersonIterator appropriately (value 0).


FAPIPersonIterator* (also output)

Output parameters FAPIPersonMemBlock*

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_PERSONITER_INVALID_PARAM

















FAPI_IDMODULE_BUSY




Comment FAPI_HANDLE_TAG is set to PERSON.

5.3.10 Function FAPIEnumPersonData

FAPIEnumPersonData

ID Module SDK V1.05


Descripton Reads a person’s specific data from the ID Module archive.

The data is returned in the FAPIPersonDataMemBlock structure.

The parameter FAPIPersonIterator contains information about the

“next” person to be read. Therefore by subsequently calling the

function, it is possible to read all persons from the archive.

To read the first person it is necessary to set the contents of

FAPIPersonIterator appropriately (value 0).


FAPIPersonIterator* (also output)


Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_PERSONITER_INVALID_PARAM

















FAPI_IDMODULE_BUSY


Comment FAPI_HANDLE_TAG is set to PERSONDATA.

ID Module SDK V1.05


5.3.11 Function FAPIEnumReferenceFromPerson


Descripton Reads a person’s specific data and one reference (finger) from the ID

Module archive.

The data is returned in the FAPIPersonDataMemBlock and

FAPIReferenceMemBlock structure.

The parameter FAPIReferenceIterator contains information about the

person and the “next” reference to be read. Therefore by subsequently

calling the function, it is possible to read all references from the

archive.

To read the first reference, it is necessary to set the contents of

FAPIReferenceIterator appropriately.

- FAPIPersonID to identify the person.

- FAPIReferenceID to FAPI_START_ITERATION


FAPIReferenceIterator* (also output)


FAPIReferenceMemBlock*

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_REFITER_INVALID_PARAM







FAPI_ITERATION_NO_MORE_DATA

FAPI_ITERATION_WRONG_REFERENCEID













FAPI_IDMODULE_BUSY


ID Module SDK V1.05





Comment FAPI_HANDLE_TAG is set to PERSONDATA and REFERENCE.

5.3.12 Function FAPIChangePersonData


Descripton Changes the person specific data of a person identified by

FAPIPersonID (inside FAPIPersonDataMemBlock) in the ID Module

archive. The data is transferred in the FAPIPersonDataBlock structure.


FAPIPersonDataMemBlock*

Output parameters

Return code 0 ok

<>0 FAPIError










FAPI_IDMODULE_CMD_INVALID_PERSON_DATA




FAPI_IDMODULE_BUSY

Comment

ID Module SDK V1.05


5.3.13 Function FAPIAppendPerson

FAPIAppendPerson

Descripton A person is added to the ID Module SDK unless the person identified

by FAPIPersonID (inside FAPIPersonMemBlock) is already in the ID

Module archive.

The data is provided by the host application via the input parameter

FAPIPersonMemBlock.


FAPIPersonMemBlock*

Output parameters

Return code 0 ok

<>0 FAPIError








FAPI_IDMODULE_AR_PERSON_ALREADY_EXISTING




FAPI_IDMODULE_CMD_INVALID_PERSON_DATA

FAPI_IDMODULE_CMD_INVALID_REFERENCE



FAPI_IDMODULE_BUSY

Comment

ID Module SDK V1.05


5.3.14 Function FAPIGetPersonID

FAPIGetPersonID

Descripton A free FAPIPersonID returned via the corresponding output

parameter is requested from the ID Module archive.


FAPIPersonID

Output parameters FAPIPersonID*

Return code 0 ok

<>0 FAPIError


FAPI_IDMODULESDK_PERSONID_INVALID_PARAM










FAPI_IDMODULE_BUSY

Comment PersonID may be used to get a free PersonID from the ID Module

with a specified minimum value. The ID Module returns the

lowest available PersonID, greater than the ID specified as input.

5.4 Tools functions

5.4.1 Function FAPICreateDeviceConfiguration


Descripton Creates a set of ID Module specific entries in the registry set to

define default values. FAPIConfigurationPath and

FAPIModuleName build a registry key that serves as “entry point”

for the set of entries that contain data.


FAPIModuleName

FAPIModulePort

Output parameters

Return code 0 ok

<>0 FAPIError


ID Module SDK V1.05




FAPI_IDMODULESDK_CONF_ALREADY_EXITS



Comment

5.4.2 Function FAPIUpdateConfigurationFromModule


Descripton This function reads the set of ID Module specific data from the ID

Module and updates the corresponding values in the registry. The

desired values are retrieved by calls of FAPIStateIDModule and

FAPIReadConfigIDModule and then it checks whether the

attached ID Module and the FAPIModuleName value are equal.

The FAPIModulePort parameter will overwrite the configuration

entry and is used as the chosen port for the RS232 serial interface

communication.


FAPIModuleName

FAPIModulePort

Output parameters

Return code 0 ok

<>0 FAPIError







FAPI_IDMODULESDK_CONF_***_INVALID

FAPI_IDMODULESDK_CONF_***_UPDATE_FAILED

and occasionally return codes caused by “FAPIAcquireDevice”,

“FAPIReadConfigIDModule” or

“FAPIReleaseDevice”

Comment

ID Module SDK V1.05


5.4.3 Function FAPIDeleteDeviceConfiguration


Descripton Deletes a set of ID Module specific entries from the configuration.

FAPIConfigurationPath and FAPIModuleName build a

configuration key (sub-tree) that serves as an “entry point” from

which all entries are removed including the “ModuleName” entry

itself.


FAPIModuleName

Output parameters

Return code 0 ok

<>0 FAPIError






Comment

ID Module SDK V1.05


5.4.4 Function FAPISerialize

FAPISerialize

Descripton Serializes a FAPIMemblock structure into a byte block according to the

ID Module interface specification.

Input parameters FAPIGenericHandle

Output parameters BYTE**

WORD*

Return code 0 ok

<>0 FAPIError

FAPI_IDMODULESDK_IF_INVALID_MEMBLOCK

FAPI_IDMODULESDK_SERDATA_INVALID_PARAM

FAPI_IDMODULESDK_SERDATALENGTH_INVALID_PARAM







Comment The retrieved byte block must be freed by calling “FAPIFreeSerialzed”.

ID Module SDK V1.05


5.4.5 Function FAPIDeserialize

FAPIDeserialize

Descripton Deserializes a byte block into the desired FAPIMemblock structure.

Input parameters BYTE*

WORD

FAPIMemBlockType

Output parameters FAPIGenericHandle

Return code 0 ok

<>0 FAPIError




FAPI_IDMODULESDK_SERDATALENGTH_INVALID_PARAM

FAPI_IDMODULESDK_PERSON_CORRUPTED





FAPI_IDMODULESDK_IF_INVALID_HANDLE_TYPE

Comment The retrieved FAPIMemblock structure must be freed by calling

“FAPIFree”.

5.4.6 Function FAPIFreeSerialized

FAPIFreeSerialize

Descripton Frees a byte block allocated by FAPISerialize.

Input parameters BYTE**

Output parameters

Return code 0 ok

<>0 FAPIError


Comment

ID Module SDK V1.05


5.4.7 Function FAPIGetErrorText

FAPIGetErrorText

Descripton Returns an error text for a given error number.

Input parameters FAPIError

Output parameters FAPIErrortext*

Return code 0 ok

<>0 FAPIError

...

Comment

5.4.8 Function FAPIFree

FAPIFree

Descripton This function frees storage allocated by the following handle

types:



FAPIPersonMemBlock


Input parameters FAPIGenericHandle

Output parameters

Return code 0 ok

<>0 FAPIError

...

Comment The particular handles must be set to FAPIGenericHandle. This

function identifies the different types by interpreting the tag

values that have been set appropriately previously.


ID Module SDK V1.05


6 Scenarios for Dealing with ID Module Configurations

For each ID Module a predefined set of registry entries called “registry configuration” must exist.

The contents of the “registry configuration” is defined in chapter 4.1.3. It should be noted that inside

the ID Module firmware, a corresponding set of data called the “firmware configuration” of the ID

Module exists.

It is recommended that the application use a “registry configuration” consistent with the “firmware

configuration”.

Furthermore it must be noted that an existing “registry configuration” is a necessary precondition to

obtain access to the ID Module firmware via the FAPI.DLL at all. The ID Module access for an

application requires a valid FAPIDeviceHandle and/or FAPIArchiveHandle. These handles are

provided by calls of the functions “FAPIAcquireDevice” and “FAPIAcquireArchive” respectively.

The application must not manipulate the handles itself but must pass the handles as parameters to

subsequent FAPI function calls. The period beginning with acquiring the handle(s) up and ending

with freeing the handle(s) may be called a “session”. The term “open session” corresponds to the

existence of a valid handle(s).

Under consideration of these comments, there are some scenarios important for any application

when managing ID Module configurations.

6.1 Scenario 1: New or unknown ID Module must be accessed


FAPIAcquireDevice registry

"SerialNumber" is set to the value of

the firmware configuration

"ConnectionID" is set arbitrarily

Default entries for "module"

Note: "SerialNumber" and

"ConnectionID" hold default

values to denote the state "unset"

SCENARIO 1:

Precondition:

There does not exist a "registry configuration" of the FP-Module ModuleX .

Opening a session via "FAPIAcquireDevice" resp." FAPIAcquireArchive" will fail.

Proposed Solution:

Note: The returned FAPIDeviceHandle

contains a copy of the "registry

configuration"

ID Module SDK V1.05


6.2 Scenario 2: Registry configuration to be overwritten by firmware configuration

FAPIUpdateConfigurationFromModule registry

SCENARIO 2:

Precondition:

- Existing "registry configuration"

- no open session is required because FAPIUpdateConfigurationFromModule processes own

session.

Proposed Solution:

6.3 Scenario 3: Firmware configuration to be overwritten by registry configuration

FAPIConfigFPModule registry

SCENARIO 3:

Precondition:

Open session

Proposed Solution:

Note: The registry is not accessed because

the (full or partial) "firmware configuration"

update is done with the FAPIDevicehandle's

copy of the the "registry configuration"

ID Module SDK V1.05


6.4 Scenario 4: Application changes the configurations by own means

GUI changes configuration registry

SCENARIO 4:

Precondition:

Open session necessary only in solution 2

Proposed Solution 1: The GUI's configuration dialog(s) are initialized with the "registry configuration"

data

Note: A new session is necessary because

the FAPIDeviceHandle's copy of the "registry

configuration" must be actualized due to the

GUI's registry changes.

FAPIConfigFPModule

FAPIAcquireDevice

(new-handle)

FAPIReleaseDevice

open

session

yes

optional update of

"firmware configuration"

no

ID Module SDK V1.05


6.5 Scenario 5: Application changes the UART configurations by own means


SCENARIO 5:

Precondition:


Proposed Solution 1: The GUI's configuration dialog(s) are initialized with the "registry configuration"

data

Note: A new session is necessary because

the FAPIDeviceHandle's copy of the "registry

configuration" must be actualized due to the

GUI's registry changes.

If baudrate changes are made , first the

connection must be done with the old

baudrate and then change to new one.

FAPIConfigFPModule

FAPIAcquireDevice

(new-handle)

FAPIReleaseDevice

open

session

yes

optional update of


no

GUI changes BAUDRATES

ID Module SDK V1.05



SCENARIO 4:

Precondition:


Proposed Solution 2: The GUI's configuration dialog(s) are initialized with the "firmware configuration"

data

optional update of


FAPIStateFPModule

FAPIReadConfigFPModule

The returned structures

FAPIConfigData and

FAPIStateResponse

of these function calls hold all required data

ID Module SDK V1.05


7 Literature

[1] ID Module SDK User's Guide

[2] ID Module Interface Description V1.99, ID Module Firmware V1.0, Siemens AG Munich

ID Module SDK V1.05


8 Terms

Term Explanation

Application Programming Interface A standardized programming interface such

that application programmers do not need to

know the specific details of the software they

want to integrate into their proprietary

applications. Thus biometric solutions

provided by different biometric software

suppliers might easily be exchanged from the

application’s point of view.

Enrollment A user is introduced to the system, which

means that example data of his or her

biometric features must be acquired for

subsequent use during verification or

identification.

Identification A person’s identity is determined by

comparing actual biometric features (e.g.

fingerprint features) with the existing

reference features of all persons in a given

database.

person Consists of person specific data and biometric data for a person

identified by PersonID.

person specific data PersonID and lastname or firstname, for example

biometric data Composed of 1-10 references for person

reference Comprised of 1-n (configurable) encoded fingerprints for

(PersonID/ReferenceID) where ReferenceID identifies a

particular finger of the person. Fingerprints are the raw image

data of a finger.

ID Module SDK V1.05


1. reference (finger)

person

person specific data

biometric data

encoded FPs

10 . reference (finger)

encoded FPs

configurable

number

Figure 8-1: Structure of a person

ID Module SDK V1.05


9 Abbreviations

API Application Programming Interface

BiometricData Biometric Data

BMP Bitmap, image data file format

DLL Dynamic Link Library

FAPI (SIEMENS) Fingerprint API

FAPI-Interface Interface of the Fingerprint API

GUI Graphical User Interface

PDF Portable Document Format

SDK Software Development Kit

UI-DLL User Interface – Dynamic Link Library

ID Module SDK V1.05


The Example Code #include "windows.h" #include <stdlib.h> #include <stdio.h> #include "conio.h" #include "idmodule.h" /*******************************************************************/ /*******************************************************************/ // ErrorHandling /*******************************************************************/ /*******************************************************************/ //------------------------------------------------------------------ // Function checkRetCode //------------------------------------------------------------------ // Checks ErrorCode, if failed, gets errormessage and exit program int checkRetCode (int iError) { FAPIErrorText ErrorText = ""; if (iError != FAPI_OK) { FAPIGetErrorText(iError, &ErrorText); printf("ERROR: %d \n%s\n ", iError, ErrorText); getch(); return 0; } return 1; } /*******************************************************************/ /*******************************************************************/ // CallBack Function /*******************************************************************/ /*******************************************************************/ //------------------------------------------------------------------ // Function CallBackFunc //------------------------------------------------------------------ // Used for Userinteraction long __stdcall CallBackFunc( FAPICallBackTyp* pCallBackTyp) { int a; switch (*pCallBackTyp) { case FAPI_NEW_IMAGE: printf("\n\nPlease put your finger on the sensor!"); break; case FAPI_RETRY_IMAGE: printf("\n\nBad Picture Quality, Retry?"); break; }; printf("\n\tTo continue press <Enter> \n\tOtherwise press <x>"); a = getch(); switch (a) { case 13: // Enter return FAPI_OK; break; default: return FAPI_CALLBACK_CANCEL; break; } return 0; }

ID Module SDK V1.05


/*******************************************************************/ /*******************************************************************/ // Sample Functions /*******************************************************************/ /*******************************************************************/ //------------------------------------------------------------------ // Function sampleSerialize //------------------------------------------------------------------ // Shows all necessary functions for serializing and deserializing MemBlock-Types int sampleSerialize() { int retCode = FAPI_OK; FAPIArchiveHandle ArchiveHandle; FAPIPersonID PersonID; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPIPersonMemBlock Person; BYTE* SerializedData; WORD DataLength; strncpy(ModuleName,"module1",16); //-------------------------------------------- // Open Archiv retCode = FAPIAcquireArchive(ConfigurationPath, ModuleName, ModulePort, &ArchiveHandle); if (retCode != FAPI_OK) return retCode; //-------------------------------------------- // Get a person from the ID Module archive PersonID = 99; retCode = FAPIGetPerson( &ArchiveHandle, PersonID, &Person); if (retCode != FAPI_OK) { FAPIReleaseArchive(&ArchiveHandle); return retCode; } //-------------------------------------------- // Serializing the retrieved person! printf("\nprocessing FAPISerialize ...\n"); retCode = FAPISerialize( (FAPIGenericHandle*)&Person, &SerializedData, &DataLength); FAPIFree((FAPIGenericHandle)&Person); if (retCode != FAPI_OK) { FAPIReleaseArchive(&ArchiveHandle); return retCode; } //-------------------------------------------- // deserializing the serialized person! printf("\nprocessing FAPIDeserialize ...\n"); retCode = FAPIDeserialize( SerializedData, DataLength, (FAPIGenericHandle)&Person, FAPI_PERSON); FAPIFree((FAPIGenericHandle)&Person); //-------------------------------------------- // free the serialized person! printf("\nprocessing FAPIFreeSerialized ...\n");

ID Module SDK V1.05


FAPIFreeSerialized(&SerializedData); if (retCode != FAPI_OK) { FAPIReleaseArchive(&ArchiveHandle); return retCode; } retCode = FAPIReleaseArchive(&ArchiveHandle); return FAPI_OK; } //------------------------------------------------------------------ // Function sampleRegistry //------------------------------------------------------------------ // Shows all necessary functions for management of ID Module Registry entries int sampleRegistry() { int retCode = FAPI_OK; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; strncpy(ModuleName,"moduleXY",16); //-------------------------------------------- // create a device(ID Module) in registry retCode = FAPICreateDeviceConfiguration( ConfigurationPath, ModuleName, ModulePort); if (retCode != FAPI_OK) { // return retCode; } //-------------------------------------------- // delete a device(ID Module) in registry retCode = FAPIDeleteDeviceConfiguration( ConfigurationPath, ModuleName); if (retCode != FAPI_OK) { return retCode; } //-------------------------------------------- // update a device(ID Module) in registry with data from ID Module strncpy(ModuleName,"module1",16); retCode = FAPIUpdateConfigurationFromModule( ConfigurationPath, ModuleName, ModulePort); if (retCode != FAPI_OK) { return retCode; } return FAPI_OK; } //------------------------------------------------------------------ // Function sampleLiveIdentify //------------------------------------------------------------------ // Shows all necessary functions for identifying a person int sampleLiveIdentify() { int retCode = FAPI_OK; FAPIDeviceHandle DeviceHandle; FAPIArchiveHandle ArchiveHandle; FAPIPersonID PersonID; FAPIReferenceID ReferenceID;

ID Module SDK V1.05


FAPIResult Result; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPICallBackTyp CbType = FAPI_NEW_IMAGE; strncpy(ModuleName,"module1",16); //-------------------------------------------- // Open Sensor retCode = FAPIAcquireDevice(ConfigurationPath, ModuleName, ModulePort, &DeviceHandle); if (retCode != FAPI_OK) return retCode; //-------------------------------------------- // Open Archiv retCode = FAPIAcquireArchive(ConfigurationPath, ModuleName, ModulePort, &ArchiveHandle); if (retCode != FAPI_OK) return retCode; printf("\nprocessing FAPILiveIdentifyPerson ...\n"); //-------------------------------------------- // Please put finger on sensor if (CallBackFunc(&CbType) == FAPI_OK) { retCode = FAPILiveIdentifyPerson(&DeviceHandle, FAPI_SINGLE_MODE, &ArchiveHandle, &PersonID, &ReferenceID, &Result); if (retCode != FAPI_OK) { FAPIReleaseDevice(&DeviceHandle); FAPIReleaseArchive(&ArchiveHandle); return retCode; } if (Result == FAPI_KNOWN) printf("\nVerified\n"); else printf("\nUnknown"); } //-------------------------------------------- // Close Devices retCode = FAPIReleaseDevice(&DeviceHandle); retCode = FAPIReleaseArchive(&ArchiveHandle); return FAPI_OK; } //------------------------------------------------------------------ // Function sampleExtractBioData //------------------------------------------------------------------ // Shows all necessary functions for extracting biometric data (online encode) int sampleExtractBioData() { int retCode = FAPI_OK; FAPIDeviceHandle DeviceHandle; FAPIReferenceMemBlock Reference; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPICallBackTyp CbType = FAPI_NEW_IMAGE; strncpy(ModuleName,"module1",16);

ID Module SDK V1.05


//-------------------------------------------- // Open Sensor retCode = FAPIAcquireDevice(ConfigurationPath, ModuleName, ModulePort, &DeviceHandle); if (retCode != FAPI_OK) return retCode; printf("\nprocessing FAPIExtractBioData ...\n"); //-------------------------------------------- // Please put finger on sensor if (CallBackFunc(&CbType) == FAPI_OK) { retCode = FAPIExtractBioData(&DeviceHandle, FAPI_SINGLE_MODE, &Reference); FAPIFree((FAPIGenericHandle)&Reference); if (retCode != FAPI_OK) { FAPIReleaseDevice(&DeviceHandle); return retCode; } } //-------------------------------------------- // Close Devices retCode = FAPIReleaseDevice(&DeviceHandle); return FAPI_OK; } //------------------------------------------------------------------ // Function sampleEnrollment //------------------------------------------------------------------ // Enrolls a fingerprint object int sampleEnrollment() { int retCode = FAPI_OK; FAPIDeviceHandle DeviceHandle; FAPIArchiveHandle ArchiveHandle; FAPIPersonID PersonID; FAPIReferenceID ReferenceID; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPIPersonDataMemBlock PersonData; strncpy(ModuleName,"module1",16); printf("ModuleName :%s\n", ModuleName); //-------------------------------------------- // Open Sensor retCode = FAPIAcquireDevice(ConfigurationPath, ModuleName, ModulePort, &DeviceHandle); if (retCode != FAPI_OK) return retCode; //-------------------------------------------- // Open Archiv retCode = FAPIAcquireArchive(ConfigurationPath, ModuleName, ModulePort, &ArchiveHandle); if (retCode != FAPI_OK)

ID Module SDK V1.05


return retCode; // build PersonData i.e. call FAPIGetPersonData PersonID = 55; retCode = FAPIGetPersonData(&ArchiveHandle, PersonID, &PersonData); if (retCode != FAPI_OK) { return retCode; } //-------------------------------------------- // Enroll ReferenceID = 4; printf("\nprocessing FAPIEnrollment ...\n"); retCode = FAPIEnrollment(&DeviceHandle, &ArchiveHandle, FAPI_SINGLE_MODE, &PersonData, ReferenceID, CallBackFunc); //-------------------------------------------- // Close Devices FAPIFree((FAPIGenericHandle)&PersonData); FAPIReleaseDevice(&DeviceHandle); FAPIReleaseArchive(&ArchiveHandle); return retCode; } //------------------------------------------------------------------ // Function sampleArchiveManagement //------------------------------------------------------------------ // Show use of archive management functions int sampleArchiveManagement() { int retCode = FAPI_OK; FAPIArchiveHandle ArchiveHandle; FAPIPersonID PersonID = 33; FAPIReferenceID ReferenceID = 4; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPIPersonDataMemBlock PersonData; FAPIPersonMemBlock Person; FAPIReferenceMemBlock Reference; FAPIPersonIterator PersonIterator = 0; FAPIReferenceIterator ReferenceIterator; strncpy(ModuleName,"module1",16); printf("ModuleName :%s\n", ModuleName); //-------------------------------------------- // Open Archiv retCode = FAPIAcquireArchive(ConfigurationPath, ModuleName, ModulePort, &ArchiveHandle); if (retCode != FAPI_OK) return retCode; //------------------------------------------- // Delete Person

ID Module SDK V1.05


PersonID = 33; retCode = FAPIDeletePerson(&ArchiveHandle, PersonID); if (retCode != FAPI_OK) { return retCode; } //------------------------------------------- // Delete Reference fromPerson PersonID = 55; ReferenceID = 4; retCode = FAPIDeleteReferenceFromPerson(&ArchiveHandle, PersonID, ReferenceID); if (retCode != FAPI_OK) { return retCode; } //------------------------------------------- // Delete Archive! /* retCode = FAPIDeleteArchive(&ArchiveHandle, PersonID, ReferenceID); if (retCode != FAPI_OK) return retCode; */ //------------------------------------------ // Get Person PersonID = 66; retCode = FAPIGetPerson(&ArchiveHandle, PersonID, &Person); if (retCode != FAPI_OK) { return retCode; } FAPIFree((FAPIGenericHandle)&Person); //------------------------------------------ // Get PersonData PersonID = 44; retCode = FAPIGetPersonData(&ArchiveHandle, PersonID, &PersonData); if (retCode != FAPI_OK) { return retCode; } FAPIFree((FAPIGenericHandle)&PersonData); //------------------------------------------ // Get Reference from Person PersonID = 66; ReferenceID = 7; retCode = FAPIGetReferenceFromPerson(&ArchiveHandle, PersonID, ReferenceID, &PersonData, &Reference); if (retCode != FAPI_OK) { return retCode; } FAPIFree((FAPIGenericHandle)&Reference); FAPIFree((FAPIGenericHandle)&PersonData);

ID Module SDK V1.05


//------------------------------------------ // Enumerate PersonData PersonIterator = 0; retCode = FAPIEnumPersonData(&ArchiveHandle, &PersonIterator, &PersonData); if (retCode != FAPI_OK) { return retCode; } if ( PersonData.dpPersonData != NULL ) { PersonID = (FAPIPersonID)(*(FAPIPersonID*)PersonData.dpPersonData); } printf("FAPIEnumPersonData : PersonID = %ld\n", PersonID); FAPIFree((FAPIGenericHandle)&PersonData); while (retCode == 0) { retCode = FAPIEnumPersonData(&ArchiveHandle, &PersonIterator, &PersonData); if (retCode == FAPI_OK ) { if ( PersonData.dpPersonData != NULL ) { PersonID = (FAPIPersonID)(*(FAPIPersonID*)PersonData.dpPersonData); } printf("FAPIEnumPersonData : PersonID = %ld\n", PersonID); } else if (retCode != FAPI_OK) { FAPIReleaseArchive(&ArchiveHandle); return retCode; } FAPIFree((FAPIGenericHandle)&PersonData); } //------------------------------------------ // Enumerate Person PersonIterator = 0; retCode = FAPIEnumPerson(&ArchiveHandle, &PersonIterator, &Person); if (retCode != FAPI_OK) { return retCode; } if ( Person.dPersonData.dpPersonData != NULL ) { PersonID = (FAPIPersonID)(*(FAPIPersonID*)Person.dPersonData.dpPersonData); } printf("FAPIEnumPerson : PersonID = %ld\n", PersonID); FAPIFree((FAPIGenericHandle)&Person); while (retCode == 0) { retCode = FAPIEnumPerson(&ArchiveHandle, &PersonIterator, &Person); if (retCode == FAPI_OK ) { if ( Person.dPersonData.dpPersonData != NULL ) { PersonID = (FAPIPersonID)(*(FAPIPersonID*)Person.dPersonData.dpPersonData); }

ID Module SDK V1.05


printf("FAPIEnumPerson : PersonID = %ld\n", PersonID); } else if (retCode != FAPI_OK) { FAPIReleaseArchive(&ArchiveHandle); return retCode; } FAPIFree((FAPIGenericHandle)&Person); } //------------------------------------------ // Enumerate References of a Person ReferenceIterator.dPersonID = 55; ReferenceIterator.dReferenceID = FAPI_START_ITERATION; retCode = FAPIEnumReferenceFromPerson(&ArchiveHandle, &ReferenceIterator, &PersonData, &Reference); if (retCode != FAPI_OK) { return retCode; } printf("FAPIEnumReferenceFromPerson : dPersonID = %ld / dReferenceID = %ld\n", ReferenceIterator.dPersonID,ReferenceIterator.dReferenceID); FAPIFree((FAPIGenericHandle)&Reference); FAPIFree((FAPIGenericHandle)&PersonData); while (retCode == 0) { retCode = FAPIEnumReferenceFromPerson(&ArchiveHandle, &ReferenceIterator, &PersonData, &Reference); if (retCode == FAPI_OK ) { printf("FAPIEnumReferenceFromPerson : dPersonID = %ld / dReferenceID = %ld\n", ReferenceIterator.dPersonID,ReferenceIterator.dReferenceID); } else if (retCode != FAPI_OK) { FAPIReleaseArchive(&ArchiveHandle); return retCode; } FAPIFree((FAPIGenericHandle)&Reference); FAPIFree((FAPIGenericHandle)&PersonData); } retCode = FAPIReleaseArchive(&ArchiveHandle); if (retCode != FAPI_OK) { return retCode; } return FAPI_OK; } //------------------------------------------------------------------ // Function sampleArchiveManagementUpdate //------------------------------------------------------------------ // Show use of archive management functions int sampleArchiveManagementUpdate() { int retCode = FAPI_OK;

ID Module SDK V1.05


FAPIArchiveHandle ArchiveHandle; FAPIPersonID PersonID = 33; FAPIPersonID ReturnPersonID = 1; FAPIReferenceID ReferenceID = 4; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPIPersonDataMemBlock PersonData; FAPIPersonMemBlock Person; strncpy(ModuleName,"module1",16); printf("ModuleName :%s\n", ModuleName); //-------------------------------------------- // Open Archiv retCode = FAPIAcquireArchive(ConfigurationPath, ModuleName, ModulePort, &ArchiveHandle); if (retCode != FAPI_OK) { return retCode; } //------------------------------------------- // Change PersonData // build persondata retCode = FAPIChangePersonData(&ArchiveHandle, &PersonData); if (retCode != FAPI_OK) { return retCode; } //------------------------------------------- // Get free PersonID PersonID = 500; retCode = FAPIGetPersonID(&ArchiveHandle, PersonID, &ReturnPersonID); if (retCode != FAPI_OK) { return retCode; } printf("FAPIGetPersonID : / min. PersonID = %ld / returned PersonID = %ld \n", PersonID,ReturnPersonID); //------------------------------------------- // Add Person PersonID = 55; ReferenceID = 4; // Build Person ... retCode = FAPIAppendPerson(&ArchiveHandle, &Person); if (retCode != FAPI_OK) { return retCode; } retCode = FAPIReleaseArchive(&ArchiveHandle); if (retCode != FAPI_OK)

ID Module SDK V1.05


{ return retCode; } return FAPI_OK; } //------------------------------------------------------------------ // Function sampleModuleConfiguration //------------------------------------------------------------------ // Some module management functions concerning the module configuration! int sampleModuleConfiguration() { int retCode = FAPI_OK; FAPIDeviceHandle DeviceHandle; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPIConfigFlag ConfigFlag; FAPIConfigData ConfigData; FAPIModulePassword ActualModulePassword; FAPIModulePassword NewModulePassword; FAPIModuleOperationMode ModuleOperationMode; strncpy(ModuleName,"module1",16); printf("ModuleName :%s\n", ModuleName); //-------------------------------------------- // Open Device retCode = FAPIAcquireDevice(ConfigurationPath, ModuleName, ModulePort, &DeviceHandle); if (retCode != FAPI_OK) { return retCode; } //-------------------------------------------- // Configure the ID Module ConfigFlag = FAPI_USE_SENSOR_CONFIG | FAPI_USE_UART_CONFIG; retCode = FAPIConfigIDModule(&DeviceHandle, ConfigFlag); if (retCode != FAPI_OK) { return retCode; } //-------------------------------------------- // Change the ID Module operation mode ModuleOperationMode = FAPI_FULLYHOSTCONTROLLED_MODE; //-------------------------------------------- // Note: PASSWORD must be the actual password of the ID Module // otherwise an error occurs. strncpy(ActualModulePassword,"PASSWORD",16); retCode = FAPIChangeIDModuleOperationMode(&DeviceHandle, ActualModulePassword, ModuleOperationMode); if (retCode != FAPI_OK) { return retCode; }

ID Module SDK V1.05


//-------------------------------------------- // Change the ID Module security password strncpy(ActualModulePassword,"PASSWORD",16); strncpy(ActualModulePassword,"PASSWORD",16); retCode = FAPIChangeIDModulePassword(&DeviceHandle, ActualModulePassword, NewModulePassword); if (retCode != FAPI_OK) { return retCode; } //-------------------------------------------- // Read the ID Module Configuration ConfigData.dConfigFlag = FAPI_USE_POWERMGMT_CONFIG | FAPI_USE_ARCHIVE_CONFIG; retCode = FAPIReadConfigIDModule(&DeviceHandle, &ConfigData); if (retCode != FAPI_OK) { return retCode; } printf("FAPIReadConfigIDModule :\n"); printf("\tConfigData.dPowerMgmtConfigData.dActiveToIdle = %ld \n", ConfigData.dPowerMgmtConfigData.dActiveToIdle); printf("\tConfigData.dPowerMgmtConfigData.dIdleToOff = %ld \n", ConfigData.dPowerMgmtConfigData.dIdleToOff); printf("\tConfigData.dArchiveConfigData.dPersonDataSize = %ld \n", ConfigData.dArchiveConfigData.dPersonDataSize); printf("\tConfigData.dArchiveConfigData.dCountEncodedFP = %ld \n", ConfigData.dArchiveConfigData.dCountEncodedFP); retCode = FAPIReleaseDevice(&DeviceHandle); if (retCode != FAPI_OK) { return retCode; } return FAPI_OK; } //------------------------------------------------------------------ // Function sampleModuleManagement //------------------------------------------------------------------ // Some module management functions concerning selftest and status. int sampleModuleManagement() { int retCode = FAPI_OK; FAPIDeviceHandle DeviceHandle; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPITestResult TestResult; FAPIStateResponse StateResponse; FAPIFlashResponse FlashResponse; char* ModuleIdPtr; strncpy(ModuleName,"module1",16); printf("ModuleName :%s\n", ModuleName); //-------------------------------------------- // Open Device retCode = FAPIAcquireDevice(ConfigurationPath, ModuleName, ModulePort, &DeviceHandle);

ID Module SDK V1.05


if (retCode != FAPI_OK) { return retCode; } //-------------------------------------------- // SelfTest TestResult.dTestFlag = FAPI_TEST_ARCHIVE | FAPI_TEST_FIRMWARE; retCode = FAPISelfTest( &DeviceHandle, &TestResult); if (retCode != FAPI_OK) { return retCode; } printf("FAPISelfTest :\n"); printf("\tTestResult.dArchiveState = %ld \n", TestResult.dArchiveState); printf("\tTestResult.dFirmwareState = %ld \n", TestResult.dFirmwareState); //-------------------------------------------- // Read the ID Module status retCode = FAPIStateIDModule( &DeviceHandle, &StateResponse); if (retCode != FAPI_OK) { return retCode; } printf("FAPIStateIDModule :\n"); printf("\tStateResponse.dModuleState = %ld \n", StateResponse.dModuleState); printf("\tStateResponse.dARMFwVersion = %ld \n", StateResponse.dARMFwVersion); printf("\tStateResponse.dLEADFwVersion = %ld \n", StateResponse.dLEADFwVersion); ModuleIdPtr = (char*)(&(StateResponse.dModuleId[0])); printf("\tStateResponse.dModuleId = %02x %02x %02x %02x %02x %02x %02x %02x\n", (int)ModuleIdPtr[0],(int)ModuleIdPtr[1],(int)ModuleIdPtr[2],(int)ModuleIdPtr[3], (int)ModuleIdPtr[4],(int)ModuleIdPtr[5],(int)ModuleIdPtr[6],(int)ModuleIdPtr[7]); //-------------------------------------------- // Read the ID Module flash status retCode = FAPIStateIDModuleFlash( &DeviceHandle, &FlashResponse); if (retCode != FAPI_OK) { return retCode; } printf("FAPIStateIDModuleFlash :\n"); printf("\tFlashResponse.dFreeMemory = %ld \n", FlashResponse.dFreeMemory); printf("\tFlashResponse.dAllocatedMemory = %ld \n", FlashResponse.dAllocatedMemory); printf("\tFlashResponse.dNumberOfPersons = %ld \n", FlashResponse.dNumberOfPersons); printf("\tFlashResponse.dNumberOfRefs = %ld \n", FlashResponse.dNumberOfRefs); retCode = FAPIReleaseDevice(&DeviceHandle); if (retCode != FAPI_OK) { return retCode; } return FAPI_OK; }

ID Module SDK V1.05


//------------------------------------------------------------------ // Function sampleFirmwareDownload //------------------------------------------------------------------ // Download of the ID Module firmware int sampleFirmwareDownload() { int retCode = FAPI_OK; FAPIDeviceHandle DeviceHandle; FAPIConfigurationPath ConfigurationPath = "SOFTWARE\\Siemens\\ID Module SDK"; FAPIModuleName ModuleName; FAPIModulePort ModulePort = "com1"; FAPIFileName FirmwareFile = "firmware.txt"; FAPIFwCodeType FwCodeType = FAPI_APPLICATION_CODE; strncpy(ModuleName,"module1",16); printf("ModuleName :%s\n", ModuleName); //-------------------------------------------- // Open Device retCode = FAPIAcquireDevice(ConfigurationPath, ModuleName, ModulePort, &DeviceHandle); if (retCode != FAPI_OK) { return retCode; } //-------------------------------------------- // process the firmware domnload retCode = FAPILoadFirmware(&DeviceHandle, FirmwareFile, FwCodeType); retCode = FAPIReleaseDevice(&DeviceHandle); if (retCode != FAPI_OK) { return retCode; } return FAPI_OK; }