HELPLIB.HLB  —  CDSA  CDSA_API, HRS Identify
 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
Close Help