Edit

Share via

WinBioAsyncMonitorFrameworkChanges function (winbio.h)

  • Article

Starts an asynchronous monitor of changes to the biometric framework. Currently, the only monitored changes that are supported occur when a biometric unit is attached to or detached from the computer.

Syntax

HRESULT WinBioAsyncMonitorFrameworkChanges(
  [in] WINBIO_FRAMEWORK_HANDLE      FrameworkHandle,
  [in] WINBIO_FRAMEWORK_CHANGE_TYPE ChangeTypes
);

Parameters

[in] FrameworkHandle

Handle to the framework session opened by calling WinBioAsyncOpenFramework.

[in] ChangeTypes

A bitmask of type WINBIO_FRAMEWORK_CHANGE_TYPE flags that indicates the types of events that should generate asynchronous notifications. Beginning with Windows 8, the following flag is available:

Value Meaning
WINBIO_FRAMEWORK_CHANGE_UNIT
 A biometric unit has been attached to or detached from the computer.

Return value

The function returns an HRESULT indicating success or failure. Note that success indicates only that the function arguments were valid. Failures encountered during the execution of the operation will be returned asynchronously to a WINBIO_ASYNC_RESULT structure using the notification method specified in WinBioAsyncOpenFramework.

Return code Description
E_HANDLE
 You must set the FrameworkHandle argument.
E_INVALIDARG
 The bitmask contained in the ChangeTypes parameter contains one or more an invalid type bits. Currently, the only available value is WINBIO_FRAMEWORK_CHANGE_UNIT.
WINBIO_E_INCORRECT_SESSION_TYPE
 The FrameworkHandle argument must represent an asynchronous framework session.

Remarks

Once started, this monitor will continue generating events until the client application calls WinBioCancel or WinBioCloseFramework. Creating a monitor for WINBIO_FRAMEWORK_CHANGE_UNIT events will generate two types of asynchronous notifications:

Value Meaning
WINBIO_OPERATION_UNIT_ARRIVAL A biometric unit is attached.
WINBIO_OPERATION_UNIT_REMOVAL A biometric unit is detached.
 

The WinBioAsyncMonitorFrameworkChanges function uses a handle to the framework session opened by calling WinBioAsyncOpenFramework. The framework allocates a WINBIO_ASYNC_RESULT structure and uses it to return information about operation success or failure. If a biometric unit is attached to or detached from the computer, the framework sets the Operation member of the structure. If a problem is encountered during the operation, the framework uses the WINBIO_ASYNC_RESULT structure to return error information. The 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 WinBioAsyncOpenFramework 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.
Notifications are returned in an EnumServiceProviders structure nested inside the WINBIO_ASYNC_RESULT structure. You must call WinBioFree to release the WINBIO_ASYNC_RESULT structure after you have finished using it.

Requirements

Requirement Value
Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Target Platform Windows
Header winbio.h (include Winbio.h)
Library Winbio.lib
DLL Winbio.dll

See also

WinBioAsyncOpenFramework