NAME
   CSSM_HRS_Capture, HRS_Capture

 SYNOPSIS

 #include <hrs.h>

 API
   CSSM_RETURN CSSMAPI CSSM_HRS_Capture(
                                  CSSM_HRS_HANDLE ModuleHandle,
                                  CSSM_HRS_BIR_PURPOSE Purpose,
                                  CSSM_HRS_BIR_HANDLE_PTR CapturedBIR,
                                  sint32 Timeout,
                                  CSSM_HRS_BIR_HANDLE_PTR AuditData);
 SPI
   CSSM_RETURN CSSMHRI HRS_Capture(
                                  CSSM_HRS_HANDLE ModuleHandle,
                                  CSSM_HRS_BIR_PURPOSE Purpose,
                                  CSSM_HRS_BIR_HANDLE_PTR CapturedBIR,
                                  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.
   Purpose (input)                 A value indicating the purpose
                                   of the biometric data capture.
   CapturedBIR (output)            A handle to a BIR containing
                                   captured data. This data is either an
                                   "intermediate" type BIR (which can only
                                   be used by either the Process or
                                   CreateTemplate functions, depending on
                                   the purpose), or a "processed" BIR
                                   (which can be used directly by
                                   VerifyMatch or IdentifyMatch,
                                   depending on the purpose).
   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
                                   BSPs support the collection of audit
                                   data. A service provider may return
                                   a handle value of
                                   CSSM_HRS_UNSUPPORTED_BIR_HANDLE
                                   indicating not supported, or a value
                                   of CSSM_HRS_INVALID_BIR_HANDLE
                                   indicating no audit data is available.

 DESCRIPTION
   This function captures samples for the purpose specified, and returns
   either an "intermediate" type BIR (if the Process function needs to
   be called), or a "processed" BIR (if not). The Purpose is recorded
   in the header of the CapturedBIR. If AuditData is non-NULL, a BIR
   of type "raw" may be returned. The function returns handles to
   whatever data is collected, and all local operations can be
   completed through use of the handles.

   If the application needs to acquire the data either to store it in
   a database or to send it to a server, the application can retrieve
   the data with the HRS_GetBIRFromHandle() function.

   The application may request control of the GUI "look-and-feel" by
   providing a GUI callback pointer in HRS_SetGUICallbacks().

   Capture serializes use of the device. If two or more applications
   are racing for the device, the losers will wait until the timeout
   expires. This serialization takes place in all functions that
   capture data.

 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_PURPOSE_NOT_SUPPORTED
   CSSMERR_HRS_TIMEOUT_EXPIRED
   CSSMERR_HRS_TOO_MANY_HANDLES
   CSSMERR_HRS_UNABLE_TO_CAPTURE