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