HP Open Source Security for OpenVMS Volume 1: Common Data Security Architecture > Human Recognition Service (HRS) API Functions

HRS_Capture

 » Table of Contents

 » Glossary

 » Index

NAME

CSSM_HRS_Capture, HRS_Capture — Captures samples

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.

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