HRS_Capture

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