NAME
CSSM_HRS_IdentifyMatch, HRS_IdentifyMatch
SYNOPSIS
#include <hrs.h>
API
CSSM_RETURN CSSMAPI CSSM_HRS_IdentifyMatch(
CSSM_HRS_HANDLE ModuleHandle,
const CSSM_HRS_FAR *MaxFARRequested,
const CSSM_HRS_FRR *MaxFRRRequested,
const CSSM_BOOL *FARPrecedence,
const CSSM_HRS_INPUT_BIR *ProcessedBIR,
const CSSM_HRS_IDENTIFY_POPULATION *Population,
CSSM_BOOL Binning,
uint32 MaxNumberOfResults,
uint32 *NumberOfResults,
CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates,
sint32 Timeout);
SPI
CSSM_RETURN CSSMHRI HRS_IdentifyMatch(
CSSM_HRS_HANDLE ModuleHandle,
const CSSM_HRS_FAR *MaxFARRequested,
const CSSM_HRS_FRR *MaxFRRRequested,
const CSSM_BOOL *FARPrecedence,
const CSSM_HRS_INPUT_BIR *ProcessedBIR,
const CSSM_HRS_IDENTIFY_POPULATION *Population,
CSSM_BOOL Binning,
uint32 MaxNumberOfResults,
uint32 *NumberOfResults,
CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates,
sint32 Timeout);
LIBRARY
HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE)
PARAMETERS
The parameter definitions are the same for the API and the SPI.
ModuleHandle (input) The handle of the attached HRS
service provider.
MaxFARRequested (input) The requested FAR criterion for
successful verification.
MaxFRRRequested (input/optional) The requested FRR criterion for
successful verification. A NULL
pointer indicates that this
criterion is not provided.
FARPrecedence (input) If both criteria are provided,
this parameter indicates which
takes precedence: CSSM_TRUE for
FAR, CSSM_FALSE for FRR.
ProcessedBIR (input) The BIR to be identified.
Population (input) The population of BIRs against
which the Identify match is performed.
Binning (input) A Boolean indicating whether
Binning is on or off. Binning is a
search-optimization technique that
the service provider may employ. It
is based on searching the population
according to the intrinsic
characteristics of the biometric
data. While it may improve the speed
of the Match operation, it may also
increase the probability of missing
a candidate.
MaxNumberOfResults (input) Specifies the maximum number of match
candidates to be returned as a
result of the 1:N match. A value of
zero is a request for all candidates.
NumberOfResults (output) Specifies the number of candidates
returned in the Candidates array as
a result of the 1:N match.
Candidates (output) A pointer to an array of
CSSM_HRS_CANDIDATE_PTRs
corresponding to the BIRs identified
as a result of the match process
(that is, indices associated with
BIRs found to exceed the match
threshold). This list is in rank
order, with the highest scoring
record being first. If no matches
are found, this pointer will be set
to NULL. If the Population was
presented in a database, the IDs are
database IDs; if the set was
presented in an in-memory array, the
IDs are indexes into the array.
Timeout (input) An integer specifying the timeout
value (in milliseconds) for the
operation. If this timeout is
reached, the function returns an
error, and no candidate list. This
value can be any positive number.
A -1 value means the service
provider's default timeout value
will be used.
DESCRIPTION
This function performs an identification (1-to-many) match between
a ProcessedBIR and a set of stored BIRs. The ProcessedBIR is the
"processed" BIR captured specifically for this identification.
The population that the match takes place against can be presented
in one of three ways:
1. In a database identified by an open database handle
2. Input in an array of BIRs
3. In the "default" database of the BSP (possibly stored
in the biometric device)
The application must request a maximum FAR value criterion for
a successful match, and may also (optionally) request a maximum
FRR criterion for a successful match. If a maximum FRR value is
provided, the application must also indicate, via the FARPrecedence
parameter, which criteria takes precedence. The FARAchieved and,
optionally, the FRRAchieved are returned for each result in the
Candidate array.
NOTES
Not all service providers support 1:N identification.
Depending on the service provider and the location and size of the
database to be searched, this operation can take a significant
amount of time to perform
The number of match candidates found by the service provider is
dependent on the actual FAR used.
RETURN VALUE
A CSSM_RETURN value indicating success or specifying a particular
error condition. The value CSSM_OK indicates success. All other
values represent an error condition.
ERRORS
Errors are described in the CDSA Technical Standard. See CDSA.
CSSMERR_CSSM_NOT_INITIALIZED
CSSMERR_CSSM_FUNCTION_FAILED
CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED
CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL
CSSMERR_HRS_BIR_NOT_FULLY_PROCESSED
CSSMERR_HRS_BIR_SIGNATURE_FAILURE
CSSMERR_HRS_FUNCTION_NOT_SUPPORTED
CSSMERR_HRS_INCONSISTENT_PURPOSE
CSSMERR_HRS_NO_INPUT_BIRS
CSSMERR_HRS_RECORD_NOT_FOUND
CSSMERR_HRS_TIMEOUT_EXPIRED