NAME
CSSM_HRS_Identify, HRS_Identify
SYNOPSIS
#include <hrs.h>
API
CSSM_RETURN CSSMAPI CSSM_HRS_Identify(
CSSM_HRS_HANDLE ModuleHandle,
const CSSM_HRS_FAR *MaxFARRequested,
const CSSM_HRS_FRR *MaxFRRRequested,
const CSSM_BOOL *FARPrecedence,
const CSSM_HRS_IDENTIFY_POPULATION *Population,
CSSM_BOOL Binning,
uint32 MaxNumberOfResults,
uint32 *NumberOfResults,
CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates,
sint32 Timeout,
CSSM_HRS_BIR_HANDLE_PTR AuditData);
SPI
CSSM_RETURN CSSMHRI HRS_Identify(
CSSM_HRS_HANDLE ModuleHandle,
const CSSM_HRS_FAR *MaxFARRequested,
const CSSM_HRS_FRR *MaxFRRRequested,
const CSSM_BOOL *FARPrecedence,
const CSSM_HRS_IDENTIFY_POPULATION *Population,
CSSM_BOOL Binning,
uint32 MaxNumberOfResults,
uint32 *NumberOfResults,
CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates,
sint32 Timeout,
CSSM_HRS_BIR_HANDLE_PTR AuditData);
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 identification.
MaxFRRRequested (input/optional) The requested FRR criterion for
successful identification. 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.
Population (input) The population of Templates against
which the Identify match is
performed.
Binning (input) A Boolean value indicating whether
Binning is on or off. Binning is a
search optimization technique that
the BSP 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 results. This value
can be any positive number. A -1
value means the service provider's
default timeout value will be used.
AuditData (output/optional) A handle to a BIR containing raw
biometric data. This data may be
used to provide human-identifiable
data of the person at the device.
If the pointer is NULL on input, no
audit data is collected. Not all
HRS service providers support the
collection of audit data. A BSP may
return a handle value of
CSSM_HRS_UNSUPPORTED_BIR_HANDLE to
indicate AuditData is not supported,
or a value of
CSSM_HRS_INVALID_BIR_HANDLE to
indicate that no audit data is
available.
DESCRIPTION
This function captures biometric data from the attached device,
and compares it against the Population. 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 function returns a number of candidates from the population
that match according to the specified criteria, and the
FARAchieved and, optionally, the FRRAchieved are returned for
each result in the Candidate array.
The Identify function may be split between client and server if
a streaming callback has been set. Either the client or the
server can initiate the operation.
NOTES
Not all service providers support 1:N identification. See your
service provider's programming manual for more details.
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. Check your service
provider's manual for recommended Timeout values.
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_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
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_UNABLE_TO_CAPTURE