Version 2.

FPCaptureAccess SDK
Programmer’s Guide
© 2009 Cogent, Inc. All rights reserved.

This document contains commercial information and trade secrets of Cogent, Inc. which are confidential and
proprietary in nature and are subject to protection under law. Access to the information contained herein, howsoever
acquired and of whatsoever nature, will not entitle the accessor thereof to acquire any right thereto. The data subject to
this restriction are contained in all sheets of this document. Disclosure of any such information or trade secrets shall
not be made without the prior written permission of Cogent, Inc.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any
means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Cogent,
Inc.

The information in this document is subject to change without notice. The software mentioned in this document is
furnished under license and may only be used or copied in accordance with the terms of such license. Contact software
manufacturers directly for terms of software licenses for any software mentioned in this document not originating from
Cogent, Inc.

All brand or product names are the trademarks or registered trademarks of their respective holders.

Cogent Document # IG-EXT-AP-895-0.00 (1)

Document Revision History

Version Date Author Comment

1.0 05/14/2008 Integration Group Initial version

1.1 05/22/2008 Integration Group Updated the document

1.2 12/04/2008 Integration Group Updated the document

1.3 04/30/2009 Integration Group Updated the document

1.4 06/01/2009 Integration Group Updated the document

1.5 07/20/2009 Integration Group Updated the document

1.6 12/21/2009 Integration Group Updated the document

1.7 05/12/2010 Integration Group Updated the document

1.8 05/21/2011 Integration Group Added a function to set up option.

1.9 09/07/2011 Integration Group Added another callback function

1.10 09/23/2012 Integration Group Updated LED setting description

1.11 04/22/2012 Integration Group Updated the document

2.0 11/15/2013 Integration Group Updated system capability

2.1 04/29/2014 SDO Consolidated the error codes

Contents

1 Overview 1

2 Key Terms 1

3 System Requirements 2

4 SDK Usage 3
4.1 SDK Implementation...................................................................................................... 3
4.2 General Information ...................................................................................................... 3
4.3 Typical Workflow to Acquire Images............................................................................. 3
4.3.1 Using One Scanner ............................................................................................ 3
4.3.2 Using Multiple Scanners.................................................................................... 6

5 Integrating with a Device 10

5.1 Getting Started ............................................................................................................ 10
5.2 Acquiring Fingerprints ................................................................................................ 11
5.2.1 Starting an Acquisition.................................................................................... 11
5.2.2 Handling Each Frame ...................................................................................... 11
5.2.3 Getting the Final Fingerprint Image ................................................................ 11
5.2.4 Putting It All Together..................................................................................... 11
5.3 Closing a Device .......................................................................................................... 14
5.4 Accessing Maintenance Data....................................................................................... 14
5.5 Control LED ................................................................................................................. 14
5.6 Control Beeper............................................................................................................. 16
5.7 API Functions............................................................................................................... 17
5.7.1 CG4_Main_GetConnectedScanner ................................................................... 18
5.7.2 CG4_Main_GetAPIVersion ................................................................................ 19
5.7.3 CG4_Main_GetRunningInfo ............................................................................. 20
5.7.4 CG4_Main_Initialize ......................................................................................... 21
5.7.5 CG4_Main_DeInitialize .................................................................................... 22
5.7.6 CG4_Main_FastStartup .................................................................................... 23
5.7.7 CG4_Main_StandBy.......................................................................................... 24
5.7.8 CG4_Main_GetDeviceInfo ................................................................................ 25
5.7.9 CG4_Capture_SetMode.................................................................................... 26
5.7.10 CG4_Capture_Start .......................................................................................... 27
5.7.11 CG4_Capture_Abort ........................................................................................ 28
5.7.12 CG4_Capture_TakeResultImage ...................................................................... 29
5.7.13 CG4_Capture_AcquireResultImage ................................................................. 30
5.7.14 CG4_Controls_SetStateLEDs ............................................................................ 31
5.7.15 CG4_Controls_SetLEDs .................................................................................... 32

Contents iii
Proprietary
 5.7.16 CG4_Controls_Beeper...................................................................................... 33
5.7.17 CG4_Capture_SetCaptureOK ........................................................................... 34
5.7.18 CG4_Capture_SetStartRollingFlag ................................................................... 35
5.7.19 CG4_Capture_GetRollParameters .................................................................... 36
5.7.20 CG4_Capture_SetRollParameters .................................................................... 37
5.7.21 CG4_Capture_Calibration ................................................................................ 38
5.7.22 CG4_Controls_RegisterFootSwitchInfo............................................................ 39
5.7.23 CG4_Capture_RegisterCallbackPreviewImage................................................. 40
5.7.24 CG4_Capture_RegisterCallbackTakingResultImage ........................................ 41
5.7.25 CG4_Capture_RegisterCallbackResultImage ................................................... 42
5.7.26 CG4_Capture_RegisterCallbackFootSwitch ..................................................... 43
5.7.27 CG4_Capture_RegisterCallbackKeypad ........................................................... 44
5.7.28 CG4_Capture_RegisterCallbackObjectQuality................................................. 45
5.7.29 CG4_Capture_RegisterCallbackObjectPosition ............................................... 46
5.7.30 CG4_Capture_RegisterCallbackDeviceIsConnected ........................................ 47
5.7.31 CG4_CallbackPreviewImage ............................................................................ 48
5.7.32 CG4_CallbackResultImage .............................................................................. 49
5.7.33 CG4_CallbackFootSwitch................................................................................. 50
5.7.34 CG4_CallbackKeypad ...................................................................................... 51
5.7.35 CG4_CallbackObjectQuality ............................................................................ 52
5.7.36 CG4_CallbackDeviceIsConnected.................................................................... 53
5.7.37 CG4_Capture_GetImageMask .......................................................................... 54
5.7.38 CG4_Capture_SetAutoCapInfo ........................................................................ 55
5.7.39 CG4_Capture_SetAutoCapArea ....................................................................... 56
5.7.40 CG4_Capture_SetAutoCapFinMask ................................................................. 57
5.7.41 CG4_Control_CmdSetValue ............................................................................. 58

6 Integrating with Multiple Devices 59

6.1 Getting Started ............................................................................................................ 59
6.2 Acquiring Fingerprints ................................................................................................ 61
6.2.1 Starting an Acquisition.................................................................................... 61
6.2.2 Handling Each Frame ...................................................................................... 61
6.2.3 Getting the Final Fingerprint Image ................................................................ 61
6.2.4 Putting It All Together..................................................................................... 62
6.3 Closing All Scanner Devices ........................................................................................ 64
6.4 Accessing Maintenance Data....................................................................................... 65
6.5 Control LED ................................................................................................................. 65
6.6 Control Beeper............................................................................................................. 66
6.7 API Functions............................................................................................................... 66
6.7.1 CG4_M_Main_GetConnectedScanner .............................................................. 67
6.7.2 CG4_M_Main_GetAPIVersion ........................................................................... 68
6.7.3 CG4_M_Main_GetRunningInfo......................................................................... 69
6.7.4 CG4_M_Main_Initialize .................................................................................... 70

Contents iv
Proprietary
 6.7.5 CG4_M_Main_DeInitialize ................................................................................ 71
6.7.6 CG4_M_Main_DeInitializeAll............................................................................ 72
6.7.7 CG4_M_Main_IsInitialized ............................................................................... 73
6.7.8 CG4_M_Main_GetDeviceInfo............................................................................ 74
6.7.9 CG4_M_Capture_SetMode ............................................................................... 75
6.7.10 CG4_M_Capture_Start ..................................................................................... 76
6.7.11 CG4_M_Capture_Abort .................................................................................... 77
6.7.12 CG4_M_Capture_TakeResultImage ................................................................. 78
6.7.13 CG4_M_Capture_AcquireResultImage ............................................................. 79
6.7.14 CG4_M_Controls_SetStateLEDs ....................................................................... 80
6.7.15 CG4_M_Controls_SetLEDs ............................................................................... 81
6.7.16 CG4_M_Controls_Beeper ................................................................................. 82
6.7.17 CG4_M_Capture_SetCaptureOK ...................................................................... 83
6.7.18 CG4_M_Capture_SetStartRollingFlag............................................................... 84
6.7.19 CG4_M_Capture_GetRollParameters ............................................................... 85
6.7.20 CG4_M_Capture_SetRollParameters ................................................................ 86
6.7.21 CG4_M_Capture_Calibration ........................................................................... 87
6.7.22 CG4_M_Controls_RegisterFootSwitchInfo ....................................................... 88
6.7.23 CG4_M_Capture_RegisterCallbackPreviewImage ............................................ 89
6.7.24 CG4_M_Capture_RegisterCallbackTakingResultImage ................................... 90
6.7.25 CG4_M_Capture_RegisterCallbackResultImage .............................................. 91
6.7.26 CG4_M_Capture_RegisterCallbackFootSwitch................................................. 92
6.7.27 CG4_M_Capture_RegisterCallbackKeypad ...................................................... 93
6.7.28 CG4_M_Capture_RegisterCallbackObjectQuality ............................................ 94
6.7.29 CG4_M_Capture_RegisterCallbackObjectPosition........................................... 95
6.7.30 CG4_M_Capture_RegisterCallbackDeviceIsConnected.................................... 96
6.7.31 CG4_CallbackPreviewImage ............................................................................ 97
6.7.32 CG4_CallbackResultImage .............................................................................. 98
6.7.33 CG4_CallbackFootSwitch................................................................................. 99
6.7.34 CG4_CallbackKeypad .................................................................................... 100
6.7.35 CG4_CallbackObjectQuality .......................................................................... 101
6.7.36 CG4_M_Capture_GetImageMask ................................................................... 102
6.7.37 CG4_M_Capture_SetAutoCapInfo .................................................................. 103
6.7.38 CG4_M_Capture_SetAutoCapArea ................................................................. 104
6.7.39 CG4_M_Capture_SetAutoCapFinMask ........................................................... 105
6.7.40 CG4_M_Control_CmdSetValue ...................................................................... 106

7 Structure Reference 107

7.1 CG4ScannerExist ....................................................................................................... 107
7.2 CG4ApiVersion .......................................................................................................... 107
7.3 CG4PropertyInfo ........................................................................................................ 107
7.4 CG4RunningInfo ........................................................................................................ 108
7.5 CgRollParameters ...................................................................................................... 108

Contents v
Proprietary
 7.6 ImageData ................................................................................................................. 109
7.7 CG4MScannerExist .................................................................................................... 110
7.8 CG4AutoCapInfo........................................................................................................ 110

8 Enumeration Reference 112

8.1 CG4ImageType .......................................................................................................... 112
8.2 CG4ImageResolution ................................................................................................. 113
8.3 CG4LedType .............................................................................................................. 113
8.4 CG4ScannerType ....................................................................................................... 114
8.5 Image Format ............................................................................................................ 114
8.6 CG4ObjectQualityState .............................................................................................. 114
8.7 CG4ObjectCountState ............................................................................................... 115
8.8 CG4KeypadType ........................................................................................................ 115

Appendix A Code Definitions 116

A.1 Generic Error Codes .................................................................................................. 116
A.2 Device Related Error Codes ....................................................................................... 116
A.3 Mosaic Error Codes ................................................................................................... 117
A.4 Command mask macro ............................................................................................. 119

Contents  vi
Proprietary
1 Overview
The Cogent Fingerprint Capture (FPCaptureAccess) SDK provides a customizable interface for
the following Cogent fingerprint scanning devices:
CS500i scanner
CS500e scanner
CS500P scanner
CS1000P scanner
CS1000e scanner
CSD450, CSD450F scanner
CSD330, CSD330X scanner
CSD200 scanner CSD200i (CSD200 2013) scanner

The FPCaptureAccess SDK is a low-level SDK that provides the following functionality:
Operate each supported scanner,
The SDK is provided as a dynamic link library (DLL), and
Sample code (Visual C++ 6.0) and .Net wrapper are provided.

The FPCaptureAccess SDK is designed to be used by the OEM vendor so that they can build their
own graphical user interface, workflows, or image processing algorithms on the top of this SDK
and the corresponding drivers.

The SDK is provided as a DLL version with the sample code written in Visual C++ 6.0 as well as .Net
wrapper sample code. The SDK provides software programmers with all of the necessary
information for designing a complete biometric solution based on the 3M fingerprint/palm
scanner product line.

The interfaces of this SDK are designed to be open for support of new scanner devices as they
become available. This ensures that minimum effort is needed by the customer to integrate new
devices into an existing biometric solution.

2 Key Terms
This section describes key terms that are used throughout this Guide.

Term Description

Software Development Kit (SDK) An SDK is a programming package that enables

programmers to develop applications for a specific
platform. Typically, an SDK includes one or more APIs,

2 - Key Terms 1
Proprietary
 programming tools, and documentation.
Application Program Interface (API) An API is a set of routines, protocols, and tools for
building software applications.

3 System Requirements
The following minimum system requirements are necessary in order to use the SDK described
in this document:

Operating System:
Windows 2000 with Service Pack 4
Windows XP with Service Pack 3

Windows Vista
Windows 7 SP1 32-bit and 64-bit
Windows 8 32-bit and 64-bit (Exclude Windows RT)

Tools:
Microsoft Visual C++ 6.0, Microsoft Visual Stuido 2008

Hardware:
CPU: Core 2 Due 2.4 GHz
Memory:
1G or more memory for CS450, CS500i and CS500e
2G RAM or more memory for CS500P , CS1000P and CS1000e.
Graphics Adapter: Graphics card supporting 1024 x 768 x 24 bit colors with DirectDraw
Support, 8 MB video memory or above
PC Interface:
USB 2.0
USB 3.0 (exclude palm scanner model (CS500p)
IEEE 1394B for CS1000P, OHCI-compliant
Monitor: Supports 1024 x 768 displays. A 19-inch monitor is recommended for displaying a
resolution of 1280 x 1024. Touch-screen is an option.

3 - System Requirements 2
Proprietary
4 SDK Usage

4.1 SDK Implementation

In order to use the SDK, please include the following header files to your project:
CG4EssentialsApi.h – interface functions for using one Cogent scanner, type definitions,
constants, enumerations, and SDK related return codes
CG4EssentialsApiM.h – interface functions, type definitions, constants and enumerations for
using multiple scanners
If you plan to load the DLL statically, then the following files need to be specified for linkage:
CG4EssentialsApi.lib

At runtime, the following files need to be accessible:

CG4EssentialsApi.dll – the main runtime library
ClydeMosaic.dll – mosaic arithmetic runtime library
ResolutionImprove.dll – device related runtime library

4.2 General Information

If a function returns a status that is smaller than CG4_STATUS_OK, then the return parameter
values might be invalid.

Notes
Be sure nothing is on the platen during call CG4_Main_Initialize(CG4_M_Main_Initialize)/
CG4_Capture_Calibration(CG4_M_Capture_Calibration). During the time when the
application initializes the capture device, the optimal capture settings are determined by the
software through interactions with the hardware device. If the platen is not clear of debris
the resulting ‘calibration’ settings may not be optimal.

4.3 Typical Workflow to Acquire Images

4.3.1 Using One Scanner

The typical workflow to acquire images is provided below:

1. Call CG4_Main_Initialize() to initialize the device for image acquisition.
2. Call CG4_Capture_SetRollParameters() to set up the initialization parameters.
3. Call CG4_Capture_Calibration() to calibrate the device.
4. Call the appropriate callback registration functions to retrieve the required notifications.
5. Call CG4_Capture_SetMode() to select the correct acquisition type.
6. Call CG4_Capture_Start() to start image acquisition.
4 - SDK Usage 3
Proprietary
7. Initiate the result image acquisition is triggered automatically (auto capture) and/or
manually by CG4_Capture_TakeResultImage().
8. Call CG4_Capture_AcquireResultImage() to acquire the result image. It might take several
seconds, expect a delay.
9. The result image that is passed as ImageData to the callback function
CG4_CallbackResultImage() can be obtained.
10. Call CG4_Main_DeInitialize() when finished using the device.

Rolled and Flat capture process diagrams are provided below:

Application Capture SDK

Application SDK
Thread Thread

CG4_Capture_RegisterCallbackPreviewImage(OnPreviewImageAvailable)

CG4_Capture_RegisterCallbackResultImage(OnResultImageAvailable)

CG4_Capture_SetMode(CG4_ROLL_SINGLE_FINGER) OnPreviewImageAvailable callback is

invoked after call to SetMode
Signal(Begin Preview)

OnPreviewImageAvailable()
Application gets the running info within the
preview callback. This information applies
to rolled capture only.
CG4_Main_GetRunningInfo()
The rolled capture feature is enabled after
CG4_Capture_Start(1 object) the start function call

The preview callback is invoked repeatedly

until TakeResultImage() is called Signal(Start Capture)

OnPreviewImageAvailable()
The SDK determines if the rolled capture is
CG4_Main_GetRunningInfo()
complete and sets the running info flags
Application checks running info to determine accordingly and stops the capture of new
if a rolled capture is complete images.
Signal(Capture)

CG4_Capture_TakeResultImage()

Signal(Stop Preview)

CG4_Capture_AcquireResultImage()

Signal(Capture)

OnResultImageAvailable()
The OnResultImageAvailable function is
called when the AcquireResultImage
ImageData function is invoked
The image data is returned as a parameter
of the OnResultImageAvailable() callback
interface

Figure 4-1 Rolled Capture Diagram

4 - SDK Usage 4
Proprietary
 Application Capture SDK
Application SDK
Thread Thread

CG4_Capture_RegisterCallbackPreviewImage(OnPreviewImageAvailable)

CG4_Capture_RegisterCallbackResultImage(OnResultImageAvailable)

CG4_Capture_RegisterCallbackObjectQuality(OnObjectQuality)
OnPreviewImageAvailable callback is
CG4_Capture_SetMode(CG4_FLAT_RIGHT_FINGERS, AutoCapture=true) invoked after call to SetMode

Signal(Begin Preview)

OnPreviewImageAvailable()

Application gets the running info within the

preview callback. This information applies
to rolled capture only.

CG4_Main_GetRunningInfo()
The auto-capture feature is enabled after
CG4_Capture_Start(4 objects) the start function call

Signal(Start Capture)
The preview callback is invoked repeatedly
until auto-capture or an the take image
function is invoked.
OnPreviewImageAvailable()

CG4_Main_GetRunningInfo()
The object quality callback is invoked when
the SDK capture criteria are met
OnObjectQuality()
Application manual capture criteria not met.
SDK auto-capture criteria met

Signal(Stop Preview)

Signal(Capture)

OnResultImageAvailable()
The OnResultImageAvailable function is
The image data is returned as a parameter called when the auto-capture criteria are
ImageData
of the OnResultImageAvailable() callback met
interface

Figure 4-2 Flat Auto Capture Diagram

4 - SDK Usage 5
Proprietary
 Application Capture SDK
Application SDK
Thread Thread

CG4_Capture_RegisterCallbackPreviewImage(OnPreviewImageAvailable)

CG4_Capture_RegisterCallbackResultImage(OnResultImageAvailable)

CG4_Capture_RegisterCallbackObjectQuality(OnObjectQuality)
OnPreviewImageAvailable callback is
CG4_Capture_SetMode(CG4_FLAT_RIGHT_FINGERS, AutoCapture=false) invoked after call to SetMode

Signal(Begin Preview)

OnPreviewImageAvailable()

Application gets the running info within the

preview callback. This information applies
to rolled capture only.
CG4_Main_GetRunningInfo()
The auto-capture feature is enabled after
the start function call
CG4_Capture_Start(4 objects)

Signal(Start Capture)
The preview callback is invoked repeatedly
until auto-capture or an the take image
function is invoked.
OnPreviewImageAvailable()

CG4_Main_GetRunningInfo()
The object quality callback is invoked when
the SDK capture criteria are met
OnObjectQuality()
Application manual capture criteria met
Signal(Capture)

CG4_Capture_TakeResultImage()

Signal(Stop Preview)

CG4_Capture_AcquireResultImage()
Signal(Capture)

OnResultImageAvailable()

The image data is returned as a parameter The OnResultImageAvailable function is

of the OnResultImageAvailable() callback ImageData
called when the AcquireResultImage
interface function is invoked

Figure 4-3 Flat Manual Capture Diagram

4.3.2 Using Multiple Scanners

The typical workflow to acquire images is provided below:

1. Call CG4_M_Main_GetConnectedScanner() to retrieve count of connected scanner devices.
2. Call CG4_M_Main_Initialize() to initialize a device for image acquisition.
3. Call CG4_M_Capture_SetRollParameters() to set up the initialization parameters.
4. Call CG4_ M_Capture_Calibration() to calibrate the device.
5. Call the appropriate callback registration functions to retrieve the required notifications.
6. Call CG4_ M_Capture_SetMode() to select the correct acquisition type.
7. Call CG4_ M_Capture_Start() to start image acquisition.

4 - SDK Usage 6
Proprietary
8. Initiate the result image acquisition is triggered automatically (auto capture) and/or
manually by CG4_ M_Capture_TakeResultImage().
9. Call CG4_M_Capture_AcquireResultImage() to acquire the result image. It might take
several seconds, expect a delay.
10. The result image that is passed as ImageData to the callback function
CG4_CallbackResultImage() can be obtained.
11. Repeat steps 2 through 10 to operate the other devices.
12. Call CG4_M_Main_DeInitializeAll() when finished using all of the devices.

Rolled and Flat capture process diagrams are provided below:

Application Capture SDK
Application SDK
Thread Thread

CG4_M_Capture_RegisterCallbackPreviewImage(OnPreviewImageAvailable)

CG4_M_Capture_RegisterCallbackResultImage(OnResultImageAvailable)

CG4_M_Capture_SetMode(CG4_ROLL_SINGLE_FINGER) OnPreviewImageAvailable callback is

invoked after call to SetMode
Signal(Begin Preview)

OnPreviewImageAvailable()
Application gets the running info within the
preview callback. This information applies
to rolled capture only.
CG4_M_Main_GetRunningInfo()
The rolled capture feature is enabled after
CG4_M_Capture_Start(1 object) the start function call

The preview callback is invoked repeatedly

until TakeResultImage() is called Signal(Start Capture)

OnPreviewImageAvailable()
The SDK determines if the rolled capture is
CG4_M_Main_GetRunningInfo()
complete and sets the running info flags
Application checks running info to determine accordingly and stops the capture of new
if a rolled capture is complete images.
Signal(Capture)

CG4_M_Capture_TakeResultImage()

Signal(Stop Preview)

CG4_M_Capture_AcquireResultImage()

Signal(Capture)

OnResultImageAvailable()
The OnResultImageAvailable function is
called when the AcquireResultImage
ImageData function is invoked
The image data is returned as a parameter
of the OnResultImageAvailable() callback
interface

Figure 4-4 Rolled Capture Diagram

4 - SDK Usage 7
Proprietary
 Application Capture SDK
Application SDK
Thread Thread

CG4_M_Capture_RegisterCallbackPreviewImage(OnPreviewImageAvailable)

CG4_M_Capture_RegisterCallbackResultImage(OnResultImageAvailable)

CG4_M_Capture_RegisterCallbackObjectQuality(OnObjectQuality)
OnPreviewImageAvailable callback is
CG4_M_Capture_SetMode(CG4_FLAT_RIGHT_FINGERS, AutoCapture=true) invoked after call to SetMode

Signal(Begin Preview)

OnPreviewImageAvailable()

Application gets the running info within the

preview callback. This information applies
to rolled capture only.

CG4_M_Main_GetRunningInfo()
The auto-capture feature is enabled after
CG4_M_Capture_Start(4 objects) the start function call

Signal(Start Capture)
The preview callback is invoked repeatedly
until auto-capture or an the take image
function is invoked.
OnPreviewImageAvailable()

CG4_M_Main_GetRunningInfo()
The object quality callback is invoked when
the SDK capture criteria are met
OnObjectQuality()
Application manual capture criteria not met.
SDK auto-capture criteria met

Signal(Stop Preview)

Signal(Capture)

OnResultImageAvailable()
The OnResultImageAvailable function is
The image data is returned as a parameter called when the auto-capture criteria are
ImageData
of the OnResultImageAvailable() callback met
interface

Figure 4-5 Flat Auto Capture Diagram)

4 - SDK Usage 8
Proprietary
 Application Capture SDK
Application SDK
Thread Thread

CG4_M_Capture_RegisterCallbackPreviewImage(OnPreviewImageAvailable)

CG4_M_Capture_RegisterCallbackResultImage(OnResultImageAvailable)

CG4_M_Capture_RegisterCallbackObjectQuality(OnObjectQuality)
OnPreviewImageAvailable callback is
CG4_M_Capture_SetMode(CG4_FLAT_RIGHT_FINGERS, AutoCapture=false) invoked after call to SetMode

Signal(Begin Preview)

OnPreviewImageAvailable()

Application gets the running info within the

preview callback. This information applies
to rolled capture only.
CG4_M_Main_GetRunningInfo()
The auto-capture feature is enabled after
the start function call
CG4_M_Capture_Start(4 objects)

Signal(Start Capture)
The preview callback is invoked repeatedly
until auto-capture or an the take image
function is invoked.
OnPreviewImageAvailable()

CG4_M_Main_GetRunningInfo()
The object quality callback is invoked when
the SDK capture criteria are met
OnObjectQuality()
Application manual capture criteria met
Signal(Capture)

CG4_M_Capture_TakeResultImage()

Signal(Stop Preview)

CG4_M_Capture_AcquireResultImage()
Signal(Capture)

OnResultImageAvailable()

The image data is returned as a parameter The OnResultImageAvailable function is

of the OnResultImageAvailable() callback ImageData
called when the AcquireResultImage
interface function is invoked

Figure 4-6 Flat Manual Capture Diagram

5 - Integrating with a Device 9

Proprietary
5 Integrating with a Device
Applications utilize a scanner by using the SDK in the following manner:
Initialize a scanner.
Call API functions (CG4EssentialsApi.h) to the scanner to acquire fingerprints.
Close the scanner.

5.1 Getting Started

Call interface functions in CG4EssentialsApi.h to allow only one device to exist on the same
computer. Before an application can use a scanner, it must perform the following:
1. Call CG4_Main_Initialize() to initialize the device.
2. Call CG4_Capture_SetRollParameters() to set up the initialization parameters.
3. Call CG4_Capture_Calibration() to calibrate the device.
4. Call appropriate callback registration functions to retrieve the required notifications.

The following code provides an example of initializing the device driver:

int nRslt = 0;
CgRollParameters tCG4RollParm;
CG4ScannerType scannerType = CG4_SCANNER_CSD330;

// Initialize CSD330 scanner

nRslt = CG4_Main_Initialize(scannerType);
if (nRslt<CG4_STATUS_OK)
return –1;

// Fill and set initialization values

tCG4RollParm.MaxFrameNumber = 100;
tCG4RollParm.SlideDetectionStatus = 1;
tCG4RollParm.SlidingPixelCounter = 31000;
tCG4RollParm.SlidingPercentageThreshold = 0.302;
tCG4RollParm.SlidingSADMeanThreshlod = 38;
tCG4RollParm.RollBackThreshold = -400;
tCG4RollParm.CheckSensorThreshold = 500;
nRslt = CG4_Capture_SetRollParameters(tCG4RollParm);
if (nRslt<CG4_STATUS_OK)
return –1;

// Calibrate device
nRslt = CG4_Capture_Calibration();
if (nRslt < CG4_STATUS_OK)
return –1;

// Initialize callback functions

CG4_Capture_RegisterCallbackPreviewImage(…);
CG4_Capture_RegisterCallbackTakingResultImage(…);
CG4_Capture_RegisterCallbackResultImage(…);

5 - Integrating with a Device 10

Proprietary
5.2 Acquiring Fingerprints
The scanner communicates with the application using callback functions during the fingerprint
acquisition.

5.2.1 Starting an Acquisition

When an application acquires fingerprints, it specifies the type of fingerprint it requires. Instead
of making the application define capture settings for each fingerprint type, the application can
simply request a particular fingerprint type. Please call CG4_Capture_SetMode to select the
correct acquisition type.

5.2.2 Handling Each Frame

The application can get the current image from the scanner by calling the
CG4_CallbackPreviewImage function. This command passes back a data structure that
describes the image. The application may wish to the display the image; however, the
application must not spend too much time in the callback function because the scanner is
blocked waiting for the application to finish.
Note: The more time spent in the frame-grab callback function means the less of a frame rate
your application achieves. A low frame rate negatively affects the quality of a rolled
fingerprint.

5.2.3 Getting the Final Fingerprint Image

The image received with the CG4_CallbackResultImage function reflects the final fingerprint
image as it is captured. In the case of rolled prints, the image contains the merged fingerprint
ridges. This image is known as the composite image.
Note: The scanner owns the image’s memory buffer. Do not keep pointers to this buffer
because the address of the buffer may change between fingerprint acquisitions.

5.2.4 Putting It All Together

The following code is an example of acquiring a rolled fingerprint:

// NOTE: Error hanlding is kept simple for brevity

// Initialize callback functions

CG4_Capture_RegisterCallbackPreviewImage(
UserPreviewFuc, this);
CG4_Capture_RegisterCallbackTakingResultImage(
UserTakingFuc, this);
CG4_Capture_RegisterCallbackResultImage(
UserResultFuc, this);

//
// select correct acquisition type
//
int SetCurrentAcquistionType()
5 - Integrating with a Device 11
Proprietary
 {
int nRslt = 0;

CG4ImageType m_capTypeApi = CG4_ROLL_SINGLE_FINGER;

CG4ImageResolution m_ImgResolution = CG4_IMAGE_RESOLUTION_500;
BOOL m_bAutoCapture = FALSE;
BOOL m_bAutoContrast = FALSE;
int m_nFullImgWidth=0, m_nFullImgHeight=0;
int m_nBaseRslnX=0, m_nBaseRslnY=0;

nRslt = CG4_Capture_SetMode(
m_capTypeApi,
m_ImgResolution,
m_bAutoCapture,
m_bAutoContrast,
&m_nFullImgWidth,
&m_nFullImgHeight,
&m_nBaseRslnX,
&m_nBaseRslnY);
if (nRslt != CG4_STATUS_OK)
return –1;
}

//
// start image acquisition
//
Int StartImageAcquistion()
{
Int nRslt = 0;

nRslt = CG4_Capture_Start(1);
if (nRslt == CG4_STATUS_OK)
{
nRslt = CG4_Capture_SetStartRollingFlag(TRUE);
}

Return nRslt;
}

//
// Preview image available notification.
//
void UserPreviewFuc(void* pContext, const ImageData image)
{

// Processing flat mode

// …

// Processing roll mode

CG4RunningInfo info;
CG4_Main_GetRunningInfo(&info);
if ( info.bIsCaptureOK && !info.bIsCaptureAbort )
{
nRc = info.nErrorCode;
if (nRc == CG4_STATUS_OK)
{

5 - Integrating with a Device 12

Proprietary
 // The acquisition is done
CG4_Controls_Beeper( 3 );
}
else
{
// The acquisition is failed
CG4_Controls_Beeper( 6 );
}

return;
}

// use image to handle preview image

}

//
// This notification is sent to indicate begin of result image
// acquisition..
//
void UserTakingFuc(void* pContext)
{
// …
}

//
// Result image acquisition completion notification.
//
void UserResultFuc(
void* pContext,
const int imageStatus,
const ImageData image,
const CG4ImageType imageType,
const int detectedOdbjects))
{
// …

if( imageStatus >= CG4_STATUS_OK )

{
// Result image acquisition is done
CG4_Controls_Beeper(3);
// use image to handle result image
// …
}
else
{
// Result image acquisition is failed
}

5 - Integrating with a Device 13

Proprietary
5.3 Closing a Device
An application can close a scanner when it has finished capturing all of the required prints.
Closing a scanner frees all the resources that were allocated by it. The scanner handle is no
longer valid when the scanner it references has been closed. To use the same scanner again,
the application must reopen the scanner. An application closes a scanner by calling the
CG4_Main_DeInitialize function.
Note: If an application closes without closing any open scanners, then the device driver
interface will automatically close all the opened scanners. This happens before the DLL
is unloaded. This behavior holds true if the application loaded and unloaded the scanner
DLL dynamically.

The following code shows an example of closing a scanner:

int nRslt=0;

// Open a scanner

// ...

// Scan all the fingerprints of a person

// ...

// Close the scanner

nRslt = CG4_Main_DeInitialize();

5.4 Accessing Maintenance Data

The scanner places maintenance data in the device’s data store. Applications have access to this
data and can read the data from the device at any time. To read the data, call the function
CG4_Main_GetDeviceInfo. The following code shows an example:

int nRslt=0;
CG4PropertyInfo info;

nRslt = CG4_Main_GetDeviceInfo(&info);

5.5 Control LED

An application can control LED to internal device LEDs by calling the CG4_Controls_SetLEDs.

Function: There are three types of LEDs: finger LEDs, status LEDs, and extend LEDs. Each finger
LED or status LED value consists of one byte. Each extend LED value consists of 4-byte integers.
Extend LEDs are only for the CS500p/CS1000p/CS1000e/CSD330 scanner. Finger LED and
status LED are only for the CS500i/CS500e scanner.

5 - Integrating with a Device 14

Proprietary
Each pair of bits controls one LED for status LEDs:
'00' expresses the yellow light,
'01' expresses the red light,
'10' expresses the green light, and
'11' turns off the LED.

Each bit controls one LED for finger LEDs. Each bit from 0 bit to 4 bit expresses the left fingers
LED, the left thumb LED, the right thumb LED, the right fingers LED, and two thumbs LED. High
3 bits are reserved. '0' turns on the LED, '1' turns off the LED.

For CS500p/CS1000p/CS1000e scanner, Each bit controls one LED for extend LEDs. First bytes
are for right hand, second bytes are for left hand. Each bit from 0 bit to 7 bit expresses the
thumb LED, the index LED, the middle LED, the ring LED, the small LED, the writer’s palm LED,
the lower palm LED, and the upper palm LED. '0' turns on the LED, '1' turns off the LED.

For CSD330 scanner, Each bit controls one LED for extend LEDs. The fourth byte is 0x40 for
default value. For the first bytes, each bit from 0 bit to 7 bit expresses the left thumb red LED,
the left thumb green LED, the left small red LED, the left small green LED, the left ring red LED,
the left ring green LED, the left middle red LED, the left middle green LED, For the second bytes,
each bit from 0 bit to 7 bit expresses the left index red LED, the left index green LED, the right
middle red LED, the right middle green LED, the right ring red LED, the right ring green LED, the
right index red LED, the right index green LED, For the third bytes, each bit from 0 bit to 3 bit
expresses the right small red LED, the right small green LED, the right thumb red LED, the right
thumb green LED, other bits a reserve.
For CSD330 scanner, Perhaps the following define constants will be more clear.

const int CG_CSD330_LIGHT_BASE_VALUE = 0x40000000;

// Right Leds
const int CG_CSD330_RIGHT_THUMB_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x07ffff);
const int CG_CSD330_RIGHT_THUMB_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0bffff);
const int CG_CSD330_RIGHT_INDEX_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0f7fff);
const int CG_CSD330_RIGHT_INDEX_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0fbfff);
const int CG_CSD330_RIGHT_MIDDLE_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0ff7ff);
const int CG_CSD330_RIGHT_MIDDLE_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0ffbff);
const int CG_CSD330_RIGHT_RING_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0fdfff);
const int CG_CSD330_RIGHT_RING_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0fefff);
const int CG_CSD330_RIGHT_SMALL_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0dffff);
const int CG_CSD330_RIGHT_SMALL_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0effff);

// Lift Leds
const int CG_CSD330_LIFT_THUMB_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0ffffd);
const int CG_CSD330_LIFT_THUMB_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0ffffe);
const int CG_CSD330_LIFT_INDEX_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0ffdff);
const int CG_CSD330_LIFT_INDEX_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0ffeff);
const int CG_CSD330_LIFT_MIDDLE_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0fff7f);
const int CG_CSD330_LIFT_MIDDLE_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0fffbf);
5 - Integrating with a Device 15
Proprietary
const int CG_CSD330_LIFT_RING_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0fffdf);
const int CG_CSD330_LIFT_RING_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0fffef);
const int CG_CSD330_LIFT_SMALL_GREEN = (CG_CSD330_LIGHT_BASE_VALUE + 0x0ffff7);
const int CG_CSD330_LIFT_SMALL_RED = (CG_CSD330_LIGHT_BASE_VALUE + 0x0ffffb);

The following code is an example of setting the status LEDs from left to right (e.g., "yellow, red,
green, off"):

int nRslt=0;
int ledValue = 0x1B;

nRslt = CG4_Controls_SetLEDs(CG4_LED_STATUS, ledValue);

The following code is an example of only turning on the right fingers LED, the other fingers
LEDs are turned off.

int nRslt=0;
int ledValue = 0xF7;

nRslt = CG4_Controls_SetLEDs(CG4_LED_FINGER, ledValue);

The following code is an example of only turning on the left writer’s palm LED; the other fingers
LEDs are turned off.

// For CS500p/CS1000p/CS1000e scanner, turning on the left writer's palm

LED, the other fingers LEDs are turned off.
int nRslt=0;
int ledValue = 0xDFFF;
nRslt = CG4_Controls_SetLEDs(CG4_LED_EXTEND, ledValue);

// For CSD330 scanner, turning on the left small red LED, the other finger
LEDs are turned off.
int nRslt=0;
const int CG_CSD330_LIGHT_BASE_VALUE = 0x40000000;
const int CG_CSD330_LIFT_SMALL_RED = (CG_CSD330_LIGHT_BASE_VALUE +
0x0ffffb);
nRslt = CG4_Controls_SetLEDs(CG4_LED_EXTEND, CG_CSD330_LIFT_SMALL_RED);

Note: The SDK controls the LED internally during the capture time, like showing the current
capture finger or the finger status. Rewriting your own LED control code might have conflicting
results.

5.6 Control Beeper

An application can send a beep pattern to an internal device beeper by calling the
CG4_Controls_Beeper function. There are a total of eight patterns in the device beeper (0…7).
The following code provides an example:

int nRslt=0;
int BeepMode = 3;
5 - Integrating with a Device 16
Proprietary
 nRslt = CG4_Controls_Beeper(BeepMode);

5.7 API Functions

This section provides detailed information about the API functions contained in this SDK.

5 - Integrating with a Device 17

Proprietary
5.7.1 CG4_Main_GetConnectedScanner

Function Definition

int WINAPI CG4_Main_GetConnectedScanner (

CG4ScannerExist* scannerExist
);

Description
This function is used to get a connection to a scanner.

Parameters
scannerExist [in/out] This is a connected scanner; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 

1818
Proprietary
5.7.2 CG4_Main_GetAPIVersion

Function Definition

int WINAPI CG4_Main_GetAPIVersion(

CG4ApiVersion* info
);

Description
This function is used to get the DLL version information.

Parameters
info [in/out] This is the DLL version information; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 19

Proprietary
5.7.3 CG4_Main_GetRunningInfo

Function Definition

int WINAPI CG4_Main_GetRunningInfo(

CG4RunningInfo* info
);

Description
This function is used to get the run-time information.

Parameters
info [in/out] This is the device run-time information; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 20

Proprietary
5.7.4 CG4_Main_Initialize

Function Definition

int WINAPI CG4_Main_Initialize(

CG4ScannerType ScannerType=CG4_SCANNER_CS500I
);

Description
This function is used to initialize the scanner.

Parameters
ScannerType [in] This is the scanner type; default value is CG4_SCANNER_CS500I.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 21

Proprietary
5.7.5 CG4_Main_DeInitialize

Function Definition

int WINAPI CG4_Main_DeInitialize();

Description
This function is used to deinitialize the scanner.

Parameters
None

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 22

Proprietary
5.7.6 CG4_Main_FastStartup

Function Definition

int WINAPI CG4_Main_FastStartup(

CG4ScannerType ScannerType=CG4_SCANNER_CS500I
);

Description
This function is used to perform fast startup of the scanner.

Parameters
ScannerType [in] This is the scanner type; default value is CG4_SCANNER_CS500I.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 23

Proprietary
5.7.7 CG4_Main_StandBy

Function Definition

int WINAPI CG4_Main_StandBy();

Description
This function is used to place the scanner in standby mode.

Parameters
None

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 24

Proprietary
5.7.8 CG4_Main_GetDeviceInfo

Function Definition

int WINAPI CG4_Main_GetDeviceInfo(

CG4PropertyInfo* info
);

Description
This function is used to get detailed information about the scanner.

Parameters
info [in/out] This is basic device information; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 25

Proprietary
5.7.9 CG4_Capture_SetMode

Function Definition

int WINAPI CG4_Capture_SetMode(

const CG4ImageType imageType,
const CG4ImageResolution imageResolution,
BOOL AutoCapture,
BOOL AutoContrast,
int* resultWidth,
int* resultHeight,
int* baseResolutionX,
int* baseResolutionY
);

Description
This function is used to set the capture mode of the scanner. This function must be called
prior to calling CG4_Capture_Start().

Parameters
imageType [in] This is the image type to be captured.

imageResolution [in] This is the requested image resolution.

AutoCapture [in] This is a flag for indicating auto capture.

AutoContrast [in] This is a flag for indicating auto contrast.

resultWidth [in/out] This returns the width of the captured result image in pixels.

resultHeight [in/out] This returns the height of the captured result image in pixels.

baseResolutionX [in/out] This returns the horizontal base resolution of the image before
image processing has started.

baseResolutionY [in/out] This returns the vertical base resolution of the image before
image processing has started.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
If the AutoCapture flat is set to true, the SDK will auto-detect the fingers on the glass. If all
the required fingers are acceptable, it will auto-trigger the capture and take the resulting
image.

5 - Integrating with a Device 26

Proprietary
5.7.10 CG4_Capture_Start

Function Definition

int WINAPI CG4_Capture_Start(

const int numberOfObjects
BOOL AutoAcquireResultImage=TRUE
);

Description
This function is used to start the image acquisition.

Parameters
numberOfObjects [in] This is the number of expected fingertips in the image.

AutoAcquireResul [in] This is the Auto acquire result image flag.

tImage

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 27

Proprietary
5.7.11 CG4_Capture_Abort

Function Definition

int WINAPI CG4_Capture_Abort();

Description
This function is used to abort the image acquisition.

Parameters
None

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 28

Proprietary
5.7.12 CG4_Capture_TakeResultImage

Function Definition

CG4_Capture_TakeResultImage();

Description
This function is used to initiate the manual result image acquisition.

Parameters
None

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
After this function call, the finger is not required on glass. Programmers need to call
another function CG4_Capture_AcquireResultImage to get the final result image.

5 - Integrating with a Device 29

Proprietary
5.7.13 CG4_Capture_AcquireResultImage

Function Definition

CG4_Capture_AcquireResultImage();

Description
This function is used to acquire the result image. It might take a little time, up to 1.3
seconds on CS500P scanner. This function should be called immediately after
CG4_Capture_TakeResultImage function call.

Parameters
None

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 30

Proprietary
5.7.14 CG4_Controls_SetStateLEDs

Function Definition

int WINAPI CG4_Controls_SetStateLEDs (

CG4ImageType CapTypeApi,
unsigned char* StateLEDs
);

Description
This function is used to initiate the manual image acquisition.

Parameters
CapTypeApi [in] This is the image type of the active status LED.

StateLEDs [in] This is the state of the active status LED.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
This function is only for CS500i/CS500e/CS500p scanner.

5 - Integrating with a Device 31

Proprietary
5.7.15 CG4_Controls_SetLEDs

Function Definition

int WINAPI CG4_Controls_SetLEDs (

CG4LedType ledType,
int ledValue
);

Description
This function is used to set the active status LEDs on the device.

Parameters
ledType [in] This is the image type of the active status LED.

ledValue [in] This is the value of the status LED.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
Some scanners do not have LED, so this function call might return an error code
“CG4_ERR_NOT_SUPPORTED”. For CS500i/CS500e, ledType can only be “CG4_LED_FINGER”
or “CG4_LED_STATUS”. For CS500p, ledType can only be “CG4_LED_EXTEND”. For other
scanners, this function should not be used.

5 - Integrating with a Device 32

Proprietary
5.7.16 CG4_Controls_Beeper

Function Definition

int WINAPI CG4_Controls_Beeper(

int BeepMode
);

Description
This function is used to send the beep pattern to the internal device beeper.

Parameters
BeepMode [in] This is the beeper mode (0…7).

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 33

Proprietary
5.7.17 CG4_Capture_SetCaptureOK

Function Definition

int WINAPI CG4_Capture_SetCaptureOK();

Description
This function is used to determine whether the captured flag is OK.

Parameters
None

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 34

Proprietary
5.7.18 CG4_Capture_SetStartRollingFlag

Function Definition

int WINAPI CG4_Capture_SetStartRollingFlag(

BOOL flag
);

Description
This function is used to set the start rolling flag.

Parameters
flag [in] This is the flag to start the capture of the rolled prints.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 35

Proprietary
5.7.19 CG4_Capture_GetRollParameters

Function Definition

int WINAPI CG4_Capture_GetRollParameters(

CgRollParameters* para
);

Description
This function is used to get the rolled parameters.

Parameters
para [in] This is the rolled construct parameter; memory provided by
caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 36

Proprietary
5.7.20 CG4_Capture_SetRollParameters

Function Definition

int WINAPI CG4_Capture_SetRollParameters(

CgRollParameters para
);

Description
This function is used to set the rolled parameters.

Parameters
para [in] This is the rolled construct parameter; memory provided by
caller.

Return Values
CG4_STATUS_OK Success
< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 37

Proprietary
5.7.21 CG4_Capture_Calibration

Function Definition

int WINAPI CG4_Capture_Calibration ();

Description
This function is used to calibrate the scanner.

Parameters
None

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 38

Proprietary
5.7.22 CG4_Controls_RegisterFootSwitchInfo

Function Definition

int WINAPI CG4_Controls_RegisterFootSwitchInfo (

HWND hWnd,
UINT Msg
);

Description
This function is used to register the footswitch information.

Parameters
hWnd [in] This is the Windows handler that is used to display the live
image.

msg [in] This is the footswitch message ID.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 39

Proprietary
5.7.23 CG4_Capture_RegisterCallbackPreviewImage

Function Definition

int WINAPI CG4_Capture_RegisterCallbackPreviewImage(

CG4_CallbackPreviewImage callback,
void* context
);

Description
This function is used to register the callback preview image information.

Parameters
callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 40

Proprietary
5.7.24 CG4_Capture_RegisterCallbackTakingResultImage

Function Definition

int WINAPI CG4_Capture_RegisterCallbackTakingResultImage(

CG4_CallbackTakingResultImage callback,
void* context
);

Description
This function is used to register the callback taking result image information.

Parameters
callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 41

Proprietary
5.7.25 CG4_Capture_RegisterCallbackResultImage

Function Definition

int WINAPI CG4_Capture_RegisterCallbackResultImage(

CG4_CallbackResultImage callback,
void* context
);

Description
This function is used to register the callback result image information.

Parameters
callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 42

Proprietary
5.7.26 CG4_Capture_RegisterCallbackFootSwitch

Function Definition

int WINAPI CG4_Capture_RegisterCallbackFootSwitch (

CG4_CallbackFootSwitch callback,
void* context
);

Description
This function is used to register the callback footswitch information.

Parameters
callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 43

Proprietary
5.7.27 CG4_Capture_RegisterCallbackKeypad

Function Definition

int WINAPI CG4_Capture_RegisterCallbackKeypad (

CG4_CallbackKeypad callback,
void *context
);

Description
This function is used to register the callback keypad information.

Parameters
callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 44

Proprietary
5.7.28 CG4_Capture_RegisterCallbackObjectQuality

Function Definition

int WINAPI CG4_Capture_RegisterCallbackObjectQuality (

CG4_CallbackObjectQuality callback,
void* context
);

Description
This function is used to register the callback object quality information.

Parameters
callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 45

Proprietary
5.7.29 CG4_Capture_RegisterCallbackObjectPosition

Function Definition

int WINAPI CG4_Capture_RegisterCallbackObjectPosition (

CG4_CallbackObjectPosition callback,
void* context
);

Description
This function is used to register the callback object position information, which is to mark
the relative positions on preview image.

Parameters
callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 46

Proprietary
5.7.30 CG4_Capture_RegisterCallbackDeviceIsConnected

Function Definition

int WINAPI CG4_Capture_RegisterCallbackDeviceIsConnected (

CG4_CallbackDeviceIsConnected callback,
void* context
);

Description
This function is used to register the callback function to indicate the current equipment
connectivity.

Parameters
callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 47

Proprietary
5.7.31 CG4_CallbackPreviewImage

Function Definition

typedef void ( CALLBACK *CG4_CallbackPreviewImage ) (

void* pContext,
const ImageData image
);

Description
This function is used to preview the image available notification.

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

image [in] This is the preview image (valid until the callback function is
exited).

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 48

Proprietary
5.7.32 CG4_CallbackResultImage

Function Definition

typedef void ( CALLBACK *CG4_CallbackResultImage ) (

void* pContext,
const int imageStatus,
const ImageData image,
const CG4ImageType imageType,
const int detectedObjects
);

Description
This function is used to send a notification that indicates the result of the image acquisition
completion (this is only valid if imageStatus ≥ LSCAN_STATUS_OK).

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

imageStatus [in] This is the result image status value (value ≥

LSCAN_STATUS_OK indicates success).

image [in] This is the preview image (valid until the callback function is
exited).

imageType [in] This is the result image type (e.g.,

LSCAN_ROLL_SINGLE_FINGER).

detectedObjects [in] This is the number of detected objects/fingers in the result

image.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 49

Proprietary
5.7.33 CG4_CallbackFootSwitch

Function Definition

typedef void ( CALLBACK *CG4_CallbackFootSwitch ) (

void* pContext
);

Description
This function is used to send a notification that indicates the message of the trigger
Footswitch.

Parameters
pContext [in] This is a caller defined context (e.g., handler object instance
pointer).

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 50

Proprietary
5.7.34 CG4_CallbackKeypad

Function Definition

typedef void ( CALLBACK * CG4_CallbackKeypad ) (

void* pContext,
const CG4KeypadType keypadType
);

Description
This function is used to send a notification that indicates the message of the trigger
Keypad.

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

CG4KeypadType [in] This is the current key type.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 51

Proprietary
5.7.35 CG4_CallbackObjectQuality

Function Definition

typedef void ( CALLBACK *CG4_CallbackObjectQuality ) (

void* pContext,
const CG4ObjectCountState fingerCountState,
const CG4ObjectQualityState *pQualityArray,
const int qualityCount
);

Description
This function is used to send a notification that indicates fingertip quality change.

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

fingerCountState [in] This is the finger count state (OK, too few, too many).

pQualityArray [in] This is a pointer to an array of finger tip quality states (array size
in quality count).

qualityCount [in] This is the size of finger tip quality array.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 52

Proprietary
5.7.36 CG4_CallbackDeviceIsConnected

Function Definition

typedef void ( CALLBACK * CG4_CallbackDeviceIsConnected ) (

void* pContext,
const BOOL bIsExist
);

Description
This function is used to send a notification that indicates the device connectivity.

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

bIsExist [in] Flag of the equipment is connectivity

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 53

Proprietary
5.7.37 CG4_Capture_GetImageMask

Function Definition

int WINAPI CG4_Capture_GetImageMask(

unsigned char *pImageMask
);

Description
This function is used to get rolling mask image.

Parameters
pImageMask [in/out] This is a rolling mask image; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 54

Proprietary
5.7.38 CG4_Capture_SetAutoCapInfo

Function Definition

int WINAPI CG4_Capture_SetAutoCapInfo (

CG4AutoCapInfo para
);

Description
This function is used to set auto capture information.

Parameters
para [in] This is auto capture information.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 55

Proprietary
5.7.39 CG4_Capture_SetAutoCapArea

Function Definition

int WINAPI CG4_Capture_SetAutoCapArea (

BOOL bAutoCapArea,
int xPos=0, int yPos=0, int width=0, int height=0
);

Description
This function is used to set the active area for auto capture, so that the SDK only detects the
fingers on the defined area. It’s defined as the whole capture area by default.

Parameters
bAutoCapArea [in] auto capture area flag.

xPos [in] x coordinate.

yPos [in] y coordinate.

width [in] the width of the area.

height [in] the height of the area.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

5 - Integrating with a Device 56

Proprietary
5.7.40 CG4_Capture_SetAutoCapFinMask

Function Definition

int WINAPI CG4_Capture_SetAutoCapFinMask (

int nFinMask
);

Description
This function is used to set the finger mask value for auto capture, which is used to control
the finger detection and LED on scanner panel.

Parameters
nFinMask [in] finger mask value.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
The default value of nFinMask is 0 for backward compatibility. When this value is 0, the API
does not use it to control LED and auto capture. In this case, the parameter
numberOfObjects in CG4_Capture_Start or CG4_M_Capture_Start function is used to control
the finger number detection in auto capture.

If the value is not 0, the lower 4 bits of nFinMask are used to control the finger number
detection and the LED from left to right. In this case, the parameter numberOfObjects in
CG4_Capture_Start or CG4_M_Capture_Start function is ignored.

For example:
0x0F means all 4 fingers should exist. If all four fingers are detected in auto capture, all LED
will be lit.
0x05 means the middle finger and little finger on right slap should exist.

5 - Integrating with a Device 57

Proprietary
5.7.41 CG4_Control_CmdSetValue

Function Definition

int WINAPI CG4_Control_CmdSetValue (

DWORD dwCommandMask=0
);

Description
This function is used to enable or disable the feature options.

Parameters
dwCommandMask [in] Option masks

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
This function can be used to enable or disable the Halo Removal feature (software solution).
By default, this feature is disabled.

To enable this feature:

nRet = CG4_Control_CmdSetValue(CG4_CMD_MASK_HALO);

To disable this feature:

nRet = CG4_Control_CmdSetValue(CG4_CMD_MASK);

5 - Integrating with a Device 58

Proprietary
6 Integrating with Multiple Devices
Applications utilize multiple scanner devices by using the SDK in the following manner:
Get the connected scanner devices.
Initialize each scanner device.
Call API functions (CG4EssentialsApiM.h) to the scanner to acquire fingerprints.
Note: You may plug multiple devices into one PC, but it is not recommended to use
multiple scanners to capture fingerprints at the same time because of USB
bandwidth limitations.
Close all the scanner devices.

6.1 Getting Started

Call interface functions in CG4EssentialsApiM.h to allow multiple devices to exist on the same
computer. Before an application can use the scanner devices, it must perform the following:
1. Call CG4_M_Main_GetConnectedScanner to retrieve count of connected devices.
2. Call CG4_M_Main_Initialize() to initialize a device.
3. Call CG4_M_Capture_SetRollParameters() to set up the initialization parameters.
4. Call CG4_M_Capture_Calibration() to calibrate the device.
5. Call appropriate callback registration functions to retrieve the required notifications.
6. Repeat steps 2 through 5 to operate other devices.

The following code provides an example of initializing two devices. First, the CS500e and
CSD330 scanners should be plugged into a PC.

int nRslt = 0;
CG4MScannerExist tScannerExist;
int nHandle500e = -1, nHandle330 = -1;
CgRollParameters tCG4RollParm;

// get connected scanner

nRslt = CG4_M_Main_GetConnectedScanner(&tScannerExist);
if (nRslt<CG4_STATUS_OK)
return –1;

// Initialize CS500e scanner

for (int i=0; i<tScannerExist.nDevConnected; i++)
if (tScannerExist.scannerType[i] == CG4_SCANNER_CS500I)
{
nHandle500e = i;
break;
}

6 - Integrating with Multiple Devices 59

Proprietary
 if (-1 == nHandle500e)
… // some error handling, no 500e scanner detected

nRslt = CG4_M_Main_Initialize(0, &nHandle500e);

if (nRslt<CG4_STATUS_OK)
return –1;

// Fill and set initialization values

tCG4RollParm.MaxFrameNumber = 100;
tCG4RollParm.SlideDetectionStatus = 1;
tCG4RollParm.SlidingPixelCounter = 31000;
tCG4RollParm.SlidingPercentageThreshold = 0.302;
tCG4RollParm.SlidingSADMeanThreshlod = 38;
tCG4RollParm.RollBackThreshold = -400;
tCG4RollParm.CheckSensorThreshold = 500;
nRslt = CG4_M_Capture_SetRollParameters(nHandle500e, tCG4RollParm);
if (nRslt<CG4_STATUS_OK)
return –1;

// Calibrate device
nRslt = CG4_M_Capture_Calibration(nHandle500e);
if (nRslt < CG4_STATUS_OK)
return –1;

// Initialize callback functions

CG4_M_Capture_RegisterCallbackPreviewImage (…);
CG4_M_Capture_RegisterCallbackTakingResultImage(…);
CG4_M_Capture_RegisterCallbackResultImage(…);

// Initialize CSD330 scanner

for (i=0; i<tScannerExist.nDevConnected; i++)
if (tScannerExist.scannerType[i] == CG4_SCANNER_CSD330)
{
nHandle330 = i;
break;
}

if (-1 == nHandle330)
… // some error handling, no CSD330 scanner detected

if (tScannerExist.scannerType[1] != CG4_SCANNER_CSD330)
return –1;
nRslt = CG4_M_Main_Initialize(1, &nHandle330);
if (nRslt<CG4_STATUS_OK)
return –1;

// Fill and set initialization values

tCG4RollParm.MaxFrameNumber = 100;
tCG4RollParm.SlideDetectionStatus = 1;
tCG4RollParm.SlidingPixelCounter = 31000;
tCG4RollParm.SlidingPercentageThreshold = 0.302;
tCG4RollParm.SlidingSADMeanThreshlod = 38;
tCG4RollParm.RollBackThreshold = -400;
tCG4RollParm.CheckSensorThreshold = 500;

6 - Integrating with Multiple Devices 60

Proprietary
 nRslt = CG4_M_Capture_SetRollParameters(nHandle330, tCG4RollParm);
if (nRslt<CG4_STATUS_OK)
return –1;

// Calibrate device
nRslt = CG4_M_Capture_Calibration(nHandle330);
if (nRslt < CG4_STATUS_OK)
return –1;

// Initialize callback functions

CG4_M_Capture_RegisterCallbackPreviewImage (…);
CG4_M_Capture_RegisterCallbackTakingResultImage(…);
CG4_M_Capture_RegisterCallbackResultImage(…);

6.2 Acquiring Fingerprints

The scanner communicates with the application using callback functions during the fingerprint
acquisition.

6.2.1 Starting an Acquisition

When an application acquires fingerprints, it specifies the type of fingerprint it requires. Instead
of making the application define capture settings for each fingerprint type, the application can
simply request a particular fingerprint type. Please call CG4_M_Capture_SetMode to select the
correct acquisition type.

6.2.2 Handling Each Frame

The application can get the current image from the scanner by calling the
CG4_M_CallbackPreviewImage function. This command passes back a data structure that
describes the image. The application may wish to display the image; however, the application
must not spend too much time in the callback function because the scanner is blocked waiting
for the application to finish.
Note: The more time spent in the frame-grab callback function, the lower the frame rate your
application achieves. A low frame rate negatively affects the quality of a rolled
fingerprint.

6.2.3 Getting the Final Fingerprint Image

The image received with the CG4_M_CallbackResultImage function reflects the final fingerprint
image as it is captured. In the case of rolled prints, the image contains the stitched fingerprint
ridges. This image is known as the composite image.
Note: The scanner owns the image’s memory buffer. Do not keep pointers to this buffer
because the address of the buffer may change between fingerprint acquisitions.

6 - Integrating with Multiple Devices 61

Proprietary
6.2.4 Putting It All Together

The following code is an example of acquiring a rolled fingerprint:

// NOTE: Error hanlding is kept simple for brevity

// Initialize callback functions

CG4_M_Capture_RegisterCallbackPreviewImage(
Handle,UserPreviewFuc, this);
CG4_M_Capture_RegisterCallbackTakingResultImage(
Handle, UserTakingFuc, this);
CG4_M_Capture_RegisterCallbackResultImage(
Handle, UserResultFuc, this);

//
// select correct acquisition type
//
int SetCurrentAcquistionType()
{
int nRslt = 0;

CG4ImageType m_capTypeApi = CG4_ROLL_SINGLE_FINGER;

CG4ImageResolution m_ImgResolution = CG4_IMAGE_RESOLUTION_500;
BOOL m_bAutoCapture = FALSE;
BOOL m_bAutoContrast = FALSE;
int m_nFullImgWidth=0, m_nFullImgHeight=0;
int m_nBaseRslnX=0, m_nBaseRslnY=0;

nRslt = CG4_M_Capture_SetMode(
Handle,//Device handle obtained by CG4_M_Main_Initialize()
m_capTypeApi,
m_ImgResolution,
m_bAutoCapture,
m_bAutoContrast,
&m_nFullImgWidth,
&m_nFullImgHeight,
&m_nBaseRslnX,
&m_nBaseRslnY);
if (nRslt != CG4_STATUS_OK)
return –1;
}

//
// start image acquisition
//
Int StartImageAcquistion()
{
Int nRslt = 0;

nRslt = CG4_M_Capture_Start(Handle, 1);

if (nRslt == CG4_STATUS_OK)
{
nRslt = CG4_M_Capture_SetStartRollingFlag(Handle, TRUE);
}

Return nRslt;

6 - Integrating with Multiple Devices 62

Proprietary
 }

//
// Preview image available notification.
//
void UserPreviewFuc(void* pContext, const ImageData image)
{

// Processing flat mode

// …

// Processing roll mode CG4RunningInfo info;

CG4_M_Main_GetRunningInfo(Handle, &info);
if ( info.bIsCaptureOK && !info.bIsCaptureAbort )
{
nRc = info.nErrorCode;
if (nRc == CG4_STATUS_OK)
{
// The acquisition is done
CG4_M_Controls_Beeper(Handle, 3);
}
else
{
// The acquisition is failed
CG4_M_Controls_Beeper(Handle, 6);
}

return;
}

// use image to handle preview image

}

//
// This notification is sent to indicate begin of result image
// acquisition..
//
void UserTakingFuc(void* pContext)
{
// …
}

//
// Result image acquisition completion notification.
//
void UserResultFuc(
void* pContext,
const int imageStatus,
const ImageData image,
const CG4ImageType imageType,
const int detectedOdbjects))
{
// …

if( imageStatus >= CG4_STATUS_OK )

6 - Integrating with Multiple Devices 63

Proprietary
 {
// Result image acquisition is done
CG4_M_Controls_Beeper(Handle, 3);
// use image to handle result image
// …
}
else
{
// Result image acquisition is failed
}

6.3 Closing All Scanner Devices

An application can close all of the scanner devices when it has finished capturing all of the
required prints. Closing devices frees all the resources that were allocated by it. The devices
handle is no longer valid when the devices it references have been closed. To use the same
scanner again, the application must reopen the scanner. An application closes all scanner
devices by calling the CG4_M_Main_DeInitializeAll function.
Note: If an application closes without closing any open scanners, then the device driver
interface will automatically close all the opened scanners. This happens before the DLL
is unloaded. This behavior holds true if the application loaded and unloaded the scanner
DLL dynamically.
The following code shows an example of closing all of the scanner devices:

int nRslt=0;

// Open a scanner

// ...

// Scan all the fingerprints of a person

// ...

// Open a scanner

// ...

// Scan all the fingerprints of a person

// ...

// Close all of the scanner devices

nRslt = CG4_M_Main_DeInitializeAll();

6 - Integrating with Multiple Devices 64

Proprietary
6.4 Accessing Maintenance Data
The scanner places maintenance data in the device’s data store. Applications have access to this
data and can read the data from the device at any time. To read the data, call the function
CG4_M_Main_GetDeviceInfo. The following code shows an example:

int nRslt=0;
CG4PropertyInfo info;

nRslt = CG4_M_Main_GetDeviceInfo(Handle, &info);

6.5 Control LED

An application can control LED to internal device LEDs by calling the CG4_M_Controls_SetLEDs.

Function: There are three types of LEDs: finger LEDs, status LEDs, and extend LEDs. Each finger
LED or status LED value consists of one byte. Each extend LED value consists of 4-byte integers.
Extend LEDs are only for CS500p scanner. Finger LED and status LED are only for
CS500i/CS500e scanner.

Each pair of bits controls one LED for status LEDs.

'00' expresses the yellow light,
'01' expresses the red light,
'10' expresses the green light, and
'11' turns off the LED.

Each bit controls one LED for finger LEDs. Each bit from 0 bit to 4 bit expresses the left fingers
LED, the left thumb LED, the right thumb LED, the right fingers LED, and two thumbs LED. High
3 bits are reserved. '0' turns on the LED, '1' turns off the LED.

Each bit controls one LED for extend LEDs. First bytes are for right hand, second bytes are for
left hand. Each bit from 0 bit to 7 bit expresses the thumb LED, the index LED, the middle LED,
the ring LED, the small LED, the writer’s palm LED, the lower palm LED, and the upper palm
LED. '0' turns on the LED, '1' turns off the LED.

The following code is an example of setting the status LEDs from left to right (e.g., "yellow, red,
green, off"):

int nRslt=0;
int ledValue = 0x1B;

nRslt = CG4_M_Controls_SetLEDs(Handle, CG4_LED_STATUS, ledValue);

The following code is an example of only turning on the right fingers LED, the other fingers
LEDs are turned off.

int nRslt=0;
6 - Integrating with Multiple Devices 65

Proprietary
 int ledValue = 0xF7;

nRslt = CG4_M_Controls_SetLEDs(Handle, CG4_LED_FINGER, ledValue);

The following code is an example of only turning on the left writer’s palm LED; the other fingers
LEDs are turned off.

int nRslt=0;
int ledValue = 0xFFDF;
nRslt = CG4_M_Controls_SetLEDs(Handle, CG4_LED_EXTEND, ledValue);

Note: The SDK controls the LED internally during the capture time, like showing the current
capture finger or the finger status. Rewriting your own LED control code might have
conflicting results.

6.6 Control Beeper

An application can send a beep pattern to an internal device beeper by calling the
CG4_Controls_Beeper function. There are a total of eight patterns in the device beeper (0…7).
The following code provides an example:

int nRslt=0;
int BeepMode = 3;

nRslt = CG4_M_Controls_Beeper(Handle, BeepMode);

6.7 API Functions

This section provides detailed information about the API functions contained in this SDK.

6 - Integrating with Multiple Devices 66

Proprietary
6.7.1 CG4_M_Main_GetConnectedScanner

Function Definition

int WINAPI CG4_M_Main_GetConnectedScanner (

CG4MScannerExist *scannerExist
);

Description
This function is used to get connected scanner devices.

Parameters
scannerExist [in/out] This is connected scanner devices; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 

6767
Proprietary
6.7.2 CG4_M_Main_GetAPIVersion

Function Definition

int WINAPI CG4_M_Main_GetAPIVersion(

CG4ApiVersion* info
);

Description
This function is used to get the DLL version information.

Parameters
info [in/out] This is the DLL version information; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 68

Proprietary
6.7.3 CG4_M_Main_GetRunningInfo

Function Definition

int WINAPI CG4_M_Main_GetRunningInfo(

const int handle,
CG4RunningInfo* info
);

Description
This function is used to get the run-time information.

Parameters
handle [in] This is the device handle obtained by CG4_M_Main_Initialize().

info [in/out] This is the device run-time information; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 69

Proprietary
6.7.4 CG4_M_Main_Initialize

Function Definition

int WINAPI CG4_M_Main_Initialize(

const int deviceIndex,
int *handle
);

Description
This function is used to initialize the scanner.

Parameters
deviceIndex [in] Zero-based device index for device to init.

handle [in/out] This function returns device handle to be used for subsequent
function calls.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 70

Proprietary
6.7.5 CG4_M_Main_DeInitialize

Function Definition

int WINAPI CG4_M_Main_DeInitialize(const int handle);

Description
This function is used to deinitialize the scanner.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 71

Proprietary
6.7.6 CG4_M_Main_DeInitializeAll

Function Definition

int WINAPI CG4_M_Main_DeInitializeAll();

Description
This function is used to deinitialize all currently initialized scanners.

Parameters
None

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 72

Proprietary
6.7.7 CG4_M_Main_IsInitialized

Function Definition

int WINAPI CG4_M_Main_IsInitialized(const int handle);

Description
This function is used to check if device is fully initialized.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 73

Proprietary
6.7.8 CG4_M_Main_GetDeviceInfo

Function Definition

int WINAPI CG4_M_Main_GetDeviceInfo(

const int handle,
CG4PropertyInfo* info
);

Description
This function is used to get detailed information about the scanner.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

info [in/out] This is basic device information; memory provided by caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 74

Proprietary
6.7.9 CG4_M_Capture_SetMode

Function Definition

int WINAPI CG4_M_Capture_SetMode(

const int handle,
const CG4ImageType imageType,
const CG4ImageResolution imageResolution,
BOOL AutoCapture,
BOOL AutoContrast,
int* resultWidth,
int* resultHeight,
int* baseResolutionX,
int* baseResolutionY
);

Description
This function is used to set the capture mode of the scanner. This function must be called
prior to calling CG4_M_Capture_Start ().

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

imageType [in] This is the image type to be captured.

imageResolution [in] This is the requested image resolution.

AutoCapture [in] This is a flag for indicating auto capture.

AutoContrast [in] This is a flag for indicating auto contrast.

resultWidth [in/out] This returns the width of the captured result image in pixels.

resultHeight [in/out] This returns the height of the captured result image in pixels.

baseResolutionX [in/out] This returns the horizontal base resolution of the image before
image processing has started.

baseResolutionY [in/out] This returns the vertical base resolution of the image before
image processing has started.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
If the AutoCapture flag is set to true, the SDK will auto-detect the fingers on glass. If all the
required fingers are good, it will auto-trigger the capture and take the resulting image.

6 - Integrating with Multiple Devices 75

Proprietary
6.7.10 CG4_M_Capture_Start

Function Definition

int WINAPI CG4_M_Capture_Start (

const int handle,
const int numberOfObjects
BOOL AutoAcquireResultImage=TRUE
);

Description
This function is used to start the image acquisition.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

numberOfObjects [in] This is the number of expected fingertips in the image.

AutoAcquireResultI [in] This is the Auto acquire result image flag.

mage

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 76

Proprietary
6.7.11 CG4_M_Capture_Abort

Function Definition

int WINAPI CG4_M_Capture_Abort(const int handle);

Description
This function is used to abort the image acquisition.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 77

Proprietary
6.7.12 CG4_M_Capture_TakeResultImage

Function Definition

CG4_M_Capture_TakeResultImage(const int handle);

Description
This function is used to initiate the manual result image acquisition.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
After this function is called, the finger is not required on the glass. Programmers need to
call another function CG4_M_Capture_AcquireResultImage to get the final result image.

6 - Integrating with Multiple Devices 78

Proprietary
6.7.13 CG4_M_Capture_AcquireResultImage

Function Definition

CG4_M_Capture_AcquireResultImage(const int handle);

Description
This function is used to acquire the result image. It might take a little time, up to 1.3
seconds on CS500P scanner. This function should be called immediately after
CG4_M_Capture_TakeResultImage function call.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 79

Proprietary
6.7.14 CG4_M_Controls_SetStateLEDs

Function Definition

int WINAPI CG4_M_Controls_SetStateLEDs(

const int handle,
CG4ImageType CapTypeApi,
unsigned char* StateLEDs
);

Description
This function is used to set active status LEDs on device.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

CapTypeApi [in] This is the image type of the active status LED.

StateLEDs [in] This is the state of the active status LED.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
This function is only for CS500i/CS500e/CS500p scanner.

6 - Integrating with Multiple Devices 80

Proprietary
6.7.15 CG4_M_Controls_SetLEDs

Function Definition

int WINAPI CG4_M_Controls_SetLEDs (

const int handle,
CG4LedType ledType,
int ledValue
);

Description
This function is used to set the active status LEDs on the device.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

ledType [in] This is the image type of the active status LED.

ledValue [in] This is the value of the status LED.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
Some scanners do not have LEDs, so this function call might return an error code
“CG4_ERR_NOT_SUPPORTED”. For CS500i/CS500e, ledType can only be “CG4_LED_FINGER”
or “CG4_LED_STATUS”. For CS500p, ledType can only be “CG4_LED_EXTEND”. For other
scanners, this function should not be used.

6 - Integrating with Multiple Devices 81

Proprietary
6.7.16 CG4_M_Controls_Beeper

Function Definition

int WINAPI CG4_M_Controls_Beeper(

const int handle,
int BeepMode
);

Description
This function is used to send the beep pattern to the internal device beeper.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

BeepMode [in] This is the beeper mode (0…7).

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 82

Proprietary
6.7.17 CG4_M_Capture_SetCaptureOK

Function Definition

int WINAPI CG4_M_Capture_SetCaptureOK(const int handle);

Description
This function is used to determine whether the captured flag is OK.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 83

Proprietary
6.7.18 CG4_M_Capture_SetStartRollingFlag

Function Definition

int WINAPI CG4_M_Capture_SetStartRollingFlag(

const int handle,
BOOL flag
);

Description
This function is used to set the start rolling flag.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

flag [in] This is the flag to start the capture of the rolled prints.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 84

Proprietary
6.7.19 CG4_M_Capture_GetRollParameters

Function Definition

int WINAPI CG4_M_Capture_GetRollParameters(

const int handle,
CgRollParameters* para
);

Description
This function is used to get the rolled parameters.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

para [in] This is the rolled construct parameter; memory provided by

caller.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 85

Proprietary
6.7.20 CG4_M_Capture_SetRollParameters

Function Definition

int WINAPI CG4_M_Capture_SetRollParameters(

const int handle,
CgRollParameters para
);

Description
This function is used to set the rolled parameters.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

para [in] This is the rolled construct parameter; memory provided by

caller.

Return Values
CG4_STATUS_OK Success
< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 86

Proprietary
6.7.21 CG4_M_Capture_Calibration

Function Definition

int WINAPI CG4_M_Capture_Calibration(const int handle);

Description
This function is used to calibrate the scanner.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 87

Proprietary
6.7.22 CG4_M_Controls_RegisterFootSwitchInfo

Function Definition

int WINAPI CG4_M_Controls_RegisterFootSwitchInfo (

const int handle,
HWND hWnd,
UINT Msg
);

Description
This function is used to register the footswitch information.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

hWnd [in] This is the Windows handler that is used to display the live
image.

msg [in] This is the footswitch message ID.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 88

Proprietary
6.7.23 CG4_M_Capture_RegisterCallbackPreviewImage

Function Definition

int WINAPI CG4_M_Capture_RegisterCallbackPreviewImage(

const int handle,
CG4_CallbackPreviewImage callback,
void* context
);

Description
This function is used to register the callback preview image information.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 89

Proprietary
6.7.24 CG4_M_Capture_RegisterCallbackTakingResultImage

Function Definition

int WINAPI CG4_M_Capture_RegisterCallbackTakingResultImage(

const int handle,
CG4_CallbackTakingResultImage callback,
void* context
);

Description
This function is used to register the callback taking result image information.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 90

Proprietary
6.7.25 CG4_M_Capture_RegisterCallbackResultImage

Function Definition

int WINAPI CG4_M_Capture_RegisterCallbackResultImage(

const int handle,
CG4_CallbackResultImage callback,
void* context
);

Description
This function is used to register the callback result image information.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 91

Proprietary
6.7.26 CG4_M_Capture_RegisterCallbackFootSwitch

Function Definition

int WINAPI CG4_M_Capture_RegisterCallbackFootSwitch(

const int handle,
CG4_CallbackFootSwitch callback,
void* context
);

Description
This function is used to register the callback footswitch information.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 92

Proprietary
6.7.27 CG4_M_Capture_RegisterCallbackKeypad

Function Definition

int WINAPI CG4_M_Capture_RegisterCallbackKeypad(

const int handle,
CG4_CallbackKeypad callback,
void *context
);

Description
This function is used to register the callback keypad information.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 93

Proprietary
6.7.28 CG4_M_Capture_RegisterCallbackObjectQuality

Function Definition

int WINAPI CG4_M_Capture_RegisterCallbackObjectQuality(

const int handle,
CG4_CallbackObjectQuality callback,
void* context
);

Description
This function is used to register the callback object quality information.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 94

Proprietary
6.7.29 CG4_M_Capture_RegisterCallbackObjectPosition

Function Definition

int WINAPI CG4_M_Capture_RegisterCallbackObjectPosition (

const int handle,
CG4_CallbackObjectPosition callback,
void* context
);

Description
This function is used to register the callback object position information, which is to mark
the relative positions on preview image.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 95

Proprietary
6.7.30 CG4_M_Capture_RegisterCallbackDeviceIsConnected

Function Definition

int WINAPI CG4_M_Capture_RegisterCallbackDeviceIsConnected (

const int handle,
CG4_CallbackDeviceIsConnected callback,
void* context
);

Description
This function is used to register the callback function to notify the connectivity for specified
device.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

callback [in] This is the pointer to the notification function.

context [in] This is the pointer to the user context; this value is used as a
parameter for callback.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 96

Proprietary
6.7.31 CG4_CallbackPreviewImage

Function Definition

typedef void ( CALLBACK *CG4_CallbackPreviewImage ) (

void* pContext,
const ImageData image
);

Description
This function is used to preview the image available notification.

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

image [in] This is the preview image (valid until the callback function is
exited).

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 97

Proprietary
6.7.32 CG4_CallbackResultImage

Function Definition

typedef void ( CALLBACK *CG4_CallbackResultImage ) (

void* pContext,
const int imageStatus,
const ImageData image,
const CG4ImageType imageType,
const int detectedObjects
);

Description
This function is used to send a notification that indicates the result of the image acquisition
completion (this is only valid if imageStatus ≥ LSCAN_STATUS_OK).

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

imageStatus [in] This is the result image status value (value ≥

LSCAN_STATUS_OK indicates success).

image [in] This is the preview image (valid until the callback function is
exited).

imageType [in] This is the result image type (e.g.,

LSCAN_ROLL_SINGLE_FINGER).

detectedObjects [in] This is the number of detected objects/fingers in the result

image.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 98

Proprietary
6.7.33 CG4_CallbackFootSwitch

Function Definition

typedef void ( CALLBACK *CG4_CallbackFootSwitch ) (

void* pContext
);

Description
This function is used to send a notification that indicates the message of the trigger
Footswitch.

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 99

Proprietary
6.7.34 CG4_CallbackKeypad

Function Definition

typedef void ( CALLBACK * CG4_CallbackKeypad ) (

void* pContext,
const CG4KeypadType keypadType
);

Description
This function is used to send a notification that indicates the message of the trigger
Keypad.

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

CG4KeypadType [in] This is the current key type.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 100

Proprietary
6.7.35 CG4_CallbackObjectQuality

Function Definition

typedef void ( CALLBACK *CG4_CallbackFootSwitch ) (

void* pContext,
const CG4ObjectCountState fingerCountState,
const CG4ObjectQualityState *pQualityArray,
const int qualityCount
);

Description
This function is used to send a notification that indicates fingertip quality change.

Parameters
pContext [in] This is a caller-defined context (e.g., handler object instance
pointer).

fingerCountState [in] This is the finger count state (OK, too few, too many).

pQualityArray [in] This is a pointer to an array of finger tip quality states (array size
in quality count).

qualityCount [in] This is the size of finger tip quality array.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 101

Proprietary
6.7.36 CG4_M_Capture_GetImageMask

Function Definition

int WINAPI CG4_M_Capture_GetImageMask (

const int handle,
unsigned char *pImageMask
);

Description
Get rolling mask image.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

pImageMask [in/out] Rolling mask image; memory provided by caller!

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 102

Proprietary
6.7.37 CG4_M_Capture_SetAutoCapInfo

Function Definition

int WINAPI CG4_M_Capture_SetAutoCapInfo (

const int handle,
CG4AutoCapInfo para
);

Description
This function sets auto capture information.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

para [in] Auto capture information.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 103

Proprietary
6.7.38 CG4_M_Capture_SetAutoCapArea

Function Definition

int WINAPI CG4_M_Capture_SetAutoCapArea (

const int handle,
BOOL bAutoCapArea,
int xPos=0, int yPos=0, int width=0, int height=0
);

Description
This function is used to set the active area of auto capture. The active area is set to the
whole capture area by default.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

bAutoCapArea [in] auto capture area flag.

xPos [in] x coordinate.

yPos [in] y coordinate.

width [in] the width of the area.

height [in] the height of the area.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
None

6 - Integrating with Multiple Devices 104

Proprietary
6.7.39 CG4_M_Capture_SetAutoCapFinMask

Function Definition

int WINAPI CG4_M_Capture_SetAutoCapFinMask (

const int handle,
int nFinMask
);

Description
This function is used to set the finger mask value for auto capture, which is used to control
the finger detection and LED on scanner panel.

Parameters
handle [in] Device handle obtained by CG4_M_Main_Initialize().

nFinMask [in] finger mask value.

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes
The default value of nFinMask is 0 for backward compatibility. When this value is 0, the API
does not use it to control LED and auto capture. In this case, the parameter
numberOfObjects in CG4_Capture_Start or CG4_M_Capture_Start function is used to
control the finger number detection in auto capture.

If the value is not 0, the lower 4 bits of nFinMask are used to control the finger number
detection and the LED from left to right. In this case, the parameter numberOfObjects in
CG4_Capture_Start or CG4_M_Capture_Start function is ignored.

For example:
0x0F means all 4 fingers should exist. If all four fingers are detected in auto capture, all LED
will be lit.
0x05 means the middle finger and little finger on right slap should exist.

6 - Integrating with Multiple Devices 105

Proprietary
6.7.40 CG4_M_Control_CmdSetValue

Function Definition

int WINAPI CG4_M_Control_CmdSetValue (

const int handle,
DWORD dwCommandMask=0
);

Description
This function is used to enable and disable the options.

Parameters
Handle [in] Device handle obtained by CG4_M_Main_Initialize().

dwCommandMas [in] Option masks.

k

Return Values
CG4_STATUS_OK Success

< CG4_STATUS_OK Error: Please refer to Appendix A for the error code definitions.

Notes

This function can be used to enable or disable the Halo Removal feature (software solution).
By default, this feature is disabled.

To enable this feature:

nRet = CG4_M_Control_CmdSetValue(handle, CG4_CMD_MASK_HALO);

To disable this feature:

nRet = CG4_M_Control_CmdSetValue(handle, CG4_CMD_MASK);

6 - Integrating with Multiple Devices 106

Proprietary
7 Structure Reference
This section provides detailed information about the data types declared by the structs
contained in this SDK.

7.1 CG4ScannerExist
Description
This data structure is used to return the connected scanners.

Members
int nDevConnected This is a count of the number of connected
scanners.

bool bCS500i This is a flag for the CS500i.

bool bCS500e This is a flag for the CS500e.

bool bCSD450 This is a flag for the CSD450.

bool bCSD330 This is a flag for the CSD330.

bool bCSD200 This is a flag for the CSD200.

bool bCS500p This is a flag for the CS500p.

bool bCS1000p This is a flag for the CS1000p.

bool bCSD100 This is a flag for the CSD100.

7.2 CG4ApiVersion
Description
This struct is used to describe the container that is used for holding the version
information.

Members
char Product[CG4_MAX_STR_LEN] This is the product version string.

char SdkVer[CG4_MAX_STR_LEN] This is the SDK version string.

char MosaicVer[CG4_MAX_STR_LEN] This is the ClydeMosaic.dll version string.

7.3 CG4PropertyInfo
Description

7 - Structure Reference 107

Proprietary
 This struct is used to describe the device property information.

Members
int nResolution This is the resolution (500 or 1000 ppi).

char szMaker[CG4_MAX_STR_LEN] This is the device maker.

char szModel[CG4_MAX_STR_LEN] This is the device model type.

char szInterfaceType[CG4_MAX_STR_LEN] This is the device interface type (USB,

FireWire).

char szSerial[CG4_MAX_STR_LEN] This is the device serial number.

char szVer[CG4_MAX_STR_LEN] This is the firmware version of the scanner.

char szManDate[CG4_MAX_STR_LEN] This is the manufacture date.

char szServDate[CG4_MAX_STR_LEN] This is the last service date.

7.4 CG4RunningInfo
Description
This struct is used to describe the device running information.

Members
bool bIsInitialized This is the flag for initialize the device.

bool bIsCapturing This is the flag for capturing.

bool bIsCaptureAbort This is the flag to capture the abort information.

bool bAutoCapture This is the flag for auto capture.

bool bAutoContrast This is the flag for auto contrast.

bool bStartPreview This is the flag for starting the preview.

bool bIsCaptureOK This is the flag for determining if the capture is OK.

bool bIsStartRolling This is the flag to start capture of the rolled prints.

int nErrorCode This is the error code.

7.5 CgRollParameters
Description
This struct is used to describe the rolled construct parameters.

7 - Structure Reference 108

Proprietary
Members
int MaxFrameNumber This is the maximum number of frames used to stitch
an image.

int SlideDetectionStatus If this member is equal to 1, enable the slide

detection function, otherwise disable it.

int SlidingPixelCounter The number of pixels is considered to be sliding

compared to the previous frame. The smaller the
value of the SlidingPixelCounter, the more sensitive
it is to detect sliding and rotation (Good value = 8000,
General value = 25000, Low value = 31000).

float SlidingPercentageThreshold The threshold of the percentage of sliding pixels to

the total pixel number. The smaller the value of the
SlidingPercentageThreshold, the more sensitive it is
to detect sliding and rotation. The
SlidingPercentageThreshold must be within [0.0,
1.0] (Good value = 0.157, General value = 0.202, Low
value = 0.26).

int SlidingSADMeanThreshold This is a measure for judging whether a pixel is

sliding. If the SADMean of a pixel is greater than the
SlidingSADMeanThreshold, it might be sliding (Good
value = 34, General value = 36, Low value = 38).

int RollBackThreshold The greater the value of the RollBackThreshold, the

more sensitive it is to detect roll back
(RollBackThreshold must be < 0).

int CheckSensorThreshold The smaller the value of the CheckSensorThreshold,

the more sensitive it is to detect the sensor (Good
value = 255, General value = 500, Low value = 1000).

7.6 ImageData
Description
This struct is used as a container to hold image data together with meta information.

Members
void* Buffer This is a pointer to the image buffer.

dword Width This is the image’s horizontal size.

dword Height This is the image’s vertical size.

double ResolutionX This is the image’s horizontal resolution (in PPI).

double ResolutionY This is the image’s vertical resolution (in PPI).

double FrameTime This is the image acquisition time (in seconds).

7 - Structure Reference 109

Proprietary
 int Pitch This is the image’s line pitch (in bytes).

byte BitsPerPixel This is the number of bits per pixel.

ImageFormat Format This is the image color format.

bool IsFinal This is used to indicate that the image is finally

processed.

7.7 CG4MScannerExist
Description
This struct is used get connected scanner devices.

Members
int nDevConnected This is the number of connected devices.

int nCS500i This is the number of connected CS500i scanners.

int nCS500e This is the number of connected CS500e scanners.

int nCSD450 This is the number of connected CSD450 scanners.

int nCSD330 This is the number of connected CSD330 scanners.

int nCSD200 This is the number of connected CSD200 scanners.

int nCS500p This is the number of connected CS500p scanners.

int nCS1000p This is the number of connected CS1000p scanners.

int nCSD100 This is the number of connected CSD100 scanners.

CG4Scanner scannerType This is the scanner type, a mapping of array element

Type onto device index.

7.8 CG4AutoCapInfo
Description
This struct is used set auto capture information.

Members
int nLiveRes The resolution of Live image

int nAutoCap_GreyLevel This item control the minimum average grey level for
each fingerprint block (the default value is 230).

double dAutoCap_SquarePecent This item means how many percentage over the whole

7 - Structure Reference 110

Proprietary
 capture screen (the default value is 2.0).

int nAutoCap_Qua This item controls the fingerprint quality (the default
value is 12).

int nAutoCap_NoMoveFrames This item means how many still frames need to be
detected before trigger (the default value is 3).

int nAutoCap_MaxDevCentX This item controls the fingerprint center, X-axis

coordinates (the default value is 10).

int nAutoCap_MaxDevCentY This item controls the fingerprint center, Y-axis

coordinates (the default value is 10).

int nAutoCap_MaxDevGrey This item controls the fingerprint gray level (the
default value is 15).

int nAutoCap_MaxDevSquare This item controls the fingerprint area shift between
two continuous image frames (the default value is
3000).

7 - Structure Reference 111

Proprietary
8 Enumeration Reference
This section provides detailed information about the enumerations contained in this SDK.

8.1 CG4ImageType
Description
This enumeration is used to describe the image types. The enumerations are used as
parameters for CG4_Capture_SetMode.

Enumerators
CG4_ROLL_SINGLE_FINGER This is the rolled fingerprint image.

CG4_FLAT_SINGLE_FINGER This is the single flat finger.

CG4_FLAT_RIGHT_FINGERS These are the right flat fingers.

CG4_FLAT_LEFT_FINGERS These are the left flat fingers.

CG4_FLAT_TWO_THUMBS These are the two flat thumbs.

CG4_FLAT_RIGHT_THUMB This is the right flat thumb.

CG4_FLAT_LEFT_THUMB This is the left flat thumb.

CG4_PALM_RIGHT_FULL This is the full right palm.

CG4_PALM_RIGHT_WRITERS This is the right writer’s palm.

CG4_PALM_RIGHT_LOWER This is the right lower palm.

CG4_PALM_RIGHT_UPPER This is the right upper palm.

CG4_PALM_LEFT_FULL This is the full left palm.

CG4_PALM_LEFT_WRITERS This is the left writer’s palm.

CG4_PALM_LEFT_LOWER This is the left lower palm.

CG4_PALM_LEFT_UPPER This is the left upper palm.

CG4_ROLL_RIGHT_INDEX This is the right index rolled fingerprint image.

CG4_ROLL_RIGHT_MIDDLE This is the right middle rolled fingerprint image.

CG4_ROLL_RIGHT_RING This is the right ring rolled fingerprint image.

CG4_ROLL_RIGHT_SMALL This is the right small rolled fingerprint image.

8 - Enumeration Reference 112

Proprietary
 CG4_ROLL_LEFT_INDEX This is the left index rolled fingerprint image.

CG4_ROLL_LEFT_MIDDLE This is the left middle rolled fingerprint image.

CG4_ROLL_LEFT_RING This is the left ring rolled fingerprint image.

CG4_ROLL_LEFT_SMALL This is the left small rolled fingerprint image.

CG4_FLAT_RIGHT_INDEX This is the right flat index finger.

CG4_FLAT_RIGHT_MIDDLE This is the right flat middle finger.

CG4_FLAT_RIGHT_RING This is the right flat ring finger.

CG4_FLAT_RIGHT_SMALL This is the right flat small finger.

CG4_FLAT_LEFT_INDEX This is the left flat index finger.

CG4_FLAT_LEFT_MIDDLE This is the left flat middle finger.

CG4_FLAT_LEFT_RING This is the left flat ring finger.

CG4_FLAT_LEFT_SMALL This is the left flat small finger.

CG4_TYPE_NONE No image (default after initialization)

8.2 CG4ImageResolution
Description
This enumeration is used to describe the image resolution types. They are used as
parameters for CG4_Capture_SetMode.

Enumerators
CG4_IMAGE_RESOLUTION_500 500 ppi

CG4_IMAGE_RESOLUTION_1000 1000 ppi

8.3 CG4LedType
Description
This enumeration is used to describe the LED field types.

Enumerators
CG4_LED_FINGER These are the LEDs for indicating the finger LEDs.

CG4_LED_STATUS These are the LEDs for indicating the status LEDs.

CG4_LED_EXTEND These are the LEDs for indicating the extend LEDs.

8 - Enumeration Reference 113

Proprietary
 CG4_LED_NONE No LED field available

8.4 CG4ScannerType
Description
This enumeration is used to describe the scanner types.

Enumerators
CG4_SCANNER_CSD330 CSD330 scanner.

CG4_SCANNER_CSD200 CSD200 scanner

CG4_SCANNER_CSD450 CSD450 scanner

CG4_SCANNER_CS500I CS500i scanner

CG4_SCANNER_CS500E CS500e scanner

CG4_SCANNER_CS500P CS500p scanner

8.5 Image Format

Description
This enumeration is used to describe the image format constants.

Enumerators
IMG_FORMAT_GRAY This is the grayscale image.

IMG_FORMAT_RGB24 This is the 24 bit RGB color image.

IMG_FORMAT_RGB32 This is the true color RGB image.

8.6 CG4ObjectQualityState
Description
This enumeration is used to describe the quality state definitions for detected finger/hand.

Enumerators
CG4_OBJECT_NOT_PRESENT Object not detected

CG4_OBJECT_GOOD Object tracking OK

CG4_OBJECT_TOO_LIGHT Object contrast too low

CG4_OBJECT_TOO_DARK Object contrast too dark

CG4_OBJECT_BAD_SHAPE Object shape not OK

8 - Enumeration Reference  114

Proprietary
 CG4_OBJECT_POSITION_NOT_OK Object position not within tracking area

CG4_OBJECT_CORE_NOT_PRESENT Object core not found

CG4_OBJECT_TRACKING_NOT_OK Required tracking time has not been reached yet

8.7 CG4ObjectCountState
Description
This enumeration is used to describe the object/finger count state definitions.

Enumerators
CG4_OBJECT_COUNT_OK Object count is OK

CG4_TOO_MANY_OBJECTS Object count is too many objects

CG4_TOO_FEW_OBJECTS Object count is too few objects

8.8 CG4KeypadType
Description
This enumeration is used to describe the Keypad types.

Enumerators
CG4_KEYPAD_C_KEYS Keypad 'C' button

CG4_KEYPAD_D_KEYS Keypad 'D' button

CG4_KEYPAD_NONE No keypad available

8 - Enumeration Reference 115

Proprietary
Appendix A Code Definitions
This section describes all of the error codes. The following error codes are used in this SDK:
Generic Error Codes
Device Related Error Codes
Mosaic error codes
Command mask macro

A.1 Generic Error Codes

The following table describes the generic error codes.

Name Description

CG4_STATUS_OK The function has completed successfully.

CG4_ERR_INVALID_PARAM_VALUE This is an invalid parameter value.
CG4_ERR_MEM_ALLOC There is insufficient memory.
CG4_ERR_NOT_SUPPORTED Requested functionality is not supported.
CG4_ERR_FILE_OPEN The attempt to open the file has failed.
CG4_ERR_FILE_READ The attempt to read the file has failed.
CG4_ERR_THREAD_RESUME_ERR The attempt to resume the thread has failed.
CG4_ERR_THREAD_CREATE_ERR The attempt to create the thread has failed.
CG4_ERR_EVENT_CREATE_ERR The attempt to create the event has failed.
CG4_ERR_LOG_LEVEL_LOW The log level is low.
CG4_ERR_LOG_DIRECTORY_IS_NO_EXIST The log directory does not exist.
CG4_ERR_DIRECTORY_CREATE The attempt to create the directory has failed.
Figure A-1 Generic Error Codes

A.2 Device Related Error Codes

The following table describes the device related error codes.

Name Description

CG4_ERR_DEVICE_IO Communication with the device has failed.

CG4_ERR_COMMAND_FAILED The command execution has failed.
CG4_ERR_COMMAND_TIMEOUT The command execution has timed out.
CG4_ERR_NO_DEVICE No device has been detected.
CG4_ERR_NO_MATCHING_DEVICE No matching device has been detected.
CG4_ERR_DEVICE_ACTIVE The initialization has failed because it is in use
Appendix A 116
Proprietary
 by another thread/process.
CG4_ERR_NOT_INITIALIZED The device needs to be initialized.
CG4_ERR_IS_INITIALIZED The device is initialized.
CG4_ERR_DEVICE_BUSY Another thread is currently using the device
functions.
CG4_ERR_NO_HARDWARE_SUPPORT There is no hardware support for the
requested function.
CG4_ERR_DEVICE_READ_PARAM The device parameters cannot be read.
CG4_ERR_DEVICE_WRITE_PARAM The attempt to write the parameter to the
device has failed.
CG4_ERR_DEVICE_INVALID_PARAM The parameter read from the device is invalid.
CG4_ERR_DEVICE_INSUFFICIENT_MEMORY There is no memory available for the specified
action (exceeded size).
CG4_ERR_DEVICE_WRONG_OPERATION_MODE The device operation mode is incorrect.
CG4_ERR_IS_CAPTURING The device is the process of capturing prints.
CG4_ERR_DEVICE_NO_SUPPORT The device is not supported.
CG4_ERR_DEVICE_EXCEED_MAX More than 10 devices are connected, which
exceeds the maximum number that the SDK
can support.
CG4_ERR_HANDLE_INVALID Invalid handle for device.
CG4_ERR_HANDLE_NOT_MATCH Input handle and current handle not match.
CG4_ERR_AUTO_CAP_AREA_INFO Input auto capture area information error
CG4_ERR_NOT_CAPTURING Not in capturing mode
Figure A-2 Device Related Error Codes

A.3 Mosaic Error Codes

The following table describes the Mosaic error codes.

Name Description

CG4_ERR_MOSAIC_DirtySensorWindow The sensor window might be dirty,

please clean it before you capture
fingerprints.
CG4_ERR_MOSAIC_TooFast The rolling speed is too fast, press
harder and roll a little more slowly.

CG4_ERR_MOSAIC_TooSlow Your rolling speed is too slow,

please try rolling a little more faster

CG4_ERR_MOSAIC_RollBack Do not roll backwards until you finish

rolling all areas of your finger.
CG4_ERR_MOSAIC_Sliding Do not slide your finger during rolling.
CG4_ERR_MOSAIC_MosaickedImageCenterToo The image center is too low, please place
Low your finger a little higher.
CG4_ERR_MOSAIC_MosaickedImageCenterToo The image center is too high, please
High place your finger a little lower.

CG4_ERR_MOSAIC_MosaickedImageQualityToo The image quality is too low.

Low
CG4_ERR_MOSAIC_DryFinger The finger is too dry. Please press harder
or calibrate the sensor with a lower sensor
brightness and higher contrast.
CG4_ERR_MOSAIC_WetFinger The finger is too wet. Please press softly or
calibrate the sensor with a higher sensor
brightness and higher contrast.
CG4_ERR_MOSAIC_DirtySensorWindow1 If your finger is currently on the sensor,
please remove it from the sensor.
CG4_ERR_MOSAIC_FingerIsLeaving Your finger has left the scanner surface.
CG4_ERR_MOSAIC_TooManyDefectedLines A hardware failure. Need to replace
device.
CG4_ERR_MOSAIC_PalmMoving The hand or finger is moving while
capturing.

CG4_ERR_MOSAIC_MosaickedImageCenterTooLeft The image center is too close to left side,

place your finger in center position

CG4_ERR_MOSAIC_MosaickedImageCenterTooRight The image center is too close to right side,

place your finger in center position

Figure A-3 Mosaic Error Codes

A.4 Command mask macro

Name Description

CG4_CMD_MASK NULL command mask

CG4_CMD_MASK_HALO Remove halo command mask

Appendix A 119
Proprietary