WinBioAsyncOpenSession function (winbio.h)
Asynchronously connects to a biometric service provider and one or more biometric units. Starting with Windows 10, build 1607, this function is available to use with a mobile image. If successful, the function returns a biometric session handle. Every operation performed by using this handle will be completed asynchronously, including WinBioCloseSession, and the results will be returned to the client application by using the method specified in the NotificationMethod parameter.
For a synchronous version of this function, see WinBioOpenSession.
Syntax
HRESULT WinBioAsyncOpenSession(
[in] WINBIO_BIOMETRIC_TYPE Factor,
[in] WINBIO_POOL_TYPE PoolType,
[in] WINBIO_SESSION_FLAGS Flags,
[in, optional] WINBIO_UNIT_ID *UnitArray,
[in, optional] SIZE_T UnitCount,
[in, optional] GUID *DatabaseId,
[in] WINBIO_ASYNC_NOTIFICATION_METHOD NotificationMethod,
[in, optional] HWND TargetWindow,
[in, optional] UINT MessageCode,
[in, optional] PWINBIO_ASYNC_COMPLETION_CALLBACK CallbackRoutine,
[in, optional] PVOID UserData,
[in] BOOL AsynchronousOpen,
[out, optional] WINBIO_SESSION_HANDLE *SessionHandle
);
Parameters
[in] Factor
A bitmask of WINBIO_BIOMETRIC_TYPE flags that specifies the biometric unit types to be enumerated. Only WINBIO_TYPE_FINGERPRINT is currently supported.
[in] PoolType
A ULONG value that specifies the type of the biometric units that will be used in the session. This can be one of the following values:
[in] Flags
A ULONG value that specifies biometric unit configuration and access characteristics for the new session. Configuration flags specify the general configuration of units in the session. Access flags specify how the application will use the biometric units. You must specify one configuration flag but you can combine that flag with any access flag.
Value | Meaning |
---|---|
|
Group: configuration
The biometric units operate in the manner specified during installation. You must use this value when the PoolType parameter is WINBIO_POOL_SYSTEM. |
|
Group: configuration
The biometric units operate only as basic capture devices. All processing, matching, and storage operations is performed by software plug-ins. |
|
Group: configuration
The biometric units use internal processing and storage capabilities. |
|
Group: access
The client application captures raw biometric data using WinBioCaptureSample. |
|
Group: access
The client performs vendor-defined control operations on a biometric unit by calling WinBioControlUnitPrivileged. |
[in, optional] UnitArray
Pointer to an array of biometric unit identifiers to be included in the session. You can call WinBioEnumBiometricUnits to enumerate the biometric units. Set this value to NULL if the PoolType parameter is WINBIO_POOL_SYSTEM.
[in, optional] UnitCount
A value that specifies the number of elements in the array pointed to by the UnitArray parameter. Set this value to zero if the PoolType parameter is WINBIO_POOL_SYSTEM.
[in, optional] DatabaseId
A value that specifies the database(s) to be used by the session. If the PoolType parameter is WINBIO_POOL_PRIVATE, you must specify the GUID of an installed database. If the PoolType parameter is not WINBIO_POOL_PRIVATE, you can specify one of the following common values.
[in] NotificationMethod
Specifies how completion notifications for asynchronous operations in this biometric session are to be delivered to the client application. This must be one of the following values.
[in, optional] TargetWindow
Handle of the window that will receive the completion notices. This value is ignored unless the NotificationMethod parameter is set to WINBIO_ASYNC_NOTIFY_MESSAGE.
[in, optional] MessageCode
Window message code the framework must send to signify completion notices. This value is ignored unless the NotificationMethod parameter is set to WINBIO_ASYNC_NOTIFY_MESSAGE. The value must be within the range WM_APP(0x8000) to 0xBFFF.
The Windows Biometric Framework sets the LPARAM value of the message to the address of the WINBIO_ASYNC_RESULT structure that contains the results of the operation. You must call WinBioFree to release the structure after you have finished using it.
[in, optional] CallbackRoutine
Address of callback routine to be invoked when the operation started by using the session handle completes. This value is ignored unless the NotificationMethod parameter is set to WINBIO_ASYNC_NOTIFY_CALLBACK.
[in, optional] UserData
Address of a buffer supplied by the caller. The buffer is not modified by the framework or the biometric unit. It is returned in the WINBIO_ASYNC_RESULT structure. Your application can use the data to help it determine what actions to perform upon receipt of the completion notice or to maintain additional information about the requested operation.
[in] AsynchronousOpen
Specifies whether to block until the framework session has been opened. Specifying FALSE causes the process to block. Specifying TRUE causes the session to be opened asynchronously.
If you specify FALSE to open the framework session synchronously, success or failure is returned to the caller directly by this function in the HRESULT return value. If the session is opened successfully, the first asynchronous completion event your application receives will be for an asynchronous operation requested after the framework has been open.
If you specify TRUE to open the framework session asynchronously, the first asynchronous completion notice received will be for opening the framework. If the NotificationMethod parameter is set to WINBIO_ASYNC_NOTIFY_CALLBACK, operation results are delivered to the WINBIO_ASYNC_RESULT structure in the callback function specified by the CallbackRoutine parameter. If the NotificationMethod parameter is set to WINBIO_ASYNC_NOTIFY_MESSAGE, operation results are delivered to the WINBIO_ASYNC_RESULT structure pointed to by the LPARAM field of the window message.
[out, optional] SessionHandle
If the function does not succeed, this parameter will be NULL.
If the session is opened synchronously and successfully, this parameter will contain a pointer to the session handle.
If you specify that the session be opened asynchronously, this method returns immediately, the session handle will be NULL, and you must examine the WINBIO_ASYNC_RESULT structure to determine whether the session was successfully opened.
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 code | Description |
---|---|
|
There is not enough memory available to create the biometric session. |
|
If you set the notification method to WINBIO_ASYNC_NOTIFY_MESSAGE, the TargetWindow parameter cannot be NULL or HWND_BROADCAST and the MessageCode parameter cannot be zero (0). |
|
The SessionHandle parameter and the AsynchronousOpen parameter must be set.
If you set the notification method to WINBIO_ASYNC_NOTIFY_CALLBACK, you must also specify the address of a callback function in the CallbackRoutine parameter. |
|
The Flags parameter contains the WINBIO_FLAG_RAW or the WINBIO_FLAG_MAINTENANCE flag and the caller has not been granted either access permission. |
|
One or more of the biometric unit numbers specified in the UnitArray parameter is not valid. |
|
The client application is running on a remote desktop client and is attempting to open a system pool session. |
|
The PoolType parameter is set to WINBIO_POOL_PRIVATE and one or more of the requested sensors in that pool is not available. |
|
Current administrative policy prohibits use of the Windows Biometric Framework API. |
Remarks
The session handle returned by the WinBioAsyncOpenSession function can be used to generate asynchronous completion notifications for any of the following functions:
- WinBioCancel
- WinBioCaptureSample
- WinBioCloseSession
- WinBioControlUnit
- WinBioControlUnitPrivileged
- WinBioDeleteTemplate
- WinBioEnrollBegin
- WinBioEnrollCapture
- WinBioEnrollCommit
- WinBioEnrollDiscard
- WinBioEnumEnrollments
- WinBioGetProperty
- WinBioIdentify
- WinBioLocateSensor
- WinBioLockUnit
- WinBioLogonIdentifiedUser
- WinBioRegisterEventMonitor
- WinBioUnlockUnit
- WinBioUnregisterEventMonitor
- WinBioVerify
- WinBioWait
- WinBioCaptureSampleWithCallback
- WinBioEnrollCaptureWithCallback
- WinBioIdentifyWithCallback
- WinBioIdentifyWithCallback
The AsynchronousOpen parameter determines only whether the open operation will block. This parameter has no effect on the completion behavior of subsequent calls that use the session handle.
If you set the AsynchronousOpen parameter to TRUE, this function will return S_OK as soon as it has performed an initial validation of the arguments. Any errors detected beyond that point will be reported to the caller using the method specified by the NotificationMethod parameter. That is, a successful return value indicates only that the WinBioAsyncOpenSession parameters were fine and not that the open operation succeeded. To determine whether the open operation succeeded, you must examine the WINBIO_ASYNC_RESULT structure.
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 |