public interface FingerprintDevice extends Device
FingerprintDevice interface defining the fingerprint APIs for application use.
Obtain a FingerprintDevice instance from POSTerminal using:
FingerprintDevice fingerprintDevice =
(FingerprintDevice) POSTerminal.getInstance().getDevice("com.cloudpos.device.fingerprint");
"com.cloudpos.device.fingerprint" is the identifier for the fingerprint device.
Access requires permission:
<uses-permission android:name="android.permission.CLOUDPOS_FINGERPRINT"/>
Device| Modifier and Type | Field and Description |
|---|---|
static int |
ANSI_FINGERPRINT
ANSI fingerprint
|
static int |
FINGERPRINT
Normal fingerprint
|
static int |
ISO_FINGERPRINT
ISO fingerprint
|
| Modifier and Type | Method and Description |
|---|---|
int |
compare(byte[] arryISObuffer1,
byte[] arryISObuffer2)
Compares two sets of fingerprint minutiae data in ISO 2005 format and returns a dissimilarity score.
|
int |
compareByFormat(byte[] arryBuffer1,
int format1,
byte[] arryBuffer2,
int format2)
Compares two sets of fingerprint minutiae data based on their respective formats.
|
byte[] |
convertFormat(byte[] dataBuffer,
int srcFormat,
int outFormat)
Converts fingerprint data from a specified source format to the ISO IEC 19794-2-2005 format.
|
int |
convertFormat(Fingerprint fingerprintIn,
int typeIn,
Fingerprint fingerprintOut,
int typeOut)
Converts a fingerprint from one specified format to another.
|
int |
delAllFingers()
Deletes all stored fingerprints from the device.
|
int |
delFinger(int userID)
Deletes the fingerprint data associated with a specified user ID.
|
int |
enroll(int userID,
int timeout)
Enrolls a new fingerprint and associates it with a specified user ID.
|
Fingerprint |
getFingerprint(int type)
Retrieves the currently active (scanned) fingerprint in a specified format.
|
Fingerprint |
getFingerprint(int userID,
int type)
Retrieves a fingerprint associated with a given user ID in the specified format.
|
int |
getId()
Retrieves the identification number of a previously scanned fingerprint.
|
int[] |
identify(byte[] targetISObuffer,
java.util.List arryISObuffers,
int candidatesRequested)
Compares a single fingerprint against a list of candidate fingerprints and ranks the matches.
|
int[] |
listAllFingersStatus()
Lists the status of all fingerprints stored in the device.
|
void |
listenForEnroll(OperationListener listener,
int timeout)
Initiates an asynchronous process to enroll a fingerprint.
|
void |
listenForFingerprint(OperationListener listener,
int timeout)
Initiates an asynchronous operation to scan a fingerprint.
|
int |
match(Fingerprint fingerprint1,
Fingerprint fingerprint2)
Compares two fingerprints and returns the percentage of similarity.
|
void |
open(int logicalID)
Opens the fingerprint device with a specified communication mode.
|
int |
storeFeature(int userID,
Fingerprint fingerprint)
Stores a fingerprint and associates it with a specified user ID.
|
int |
verifyAgainstFingerprint(Fingerprint fingerprint,
int timeout)
Verifies the currently active fingerprint against a specified fingerprint within a given timeout period.
|
int |
verifyAgainstUserId(int userID,
int timeout)
Verifies the currently active fingerprint against the fingerprint associated with a specified user ID.
|
int |
verifyAll(int timeout)
Verifies the currently scanned fingerprint against all stored fingerprints in the device.
|
FingerprintOperationResult |
waitForFingerprint(int timeout)
Synchronously scans for a fingerprint within a specified timeout period.
|
cancelRequest, close, getFailCount, getUsageCount, openstatic final int FINGERPRINT
static final int ISO_FINGERPRINT
static final int ANSI_FINGERPRINT
void open(int logicalID) throws DeviceException
This method initializes the device for operations. The logical ID parameter specifies the desired communication mode, tailored to various fingerprint standards.
logicalID - The logical ID to specify the communication mode. It can be one of the following:
FINGERPRINT for normal fingerprint format,
ISO_FINGERPRINT for ISO-compliant fingerprint format, or
ANSI_FINGERPRINT for ANSI-compliant fingerprint format.DeviceException - for standard device-related errors as documented in DeviceException.void listenForFingerprint(OperationListener listener, int timeout) throws DeviceException
This method begins the process of fingerprint scanning in an asynchronous manner.
The handleResult() method
of the provided OperationListener will be invoked upon successful fingerprint capture.
This allows for the application to handle the fingerprint data post-capture.
The captured fingerprint data can be retrieved using the
getFingerprint(int,int) method.
The method includes a timeout parameter, requiring the fingerprint device to support
cancellation of the request. If a timeout occurs, the operation will be aborted, and
the result will indicate an ERR_TIMEOUT error,
without returning any fingerprint data.
This method is suitable for scenarios where fingerprint scanning needs to be managed alongside other application processes or where immediate response to the scanning result is not critical.
listener - The operation listener that will receive and handle the result of the fingerprint scanning.timeout - The maximum allowed time for scanning a fingerprint, in milliseconds.
Exceeding this limit will result in a timeout error.DeviceException - for standard device-related errors as documented in DeviceException.FingerprintOperationResult waitForFingerprint(int timeout) throws DeviceException
This method is the synchronous counterpart of the listenForFingerprint(OperationListener,int) method.
It blocks the calling thread until a fingerprint is scanned or the timeout period is reached.
This method is suitable for scenarios where the application workflow can accommodate a blocking operation
and requires immediate processing of the scanned fingerprint data.
If the method completes successfully within the timeout period, it returns the result of the scanning operation. If the scanning process exceeds the specified timeout, the method returns null, indicating that no fingerprint data was captured within the allotted time.
Use this method when an immediate response to the fingerprint scanning result is critical, and the application can manage the blocking nature of the call.
timeout - The maximum time allowed for the fingerprint scanning operation, in milliseconds.
Exceeding this time will result in a null return value.DeviceException - Standard device-related errors, such as communication failures
or issues with the fingerprint scanner hardware. For standard device-related errors as documented in DeviceException.int match(Fingerprint fingerprint1, Fingerprint fingerprint2) throws DeviceException
This method takes two fingerprint data objects and performs a comparison to determine their level of similarity. The result is expressed as a percentage, indicating how closely the fingerprints match each other. A higher percentage indicates a greater similarity between the two fingerprints.
This method is commonly used in scenarios where verification of an individual's identity is required, such as authentication processes or security checks. The comparison algorithm used by this method is dependent on the underlying implementation of the fingerprint device.
fingerprint1 - The first fingerprint data object to be compared.fingerprint2 - The second fingerprint data object to be compared.DeviceException - for standard device-related errors as documented in DeviceException.void listenForEnroll(OperationListener listener, int timeout) throws DeviceException
This method begins the fingerprint enrollment operation in an asynchronous manner.
It requires user interaction during the process, such as pressing or removing the finger from the scanner as prompted.
The provided OperationListener will be notified through the
handleResult() method upon each interaction and upon successful capture of the fingerprint.
During the enrollment process, various interaction information can be obtained using the
getEnrollInfo(),
getEnrollInfo(), and
getEnrollInfo() methods, depending on the stage of the process.
The final captured fingerprint data can be retrieved using the
getFingerprint(int,int) method.
The method includes a timeout parameter, and the fingerprint device must support cancellation of the request using
cancelRequest(). In case of a timeout, the operation will be aborted,
and the result will indicate a ERR_TIMEOUT error,
without returning any fingerprint data.
listener - The operation listener that will receive and handle the result of each interaction and the final fingerprint capture.timeout - The maximum allowed time for the enrollment process, in milliseconds. Exceeding this limit will result in a timeout error.DeviceException - for standard device-related errors as documented in DeviceException.int enroll(int userID,
int timeout)
throws DeviceException
This method captures and stores a new fingerprint in the device. A user ID is associated with the captured fingerprint for future identification or verification. If the userID is set to -1, the driver automatically generates a unique ID. Valid user IDs range from 1 to 100.
The method returns the ID of the stored fingerprint feature upon successful enrollment. In case of an error during the enrollment process, a negative error code is returned to indicate the type of failure.
Use this method to add new fingerprints to the device for applications that require biometric authentication.
userID - The user ID to associate with the enrolled fingerprint. Set to -1 for automatic generation.timeout - The maximum time allowed for the enrollment process, in milliseconds.DeviceException - for standard device-related errors as documented in DeviceException.int verifyAll(int timeout)
throws DeviceException
This method initiates a verification process for the currently active (scanned) fingerprint. It compares this fingerprint against all fingerprints stored in the device's memory. The method is useful in scenarios where the identity of the fingerprint provider needs to be verified against a set of known fingerprints.
The method returns a positive value if a match is found, indicating a successful verification. In cases where no match is found or an error occurs, a negative value or 0 representing an error code is returned. The specific error codes can vary based on the device's implementation and the nature of the failure.
A timeout parameter is included to limit the duration of the verification process. Exceeding this time limit results in an error, ensuring the operation does not indefinitely block the application.
timeout - The maximum duration allowed for the verification process, in milliseconds.DeviceException - for standard device-related errors as documented in DeviceException.int delAllFingers()
throws DeviceException
This method is used to clear all fingerprint data currently stored in the device's memory. It is typically utilized in scenarios where a reset of the biometric data is required, or when the device is being prepared for a new set of users.
DeviceException - for standard device-related errors as documented in DeviceException.int delFinger(int userID)
throws DeviceException
This method is used to remove a particular user's fingerprint data from the device's memory.
Upon successful deletion, the method returns a positive value. In the event of a failure during the deletion process, a negative value or 0 is returned.
Care should be exercised when using this method, as the deletion of fingerprint data is irreversible.
userID - The user ID associated with the fingerprint to be deleted.DeviceException - for standard device-related errors as documented in DeviceException.int verifyAgainstUserId(int userID,
int timeout)
throws DeviceException
This method compares the currently scanned or active fingerprint on the device with the fingerprint stored and associated with a given user ID. It is typically used in identity verification processes where the goal is to confirm whether the person currently using the device matches a known user based on their fingerprint.
The method returns a positive value if the active fingerprint matches the one associated with the specified user ID, indicating a successful verification. In cases where there is no match or an error occurs, a negative value or 0 representing an error code is returned. The specific error codes can vary based on the device's implementation and the nature of the failure.
A timeout parameter is included to limit the duration of the verification process, ensuring the operation completes within a reasonable timeframe and does not indefinitely block other processes.
userID - The user ID whose associated fingerprint is to be compared with the active fingerprint.timeout - The maximum time allowed for the verification process, in milliseconds.DeviceException - for standard device-related errors as documented in DeviceException.int verifyAgainstFingerprint(Fingerprint fingerprint, int timeout) throws DeviceException
This method is used to compare the fingerprint that is currently active or scanned on the device with a specified fingerprint. It's useful for verification processes where the goal is to determine if the scanned fingerprint matches a known or predefined fingerprint.
The method returns a positive value if the active fingerprint matches the specified fingerprint, indicating a successful verification. In cases where the fingerprints do not match or an error occurs, a negative value or 0 representing an error code is returned. The specific error codes and their meanings can vary based on the device's implementation.
The method includes a timeout parameter to ensure the verification process completes within a reasonable time frame. Exceeding this time limit results in an error, preventing indefinite blocking of operations.
fingerprint - The fingerprint data against which the active fingerprint will be verified.timeout - The maximum duration allowed for the verification process, in milliseconds.DeviceException - for standard device-related errors as documented in DeviceException.int[] listAllFingersStatus()
throws DeviceException
This method provides an overview of the fingerprints currently stored in the device's memory. It returns an array of IDs, each representing a fingerprint that has been successfully stored. These IDs can be used to reference or retrieve specific fingerprints for further processing or verification.
The method is particularly useful in scenarios where an application needs to manage or keep track of multiple fingerprint records, such as in user enrollment systems or security applications.
DeviceException - for standard device-related errors as documented in DeviceException.Fingerprint getFingerprint(int userID, int type) throws DeviceException
This method is used to obtain the fingerprint data of a specific user, formatted according to a chosen standard. The user ID (userID) is used to identify the particular user whose fingerprint data is to be retrieved. The 'type' parameter specifies the format in which the fingerprint data should be returned.
The supported fingerprint formats are: - 0: Default format. - 1: ISO IEC 19794-2-2005 format (ISO2005). - 2: ISO IEC 19794-2-2015 format (ISO2015).
This functionality is commonly used in scenarios where specific user fingerprint data is required, such as for verification or identification purposes, and the format needs to be compatible with certain processing or analysis systems.
userID - The user ID associated with the fingerprint to be retrieved.type - The desired format for the fingerprint data. Use 0 for Default, 1 for ISO2005, and 2 for ISO2015.DeviceException - for standard device-related errors as documented in DeviceException.int storeFeature(int userID,
Fingerprint fingerprint)
throws DeviceException
This method is used to save a new or existing fingerprint in the device's memory. If the userID is set to -1, the system automatically generates a unique identifier for the fingerprint. Otherwise, the provided userID is used to associate the fingerprint with a specific user or entity.
Upon successful storage of the fingerprint, the method returns the ID associated with the stored fingerprint, which can be used for future reference or retrieval. In case of an error during the storage process, a negative value or 0 is returned, representing an error code. The specific error codes can vary based on the device's implementation and the nature of the failure.
This method is typically used in scenarios requiring the registration or update of fingerprint data for users in a biometric system.
userID - The user ID to associate with the stored fingerprint. Set to -1 for automatic generation.fingerprint - The fingerprint data to be stored.DeviceException - for standard device-related errors as documented in DeviceException.Fingerprint getFingerprint(int type) throws DeviceException
This method is used to obtain the active fingerprint data in a particular standardized format. The 'type' parameter allows selection of the format in which the fingerprint data should be retrieved. This functionality is useful for applications that require the fingerprint data to be in a specific format for processing, storage, or compatibility purposes.
Supported fingerprint formats are: - 0: Default format. - 1: ISO IEC 19794-2-2005 format (ISO2005). - 2: ISO IEC 19794-2-2015 format (ISO2015).
The method returns the fingerprint data in the specified format. The returned data is typically used for subsequent processing or analysis steps within the application.
type - The desired format for the fingerprint data. Use 0 for Default, 1 for ISO2005, and 2 for ISO2015.DeviceException - for standard device-related errors as documented in DeviceException.int convertFormat(Fingerprint fingerprintIn, int typeIn, Fingerprint fingerprintOut, int typeOut) throws DeviceException
This method is used to transform the format of a given fingerprint (`fingerprintIn`) from its current type (`typeIn`) to a different specified type (`typeOut`). This functionality is crucial for interoperability between different fingerprint systems or standards, allowing fingerprints to be processed or recognized in various formats.
The method supports conversion between the following formats: - 0: Default format. - 1: ISO IEC 19794-2-2005 format (ISO2005). - 2: ISO IEC 19794-2-2015 format (ISO2015).
Upon successful conversion, the method returns a positive value, and the converted fingerprint data is stored in `fingerprintOut`. If the conversion fails, a negative error code or 0 is returned, indicating the type of error encountered.
fingerprintIn - The fingerprint data to be converted.typeIn - The current format of the fingerprint to be converted.
Use 0 for Default, 1 for ISO2005, and 2 for ISO2015.fingerprintOut - The variable where the converted fingerprint data will be stored.typeOut - The desired format for the converted fingerprint.
Use 0 for Default, 1 for ISO2005, and 2 for ISO2015.DeviceException - for standard device-related errors as documented in DeviceException.int getId() throws DeviceException
DeviceException - for standard device-related errors as documented in DeviceException.int compare(byte[] arryISObuffer1,
byte[] arryISObuffer2)
throws android.os.RemoteException,
DeviceException
This method performs a detailed comparison between two sets of fingerprint data, both of which should be formatted according to the ISO IEC 19794-2-2005 standard for fingerprint minutiae. The comparison assesses the differences between the two fingerprint data sets and quantifies these differences in the form of a dissimilarity score.
A lower dissimilarity score indicates a higher level of similarity between the two fingerprints, while a higher score suggests greater differences. This method is commonly used in fingerprint verification systems where precise comparison is essential.
arryISObuffer1 - The byte buffer containing the first set of fingerprint minutiae data in ISO 2005 format.arryISObuffer2 - The byte buffer containing the second set of fingerprint minutiae data in ISO 2005 format.DeviceException - for standard device-related errors as documented in DeviceException.android.os.RemoteExceptionint[] identify(byte[] targetISObuffer,
java.util.List arryISObuffers,
int candidatesRequested)
throws android.os.RemoteException,
DeviceException
This method evaluates a target fingerprint against a list of candidate fingerprints (up to 16) and identifies potential matches based on similarity scores. Each candidate fingerprint is compared to the target, and those with similarity scores below a predefined threshold are marked as potential matches.
After comparing all candidates, the method ranks them according to their similarity scores, with lower scores indicating higher similarity. It then returns the indices of the top matching candidates as specified by the 'candidatesRequested' parameter.
This functionality is particularly useful in identification scenarios where a fingerprint needs to be matched against a database of known prints to determine the closest matches.
targetISObuffer - The ISO-formatted byte buffer of the target fingerprint to be compared.listISObuffer - A list of ISO-formatted byte buffers of candidate fingerprints for comparison.candidatesRequested - The number of top matching candidates to return from the comparison.DeviceException - for standard device-related errors as documented in DeviceException.android.os.RemoteExceptionbyte[] convertFormat(byte[] dataBuffer,
int srcFormat,
int outFormat)
throws android.os.RemoteException,
DeviceException
This method is used to standardize fingerprint data into the ISO 2005 format, which is a widely recognized specification for fingerprint minutiae data. It takes a fingerprint data buffer in either the ISO 19794-2-2005 format or the ANSI INSITS 378-2004 format and converts it to the ISO 2005 format.
The source format is specified using the srcFormat parameter. This method facilitates interoperability between different fingerprint systems and ensures compliance with the ISO standard.
dataBuffer - The byte buffer containing the fingerprint data to be converted.srcFormat - The format of the input data. Use 0 for ISO IEC 19794-2-2005, 1 for ANSI INSITS 378-2004.outFormat - The output format, which is always set to the ISO 2005 format in this method.DeviceException - for standard device-related errors as documented in DeviceException.android.os.RemoteExceptionint compareByFormat(byte[] arryBuffer1,
int format1,
byte[] arryBuffer2,
int format2)
throws android.os.RemoteException,
DeviceException
This method performs a comparison between two fingerprint data sets, taking into account the specified formats of each set. The comparison evaluates the dissimilarities between the two sets of data, providing a score that quantifies their differences.
The method supports two formats: - 0: ISO IEC 19794-2-2005 Fingerprint Minutiae Data format. - 1: ANSI INSITS 378-2004 Fingerprint Minutiae Data format.
This functionality is useful in scenarios where fingerprints need to be compared across different format standards, ensuring compatibility and accurate matching.
arryBuffer1 - Byte buffer containing the first set of fingerprint minutiae data.format1 - Format of the first fingerprint data (0 for ISO, 1 for ANSI).arryBuffer2 - Byte buffer containing the second set of fingerprint minutiae data.format2 - Format of the second fingerprint data (0 for ISO, 1 for ANSI).DeviceException - for standard device-related errors as documented in DeviceException.android.os.RemoteException