Package de.gmxhome.conrad.jpos.jpos_base.biometrics

Interface BiometricsInterface

All Superinterfaces:

JposBaseInterface

All Known Implementing Classes:

BiometricsProperties

public interface BiometricsInterface
extends JposBaseInterface

Interface for methods that implement property setter and method calls for the Biometrics device category. For details about properties, methods and method parameters, see UPOS specification, chapter Biometrics. Further details about error handling can be found in introduction - Device Behavior Models - Errors.

Method Summary

Modifier and Type	Method	Description
void	algorithm(int newAlgorithm)	Final part of setting Algorithm.
void	beginEnrollCapture(byte[] referenceBIR, byte[] payload)	Final part of BeginEnrollCapture method.
void	beginVerifyCapture()	Final part of BeginVerifyCapture method.
boolean	checkBIRPurpose(byte[] bir, Boolean verify)	Checks if a BIR is valid for a given purpose.
void	checkFARorFRRLimit(int limit, String name)	Checks whether a FAR or FRR limit is valid.
void	endCapture()	Final part of EndCapture method.
void	identify(int maxFARRequested, int maxFRRRequested, boolean fARPrecedence, byte[][] referenceBIRPopulation, int[][] candidateRanking, int timeout)	Final part of Identify method.
void	identifyMatch(int maxFARRequested, int maxFRRRequested, boolean fARPrecedence, byte[] sampleBIR, byte[][] referenceBIRPopulation, int[][] candidateRanking)	Final part of IdentifyMatch method.
boolean	isDataEmpty(byte[] data, boolean isBIR)	Checks whether a given BIR or payload is empty.
void	processPrematchData(byte[] sampleBIR, byte[] prematchDataBIR, byte[][] processedBIR)	Final part of ProcessPrematchData method.
void	realTimeDataEnabled(boolean newRealTimeDataEnabled)	Final part of setting RealTimeDataEnabled.
void	sensorColor(int newSensorColor)	Final part of setting SensorColor.
void	sensorOrientation(int newSensorOrientation)	Final part of setting SensorOrientation.
void	sensorType(int newSensorType)	Final part of setting SensorType.
void	verify(int maxFARRequested, int maxFRRRequested, boolean fARPrecedence, byte[] referenceBIR, byte[][] adaptedBIR, boolean[] result, int[] fARAchieved, int[] fRRAchieved, byte[][] payload, int timeout)	Final part of Verify method.
void	verifyMatch(int maxFARRequested, int maxFRRRequested, boolean fARPrecedence, byte[] sampleBIR, byte[] referenceBIR, byte[][] adaptedBIR, boolean[] result, int[] fARAchieved, int[] fRRAchieved, byte[][] payload)	Final part of VerifyMatch method.

Methods inherited from interface de.gmxhome.conrad.jpos.jpos_base.JposBaseInterface

asyncMode, autoDisable, checkHealth, claim, clearInput, clearOutput, close, compareFirmwareVersion, dataEventEnabled, deviceEnabled, directIO, directIO, flagWhenIdle, freezeEvents, handlePowerStateOnEnable, newJposOutputRequest, open, powerNotify, release, removeFromPropertySetList, resetStatistics, retrieveStatistics, retryInput, retryOutput, unitDataCount, updateFirmware, updateFirmware, updateStatistics

Method Details

algorithm

void algorithm(int newAlgorithm)
        throws jpos.JposException

Final part of setting Algorithm. Can be overwritten within derived classes, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is claimed,
• Device is not enabled,
• newAlgorithm is between 0 and the number of algorithms specified in AlgorithmList.

Parameters:

newAlgorithm - New value for Algorithm property.

Throws:

jpos.JposException - If an error occurs.

realTimeDataEnabled

void realTimeDataEnabled(boolean newRealTimeDataEnabled)
                  throws jpos.JposException

Final part of setting RealTimeDataEnabled. Can be overwritten within derived classes, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is open,
• CapRealTimeData is true or newRealTimeData is false,
• internal property AllowAlwaysSetProperties is true or newRealTimeDataEnabled equals the previous value of RealTimeDataEnabled.

Parameters:

newRealTimeDataEnabled - New value for RealTimeDataEnabled property.

Throws:

jpos.JposException - If an error occurs.

sensorColor

void sensorColor(int newSensorColor)
          throws jpos.JposException

Final part of setting SensorColor. Can be overwritten within derived classes, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is open,
• newSensorColor is one of SC_MONO, SC_GRAYSCALE, SC_16, SC_256 or SC_FULL,
• the corresponding bit in CapSensorColor is set,
• internal property AllowAlwaysSetProperties is true or newSensorColor equals the previous value of SensorColor.

Parameters:

newSensorColor - New value for SensorColor property.

Throws:

jpos.JposException - If an error occurs.

sensorOrientation

void sensorOrientation(int newSensorOrientation)
                throws jpos.JposException

Final part of setting SensorOrientation. Can be overwritten within derived classes, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is claimed,
• Device is not enabled,
• newSensorOrientation is one of SO_NORMAL, SO_RIGHT, SO_INVERTED or SO_LEFT,
• the corresponding bit in CapSensorOrientation is set.

Parameters:

newSensorOrientation - New value for SensorOrientation property.

Throws:

jpos.JposException - If an error occurs.

sensorType

void sensorType(int newSensorType)
         throws jpos.JposException

Final part of setting SensorType. Can be overwritten within derived classes, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• newSensorType is one of ST_FACIAL_FEATURES, ST_VOICE, ST_FINGERPRINT, ST_IRIS, ST_RETINA, ST_HAND_GEOMETRY, ST_SIGNATURE_DYNAMICS, ST_KEYSTROKE_DYNAMICS, ST_LIP_MOVEMENT, ST_THERMAL_FACE_IMAGE, ST_THERMAL_HAND_IMAGE, ST_GAIT or ST_PASSWORD,
• the corresponding bit in CapSensorType is set.

Parameters:

newSensorType - New value for SensorType property.

Throws:

jpos.JposException - If an error occurs.

beginEnrollCapture

void beginEnrollCapture(byte[] referenceBIR,
 byte[] payload)
                 throws jpos.JposException

Final part of BeginEnrollCapture method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• referenceBIR and payload are not null (null arguments will be passed as byte[0]),
• CapTemplateAdaptation or isEmpty(referenceBIR, true) is true.

Parameters:

referenceBIR - Optional BIR to be adapted (updated).

payload - Data that will be stored by the BSP.

Throws:

jpos.JposException - If an error occurs.

beginVerifyCapture

void beginVerifyCapture()
                 throws jpos.JposException

Final part of BeginVerifyCapture method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled.

Throws:

jpos.JposException - If an error occurs.

endCapture

void endCapture()
         throws jpos.JposException

Final part of EndCapture method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled.

Throws:

jpos.JposException - If an error occurs.

identify

void identify(int maxFARRequested,
 int maxFRRRequested,
 boolean fARPrecedence,
 byte[][] referenceBIRPopulation,
 int[][] candidateRanking,
 int timeout)
       throws jpos.JposException

Final part of Identify method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• maxFARRequested and maxFRRRequested have been checked with checkFARorFRRLimit,
• timeout is positive or FOREVER,
• referenceBIRPopulation has a length > 0,
• each referenceBIR in referenceBIRPopulation is valid (checkBIRPurpose(referenceBIR, null) is true),
• candidateRanking is a valid reference (non-null int[1][]).

Even if FAR and FRR are specified to be percentage values in the UPOS specification, the corresponding values have been specified as probability value in 1/Integer.MAX_VALUE units in the BioAPI.

Parameters:

maxFARRequested - The requested FAR criterion for successful verification.

maxFRRRequested - The requested FRR criterion for successful verification.

fARPrecedence - If both criteria are provided, this parameter indicates which takes precedence.

referenceBIRPopulation - An array of BIRs against which the Identify match is performed.

candidateRanking - Array reference of BIR indices from the referenceBIRPopulation listed in rank order.

timeout - Timeout for successful biometric capture.

Throws:

jpos.JposException - If an error occurs.

identifyMatch

void identifyMatch(int maxFARRequested,
 int maxFRRRequested,
 boolean fARPrecedence,
 byte[] sampleBIR,
 byte[][] referenceBIRPopulation,
 int[][] candidateRanking)
            throws jpos.JposException

Final part of IdentifyMatch method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• maxFARRequested and maxFRRRequested have been checked with checkFARorFRRLimit,
• sampleBIR is not empty (isDataEmpty(sampleBIR, true) is false),
• referenceBIRPopulation has a length > 0,
• each referenceBIR in referenceBIRPopulation is valid (checkBIRPurpose(referenceBIR, null) is true),
• candidateRanking is a valid reference (non-null int[1][]).

Parameters:

maxFARRequested - The requested FAR criterion for successful verification.

maxFRRRequested - The requested FRR criterion for successful verification.

fARPrecedence - If both criteria are provided, this parameter indicates which takes precedence.

sampleBIR - The BIR to be identified.

referenceBIRPopulation - An array of BIRs against which the Identify match is performed.

candidateRanking - Array reference of BIR indices from the referenceBIRPopulation listed in rank order.

Throws:

jpos.JposException - If an error occurs.

processPrematchData

void processPrematchData(byte[] sampleBIR,
 byte[] prematchDataBIR,
 byte[][] processedBIR)
                  throws jpos.JposException

Final part of ProcessPrematchData method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• sampleBIR and prematchDataBIR are not empty (isEmpty(sampleBIR, true) and isEmpty(prematchDataBIR, true) are false),
• processedBIR is a valid reference (non-null byte[1][]),
• CapPrematchData is true.

Parameters:

sampleBIR - BIR to be processed.

prematchDataBIR - BIR containing prematch data.

processedBIR - Reference for the new constructed BIR.

Throws:

jpos.JposException - If an error occurs.

verify

void verify(int maxFARRequested,
 int maxFRRRequested,
 boolean fARPrecedence,
 byte[] referenceBIR,
 byte[][] adaptedBIR,
 boolean[] result,
 int[] fARAchieved,
 int[] fRRAchieved,
 byte[][] payload,
 int timeout)
     throws jpos.JposException

Final part of Verify method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• maxFARRequested and maxFRRRequested have been checked with checkFARorFRRLimit,
• timeout is positive or FOREVER,
• referenceBIR is valid (checkBIRPurpose(referenceBIR, null) is true),
• adaptedBIR is a valid reference (non-null byte[1][]),
• result is a valid reference (non-null boolean[1]),
• fARAchieved and fRRAchieved are a valid references (non-null int[1]),
• payload is a valid reference (non-null byte[1][]),
• adaptedBIR is a valid reference (non-null byte[1][]),
• candidateRanking is a valid reference (non-null int[1][]).

Parameters:

maxFARRequested - The requested FAR criterion for successful verification.

maxFRRRequested - The requested FRR criterion for successful verification.

fARPrecedence - If both criteria are provided, this parameter indicates which takes precedence.

referenceBIR - The BIR to be verified against.

adaptedBIR - Reference of the adapted BIR.

result - Reference of the result.

fARAchieved - Reference to FAR Value indicating the closeness of the match.

fRRAchieved - Reference to FRR Value indicating the closeness of the match.

payload - Reference to optional payload.

timeout - Timeout for successful verification.

Throws:

jpos.JposException - If an error occurs.

verifyMatch

void verifyMatch(int maxFARRequested,
 int maxFRRRequested,
 boolean fARPrecedence,
 byte[] sampleBIR,
 byte[] referenceBIR,
 byte[][] adaptedBIR,
 boolean[] result,
 int[] fARAchieved,
 int[] fRRAchieved,
 byte[][] payload)
          throws jpos.JposException

Final part of VerifyMatch method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• maxFARRequested and maxFRRRequested have been checked with checkFARorFRRLimit,
• timeout is positive or FOREVER,
• sampleBIR is not empty (isDataEmpty(sampleBIR, true) is false),
• referenceBIR is valid (checkBIRPurpose(referenceBIR, null) is true),
• adaptedBIR is a valid reference (non-null byte[1][]),
• result is a valid reference (non-null boolean[1]),
• fARAchieved and fRRAchieved are a valid references (non-null int[1]),
• payload is a valid reference (non-null byte[1][]),
• adaptedBIR is a valid reference (non-null byte[1][]),
• candidateRanking is a valid reference (non-null int[1][]).

Parameters:

maxFARRequested - The requested FAR criterion for successful verification.

maxFRRRequested - The requested FRR criterion for successful verification.

fARPrecedence - If both criteria are provided, this parameter indicates which takes precedence.

sampleBIR - The BIR to be identified.

referenceBIR - The BIR to be verified against.

adaptedBIR - Reference of the adapted BIR.

result - Reference of the result.

fARAchieved - Reference to FAR Value indicating the closeness of the match.

fRRAchieved - Reference to FRR Value indicating the closeness of the match.

payload - Reference to optional payload.

Throws:

jpos.JposException - If an error occurs.

checkFARorFRRLimit

void checkFARorFRRLimit(int limit,
 String name)
                 throws jpos.JposException

Checks whether a FAR or FRR limit is valid. Negative FAR or FRR limits are invalid. Depending on the interpretation of FAR and FRR values as specified in the UPOS specification (percentage values) or as used in the BioAPI reference implementation (probability in units of 1/Integer.MAX_VALUE), it can be necessary to override this method within the implementation class. The default implementation is interpretation as specified in UPOS specification, throwing a JposException if limit is less than zero or greater than 100 (percentage values).

Parameters:

limit - FAR or FRR limit to be checked.

name - limit name (maxFARRequested or maxFRRRequested).

Throws:

jpos.JposException - If limit is out of range, at least if negative.

checkBIRPurpose

boolean checkBIRPurpose(byte[] bir,
 Boolean verify)

Checks if a BIR is valid for a given purpose.

Parameters:

bir - The BIR to be checked.

verify - Must be set to true to check for validity for verification, to false for validity check for identification or to null for validity check for use as reference BIR.

Returns:

true if the BIR is valid for the specified purpose, false otherwise.

isDataEmpty

boolean isDataEmpty(byte[] data,
 boolean isBIR)

Checks whether a given BIR or payload is empty. In the default implementation, empty means the given data is null or all bytes of data are zero. In addition, if isBIR is true, data is also empty if data.length is not greater than the BIR header length (16) or the Length field of the BIR is equal to the header length.

Parameters:

data - The BIR or payload to be checked.

isBIR - True in case of a BIR, false for payload value.

Returns:

true if data is empty, false otherwise.