WinBioGetProperty function

Retrieves a session, unit, or template property.

Syntax


HRESULT WINAPI WinBioGetProperty(
  _In_       WINBIO_SESSION_HANDLE SessionHandle,
  _In_       WINBIO_PROPERTY_TYPE PropertyType,
  _In_       WINBIO_PROPERTY_ID PropertyId,
  _In_opt_   WINBIO_UNIT_ID UnitId,
  _In_opt_   WINBIO_IDENTITY *Identity,
  _In_opt_   WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  _Outptr_result_bytebuffer_maybenull_(*PropertyBufferSize)PVOID *PropertyBuffer,
  _Out_opt_  SIZE_T *PropertyBufferSize
);

Parameters

SessionHandle [in]

A WINBIO_SESSION_HANDLE value that identifies an open biometric session. Open a synchronous session handle by calling WinBioOpenSession. Open an asynchronous session handle by calling WinBioAsyncOpenSession.

PropertyType [in]

A WINBIO_PROPERTY_TYPE value that specifies the source of the property information. Currently this must be WINBIO_PROPERTY_TYPE_UNIT.

PropertyId [in]

A WINBIO_PROPERTY_ID value that specifies the property to be queried. Currently this must be WINBIO_PROPERTY_SAMPLE_HINT.

UnitId [in, optional]

A WINBIO_UNIT_ID value that identifies the biometric unit. This value cannot be zero. You can find a unit ID by calling the WinBioEnumBiometricUnits or WinBioLocateSensor functions.

Identity [in, optional]

Reserved. This must be NULL.

SubFactor [in, optional]

Reserved. This must be WINBIO_SUBTYPE_NO_INFORMATION.

PropertyBuffer

Address of a pointer to a buffer that receives the property value.

PropertyBufferSize [out, optional]

Pointer to a variable that receives the size, in bytes, of the buffer pointed to by the PropertyBuffer parameter.

Return value

If the function succeeds, it returns S_OK. If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

Return codeDescription
E_HANDLE

The session handle specified by the SessionHandle parameter is not valid.

E_POINTER

The Identity, PropertyBuffer, or PropertyBufferSize arguments cannot be NULL.

E_INVALIDARG

The UnitId, Identity, or SubFactor arguments are incorrect.

WINBIO_E_INVALID_PROPERTY_TYPE

The value of the PropertyType argument is incorrect.

WINBIO_E_INVALID_PROPERTY_ID

The value of the PropertyId argument is incorrect.

WINBIO_E_LOCK_VIOLATION

The caller attempted to query a property that resides inside of a locked region.

WINBIO_E_UNSUPPORTED_PROPERTY

The object being queried does not support the specified property.

WINBIO_E_ENROLLMENT_IN_PROGRESS

The operation could not be completed because the specified biometric unit is currently being used for an enrollment transaction (system pool only).

 

Remarks

To use WinBioGetProperty synchronously, call the function with a session handle created by calling WinBioOpenSession. The function blocks until the operation completes or an error is encountered. To prevent memory leaks, you must call WinBioFree to release the memory pointed to by the PropertyBuffer parameter when you are finished using the data contained in the buffer.

To use WinBioGetProperty asynchronously, call the function with a session handle created by calling WinBioAsyncOpenSession. The framework allocates a WINBIO_ASYNC_RESULT structure and uses it to return information about operation success or failure. If the operation is successful, the framework returns information in a nested GetProperty structure.The WINBIO_ASYNC_RESULT structure is returned to the application callback or to the application message queue, depending on the value you set in the NotificationMethod parameter of the WinBioAsyncOpenSession function:

  • If you choose to receive completion notices by using a callback, you must implement a PWINBIO_ASYNC_COMPLETION_CALLBACK function and set the NotificationMethod parameter to WINBIO_ASYNC_NOTIFY_CALLBACK.
  • If you choose to receive completion notices by using the application message queue, you must set the NotificationMethod parameter to WINBIO_ASYNC_NOTIFY_MESSAGE. The framework returns a WINBIO_ASYNC_RESULT pointer to the LPARAM field of the window message.

To prevent memory leaks, you must call WinBioFree to release the WINBIO_ASYNC_RESULT structure after you have finished using it.

Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winbio.h (include Winbio.h)

Library

Winbio.lib

DLL

Winbio.dll

See also

WinBioFree

 

 

Community Additions

ADD
Show:
© 2014 Microsoft