Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes

Installation Procedures

BioAPI, the MorphoSmart SDK, and the MorphoSmart Optic (MSO3XX/1300/CBM) USB drivers require Windows
2000 (SP2 or higher) or Windows XP. Device driver installation on Windows XP/2000 requires administrator
privileges.

1. Install MorphoSmart SDK 4.X.X.X or higher.

Insert the MorphoSmart SDK CD into the CD drive on your PC. If the installation procedure does not start, run
Setup.exe on the CD. Be sure you completely uninstall any older version of the MorphoSmart SDK. Note: If you are
developing applications using both the MorphoSmart SDK and MorphoKit on the same PC, you should install
MorphoKit first, and follow the special directions in the MorphoSmart SDK ReadMe.txt file.

2. Copy MorphoSmart SDK DLLs.

Copy files from folder PC\MS-SDK\DLL in the MorphoSmart SDK folder to the Windows System32 folder or to
another desired folder in the PATH.

3. Install the MorphoSmart USB driver from the MorphoSmart SDK (if necessary).

4. Copy BioAPI files to your hard drive, and set read/write permissions.
Insert the Morpho BioAPI Supplement CD into the CD drive on your PC. Copy the contents of the MorphoSmart
SDK folder on the CD to the MorphoSmart SDK installation folder (default location is C:\Program Files\
SAGEM SA\MorphoSmart SDK). Set read/write permissions on the BioAPI\build and BioAPI\MorphoBSPDemo
folders, subfolders, and files.

5. Set environment variables.

Set the variable MSOBIOAPI to the location of the BioAPI folder (for these installation instructions, the default
location is C:\Program Files\SAGEM SA\MorphoSmart SDK\BioAPI). Restart Visual C++ to ensure it reads this
environment variable.

6. Use batch files to install BioAPI files based on how your Visual C++ project is compiled.
Batch files are described in \MorphoSmart SDK\BioAPI\build in the “CD Contents” section.

7. Configure the BSP.

Run MorphoBSPConfig.exe in the BioAPI\build folder to configure the BSP. Refer to \MorphoSmart
SDK\BioAPI\build in “CD Contents” for details.

8. Change Project Settings for your Visual C++ projects.

Change the following Project Settings for your Visual C++ projects (refer to MorphoBSPDemo project settings):
 Link tab, Input category, Link Object/library modules: Add bioapi100.lib and bioapi_util.lib for all configurations.
 Link tab, Input category, Additional library path: Add $(MSOBIOAPI)\build\<compile_type>\lib for each compile
type (Debug, MemDebug, and Release).
 C/C++ tab, Preprocessor category, Additional include directories: Add $(MSOBIOAPI)\include, $
(MSOBIOAPI)\imports\cdsa\v2_0\inc for all configurations.

9. Compile and test your project using the BioAPI framework and the MorphoSmart BSP.

10. [Optional] Install Microsoft ADO and/or Jet components.

If calling BioAPI database functions returns database errors, your PC may need Microsoft Access database support
files:
 Microsoft Data Access Components (MDAC 2.6 or higher): http://msdn.microsoft.com/data/mdac/default.aspx.
 Microsoft Jet 4.0 Database Engine: http://support.microsoft.com/kb/239114 (Windows 2000 or XP downloads).
 MDAC and Jet updates: http://www.windowsupdate.com.

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 1
 CD Contents
\
The root folder contains the SAGEM Morpho biometric product warranty and software end-user license agreement.

\Acrobat
This folder contains Adobe Acrobat Reader 6.0 for reading the PDF files on the CD.

\MorphoSmart SDK\BioAPI\build
This folder contains batch files to install and uninstall the BioAPI MorphoSmart BSPs. The batch files are named
<action>_<compile_type>_BioAPI_MorphoSmart.bat, where:

<action> = Install or Uninstall

<compile_type> = Release, Debug, or MemDebug

(MemDebug is Debug with memory allocation/deallocation tracking. To use this, compile your application with
#define BioAPI_MEMTRACK_ON).

The Install batch files put BSP information into Module Directory Services (MDS) service provider databases, and
copies DLLs into the system folder (Windows XP: Windows\system32; Windows 2000: WINNT\system32). The
Uninstall batch files remove the information from the service provider databases and the system folder. To change
compile type, just run the required batch file for the new compile type. It is not required to run the uninstall batch
file for the active compile type before running the install batch file for the new compile type. Each batch file ends
with a pause so you can check for any errors.

Programs that use the MorphoSmart BSP must use the BSP version that matches the way the program was compiled
by Visual C++. For example, a program compiled as a Debug version must use the Debug version of the BSP, and
the corresponding BSP install batch file (Install_Debug_BioAPI_MorphoSmart.bat) must be run before the program
can properly use the MorphoSmart BSP. This also applies to precompiled DLLs, executables, and .lib files on this
CD (such as MorphoBSPDemo.exe), which are provided in all three compile types.

This folder also contains several other files:

 MorphoBSPConfig.exe: SAGEM Morpho program to choose the maximum number of records in a BioAPI
database, set the path to the MorphoSmartBSP.mdb database, set the output BIR format, and select the MSO
you want to use.

Settings for this BSP are contained in HKEY_LOCAL_MACHINE\Software\Sagem Morpho\-

MorphoSmartBSP.

The database limit is stored in the MaxDBRecords registry value. If there is no value in the registry, the
MorphoSmart BSP assumes 100. The BSP reads this limit when it is attached by BioAPI_ModuleAttach, and
compares against it when inserting new records; if the limit would be exceeded, the BSP reports a “database
full” error. BioAPI functions will fail if the maximum number of records exceeds the actual database capacity of
the MSO being used.

The MorphoSmart BSP uses a Microsoft Access database to store the templates and the BioAPI payload. The
path to this database is stored in the PayloadDatabase registry value. If there is no value in the registry, the
MorphoSmart BSP assumes the file named MorphoSmartBSP.mdb in the default directory. If this file doesn’t
exist it is automatically created.

The output BIR type is contained in the OutputBIRType registry value. See below for information regarding the
output BIR format.

Multiple USB and RS-232 MSOs can be connected to a single PC. The information about the selected MSO is
contained in the following registry values:
interface: USB for MSOs connected via or RS232 for MSOs connected via RS-232
SerialNumber: Serial number of the MSO to use (USB MSOs only)

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 2
 port_number: The COM port number, such as 1 for COM1 (RS-232 MSOs only)
baud_rate: The serial port speed (RS-232 MSOs only)

The BSP reads this configuration when it is attached by BioAPI_ModuleAttach. If the selected MSO (USB or RS-
232) is no longer connected to the PC, the BSP will try to choose the first MSO it finds connected via USB. If
no USB MSO has been selected in the registry, the BSP will again try to choose the first USB MSO (but will
not try to choose an RS-232 MSO automatically).

Only one MSO can be used at a time. If you need to use a different MSO, you must unload the BSP using
BioAPI_ModuleDetach before changing the MSO selection.

 MSOSyncDB.exe: SAGEM Morpho program to synchronize or clear the MorphoSmart and Microsoft Access
databases.

The MorphoSmart BSP uses two databases: one on the MSO itself, and a Microsoft Access database containing
template and payload information. The common element in both these databases is the user UUID. The BSP
checks that the databases are synchronized when it is attached by BioAPI_ModuleAttach. Both databases must
have the same number of records and the same set of UUIDs. If the databases are not in sync, the BSP returns
error 6176 (BioAPIERR_BSP_DEMO_DB_NOT_IN_SYNC). The databases might not be in sync because of a
database modification error or other database corruption, a change in the Microsoft Access database path
configuration for the BSP, or if the user has changed to use a different MSO.

MSOSyncDB.exe copies the Microsoft Access database contents into the MSO selected for use with the BSP:
[Synchronize databases] begins the synchronization process. The MSO database is cleared, then the UUID
and template information for each record in the Microsoft Access database is added to the MSO database.
For some MSOs, insertions can take several seconds per record.

[Cancel] stops the synchronization process, but the databases will not be synchronized.

[Clear databases] erases the records in both the MSO and the Microsoft Access databases.

MSOSyncDB can take three command-line parameters:

-database followed by the database name specifies the path of the payload database.
-sync will automatically start synchronization.
-clear will automatically clear the databases.

If these automatic processes finish successfully, MSOSyncDB will close.

\MorphoSmart SDK\BioAPI\build\<compile_type>\bin
 MorphoBSPDemo.exe: SAGEM Morpho program to demonstrate all the functions of the MorphoSmart BSP.
 Sample.exe: BioAPI Consortium sample program to demonstrate different BSPs.
 MdsEdit300.exe: Intel program to examine Module Directory Services, which contain information about the
capabilities of installed BSPs. It is strongly recommended that you not use this tool to edit the BSP information.

\MorphoSmart SDK\BioAPI\build\<compile_type>\dll
 MorphoSmartBSP.dll: SAGEM Morpho MorphoSmart BSP.
 bioapi_dummy100.dll, pwbsp.dll: BioAPI Consortium dummy (basic) and Password BSPs.
 bioapi100.dll, bioapi_mds300.dll: BioAPI Consortium Framework and utility DLLs.

\MorphoSmart SDK\BioAPI\build\<compile_type>\install
Utilities for installing the different BSPs. These are used by the batch files and do not need to be run separately.

\MorphoSmart SDK\BioAPI\build\<compile_type>\lib, \MorphoSmart SDK\BioAPI\addins,

\MorphoSmart SDK\BioAPI\imports, \MorphoSmart SDK\BioAPI\include
.lib and include files needed when compiling programs that use the MorphoSmart BSP.

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 3
\MorphoSmart SDK\BioAPI\Documentation
Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes.doc (this file)
BioAPI Specification V1.1_16-Mar-01.pdf

\MorphoSmart SDK\BioAPI\MorphoBSPDemo
This folder contains the source code and the Visual C++ project for MorphoBSPDemo, which demonstrates all the
functions of the MorphoSmart BSP. The source code provides samples of using all the supported BioAPI functions.

\MorphoSmart SDK\BioAPI\Redist
This folder contains batch files to install and uninstall files necessary for deployment of production systems:
bioapi100.dll, MorphoSmartBSP.dll, MorphoBSPConfig.exe, and MSOSyncDB.exe. These are installed into the
Windows system folder.

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 4
 Morpho BioAPI MorphoSmart BSP Supported Functions
The Morpho BioAPI Supplement for the MorphoSmart SDK provides a monolithic, identification Biometric
Service Provider (BSP) for two fingers/person in accordance with the BioAPI Specification V1.1, 16-Mar-01.
BioAPI_Init
BioAPI_Terminate
BioAPI_EnumModules
BioAPI_ModuleLoad
BioAPI_ModuleUnload
BioAPI_ModuleAttach
BioAPI_ModuleDetach
BioAPI_QueryDevice
BioAPI_FreeBIRHandle
BioAPI_GetBIRFromHandle
BioAPI_GetHeaderFromHandle
BioAPI_SetGUICallbacks
BioAPI_Capture
BioAPI_CreateTemplate
BioAPI_Process
BioAPI_VerifyMatch
BioAPI_IdentifyMatch
BioAPI_Enroll
BioAPI_Verify
BioAPI_Identify
BioAPI_Import
BioAPI_DbOpen
BioAPI_DbClose
BioAPI_DbCreate
BioAPI_DbDelete
BioAPI_DbSetCursor
BioAPI_DbFreeCursor
BioAPI_DbStoreBIR
BioAPI_DbGetBIR
BioAPI_DbGetNextBIR
BioAPI_DbQueryBIR
BioAPI_DbDeleteBIR
27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes
FRAMEWORK OPERATIONS
Does not check ElementsNeeded or NumElementsReturned for NULL pointers.
Does not check BSPUuid for NULL pointer.
BSP OPERATIONS
Handle Operations
Callback and Event Operations
If callbacks are not set, a simple default BSP GUI is provided for the capture sequence.
If callback functions have previously been specified, the default BSP GUI can be used by
supplying NULL pointer values for the callback functions.
Biometric Operations
Handles all purposes except Audit.
For enrollment using the default BSP GUI, three acquisitions are taken per finger, then
the minutiae are consolidated to yield the best enrollment templates. For identification
and verification, only one acquisition is taken per finger.
Input BIR must be either a BIR handle or a full BIR.
Purpose must be Enroll, Enroll for Verify or Enroll for Identify.
Input BIR data type must be processed (intermediate is not accepted).
Input BIR must be either a BIR handle or a full BIR.
Purpose must be Identify or Verify.
Input BIR data type must be intermediate.
Input BIR must be either a BIR handle or a full BIR.
The Population array must contain only processed BIRs.
The timeout value (for matching search time) is ignored.
Purpose must be Enroll, Enroll for Verification or Enroll for Identification.
The Population array must contain only processed BIRs.
This function is not supported in this BSP.
Database Operations
The only supported database is the default database, which is always open. The
DbName parameter is ignored and the DbHandle is always DEFAULT_DB_HANDLE.
The only supported database is the default database, which is always open. If the
DbHandle parameter is DEFAULT_DB_HANDLE, this returns BioAPI_OK, otherwise it
returns BioAPIERR_BSP_INVALID_DB_HANDLE.
The only supported database is the default database, which is always open. The
DbName parameter is ignored and the DbHandle is always DEFAULT_DB_HANDLE.
This function removes all records in the MSO and Access databases. The DbName
parameter is ignored.
The only supported database handle is DEFAULT_DB_HANDLE.
The only supported database handle is DEFAULT_DB_HANDLE.
The only supported database handle is DEFAULT_DB_HANDLE.
This function is not supported in this BSP.
The only supported database handle is DEFAULT_DB_HANDLE.
Page 5
Additional information for the MorphoSmart BSP
 Applications using the BSP must be compiled with optimizations turned off (or set to default).

 Function prototypes and usage are described in the BioAPI Specification V1.1, 16-Mar-01.

 The MorphoSmart BSP follows the BioAPI specification for memory management functions — the memory
management functions to be used are passed to BioAPI_ModuleAttach.

 The following BioAPI functions are not supported:

BioAPI_DbQueryBIR
BioAPI_EnableEvents
BioAPI_Import
BioAPI_SetStreamCallback
BioAPI_StreamInputOutput
BioAPI_SetPowerMode

 Adapted BIRs and binning are not supported.

 FRR is not supported. FARPrecedence is ignored.

 Array-type populations are limited to 100 BIRs for performance reasons. Databases created to be permanent
using BioAPI_DbCreate and populated with BioAPI_DbStoreBIR will give the best matching performance.

 Quality is supported for processed BIRs only. Audit BIRs report a quality value of -2 (not supported). For
processed BIRs that contain two templates (such as for enrollment), the lower of the two quality scores is stored
in the header.

 Audit BIRs are only supported for MSO devices connected via USB. MSOs connected via RS-232 are too slow
to return images in a timely manner. Attempts to return an audit BIR for a serial MSO will return
BioAPI_UNSUPPORTED_BIR_HANDLE for the AuditData handle.

 GUI callbacks are supported.

 Payload is supported. The payload can be any sequence of bytes, up to a length of 1024. Payload memory must
be freed by the application. The payload is stored in a Microsoft Access database with the path configured in the
registry. This database is not password-protected or encrypted. If the payload contains sensitive information,
you should encrypt the payload before providing it as part of a BIR that the MorphoSmart BSP will store in the
database.

 Morpho finger templates are compressed. The MorphoSmart BSP uses the default compression type controlled
by the parameter PK_COMP (see the MorphoSmart Programmer Guide).

 Applications should use either BioAPI or MorphoSmart functions, but not both. When the BSP is loaded with
BioAPI_ModuleAttach, it attempts to connect to the MSO. The device will be locked until
BioAPI_ModuleDetach is called. Attempting to use the MorphoSmart SDK at the same time will cause device
open failures.

 There is no information in a BIR describing finger position (which template corresponds to which finger). The
default BSP user interface always asks for the right index finger, then the left index finger, and stores the
templates in that order (right index first). This is also true for acquisitions whose minutiae are consolidated
(three right index captures, then three left index captures). BIRs with one template (or image) created using the
default BSP user interface store the right index template (image). If you develop your own user interface, you
can request any finger in any order, and the templates will be stored in the order requested. Templates stored in
an MSO database have no finger position information stored with them.

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 6
Working with biometric data and BIRs
This section describes the structure of a BIR with biometric data. It includes sample code for extracting Morpho
templates from a BIR or creating a BIR containing Morpho templates.

Extracting biometric data from a BIR

The BIR layout in the BioAPI Specifications looks like this:

typedef struct bioapi_hrs_bir

{
BioAPI_BIR_HEADER Header;
BioAPI_BIR_BIOMETRIC_DATA_PTR BiometricData;
BioAPI_DATA_PTR Signature;
} BioAPI_BIR, *BioAPI_BIR_PTR;

The BiometricData pointer is defined by SAGEM Morpho. It consists of a BIO_DATA_HEADER + the

biometric data.

At this point, the Signature is always NULL.

The BIO_DATA_HEADER looks like this:

typedef struct BioDataHeader

{
// Length of template 1
unsigned long Template1Length;
// Length of template 2
unsigned long Template2Length;
// Length of payload
uint32 PayloadLength;
} BIO_DATA_HEADER;

The rest of the biometric data comes after this header.

Below is sample code that extracts Morpho templates from a BIR. The code captures two fingerprints, then reads the
BIR header, gets the fingerprint data, and puts it in buffers pointed to by pTemplate1 and pTemplate2.

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 7
// Sample code to extract MorphoSmart templates from a BIR

BioAPI_RETURN bioReturn;
BioAPI_BIR_HANDLE CapturedBIRHandle;
bioReturn = BioAPI_Capture(BSPMODULEFILEHANDLE,
BioAPI_PURPOSE_ENROLL, &CapturedBIRHandle, 20000, NULL);

// Get BIR from BIR handle

BioAPI_BIR_PTR pBIRData = NULL;
bioReturn = BioAPI_GetBIRFromHandle(BSPMODULEFILEHANDLE,
CapturedBIRHandle, &pBIRData);

// Get the header information

BIO_DATA_HEADER header;
memcpy(&header, pBIRData->BiometricData, sizeof(header));

// Allocate memory for templates and payload

BYTE* pTemplate1 = (BYTE*)malloc(header.Template1Length);
BYTE* pTemplate2 = (BYTE*)malloc(header.Template2Length);
BYTE* pPayload = (BYTE*)malloc(header.PayloadLength);

// pSourcePtr points to the current data to copy

BYTE* pSourcePtr = pBIRData->BiometricData + sizeof(header);

// Get template 1
memcpy(pTemplate1, pSourcePtr, header.Template1Length);
pSourcePtr += header.Template1Length;

// Get template 2
memcpy(pTemplate2, pSourcePtr, header.Template2Length);
pSourcePtr += header.Template2Length;

// Get payload
memcpy(pPayload, pSourcePtr, header.PayloadLength);

// These templates can be used with the MorphoSmart SDK functions.

// They can be passed to the C_MORPHO_TemplateList::PutTemplate
// function with MORPHO_PK_COMP for i_uc_typTemplate.

// Free all the memory allocated for the BIR

free(pBIRData->BiometricData);
free(pBIRData);

Creating a BIR from Morpho templates

Below is sample code that creates a BIR from Morpho templates. To use this properly,
NewBIR.Header.Quality must be set to the correct quality value, and NewBIR.Header.PurposeMask
must be set to the correct purpose.

// Sample code to create a BIR from MorphoSmart SDK templates

// This assumes the following variables have been set:

// pTemplate1: Pointer to first template, NULL if none
// Template1Length: Length of data pointed to by pTemplate1
// pTemplate2: Pointer to second template, NULL if none
// Template2Length: Length of data pointed to by pTemplate2
// pPayload: Pointer to payload, NULL if none

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 8
// PayloadLength: Length of data pointed to by pPayload
// The templates can be retrieved with the
// C_MORPHO_TemplateList::GetTemplate API.

// Build the BIO_DATA_HEADER DataHeader

DataHeader.Template1Length = Template1Length;
DataHeader.Template2Length = Template2Length;
DataHeader.PayloadLength = PayloadLength;

// Allocate space for the templates and SAGEM Morpho header

size_t TotalDataLength = sizeof(DataHeader) +
Template1Length + Template2Length + PayloadLength;
BYTE* pData = (BYTE*)malloc(TotalDataLength);
BYTE* pDest = pData;

// Copy the templates

memcpy(pDest, &DataHeader, sizeof(DataHeader));
pDest += sizeof(DataHeader);

if (Template1Length > 0 && pTemplate1 != NULL)

{
memcpy(pDest, pTemplate1, Template1Length);
pDest += Template1Length;
}
if (Template2Length > 0 && pTemplate2 != NULL)
{
memcpy(pDest, pTemplate2, Template2Length);
pDest += Template2Length;
}
if (PayloadLength > 0 && pPayload != NULL)
{
memcpy(pDest, pPayload, PayloadLength);
}

// Build the BIR and the BIR header

BioAPI_BIR NewBIR;
ZeroMemory(&NewBIR, sizeof(NewBIR));

NewBIR.Header.Length = sizeof(NewBIR.Header) + TotalDataLength;

NewBIR.Header.HeaderVersion = 1;
NewBIR.Header.Type = BioAPI_BIR_DATA_TYPE_PROCESSED;
NewBIR.Header.Format.FormatOwner = 0x1D;
NewBIR.Header.Format.FormatID = 0;

// Must be set to the correct quality

NewBIR.Header.Quality = 0;

// Must be set to the correct purpose

NewBIR.Header.PurposeMask = BioAPI_PURPOSE_VERIFY;

NewBIR.Header.FactorsMask = BioAPI_FACTOR_FINGERPRINT;

// Put the biometric data in the BIR

NewBIR.BiometricData = pData;

// After using the BIR, be sure to free the memory it used

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 9
27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 10
Working with audit data and images
Audit BIRs returned by this BSP consist of a BIO_IMAGE_HEADER + the image bytes.

The BIO_IMAGE_HEADER looks like this:

typedef struct BioImageHeader

{
uint32 ImageWidth;
uint32 ImageHeight;
} BIO_IMAGE_HEADER;

If there is one image, the BIO_IMAGE_HEADER will be followed by ImageWidth * ImageHeight bytes. If
there are two images, the BIO_IMAGE_HEADER will be followed by 2 * ImageWidth * ImageHeight
bytes. The images are 8-bit grayscale images.

27-Jan-06 Morpho BioAPI Supplement Version for MorphoSmart SDK Developer Notes Page 11