WinBioAsyncOpenSession 函式 （winbio.h）

非同步連接生物辨識服務提供者及一個或多個生物辨識單元。 從 Windows 10 版本 1607 開始，此功能可用於行動映像檔。 若成功，函式會回傳生物特徵會話句柄。 使用此句柄執行的所有操作都會非同步完成，包括 WinBioCloseSession，結果會依照 NotificationMethod 參數中指定的方法回傳給用戶端應用程式。

關於此函式的同步版本，請參見 WinBioOpenSession。

語法

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
);

參數

[in] Factor

一個由 WINBIO_BIOMETRIC_TYPE 旗標組成的位元遮罩，指定要列舉的生物特徵單位類型。 目前只支援 WINBIO_TYPE_FINGERPRINT 。

[in] PoolType

一個 ULONG 值，指定該會話中將使用的生物特徵單位類型。 這可以是下列其中一個值：

[in] Flags

ULONG 值，指定新會話的生物特徵單元配置與存取特性。 配置旗標指定會話中單元的一般配置。 存取標誌則指定應用程式如何使用生物特徵單元。 你必須指定一個設定標誌，但你可以將該標誌與任何存取標誌合併使用。

[in, optional] UnitArray

指標指向一組生物特徵單元識別碼陣列，將納入會話中。 你可以呼叫 WinBioEnumBiometricUnits 來列舉生物特徵單位。 如果 PoolType 參數為 WINBIO_POOL_SYSTEM，則將此值設為 NULL。

[in, optional] UnitCount

一個指定 UnitArray 參數指向陣列中元素數量的值。 如果 PoolType 參數為 WINBIO_POOL_SYSTEM，則將此值設為零。

[in, optional] DatabaseId

一個指定會話要使用的資料庫的值。 如果 PoolType 參數是 WINBIO_POOL_PRIVATE，你必須指定已安裝資料庫的 GUID。 如果 PoolType 參數未 WINBIO_POOL_PRIVATE，你可以指定以下常見值之一。

[in] NotificationMethod

規定此生物辨識會話中非同步操作的完成通知如何傳遞給用戶端應用程式。 這必須是以下其中一個數值。

[in, optional] TargetWindow

會收到完工通知的窗口。 除非 NotificationMethod 參數設為 WINBIO_ASYNC_NOTIFY_MESSAGE，否則此值會被忽略。

[in, optional] MessageCode

框架必須發送的視窗訊息代碼以表示完成通知。 除非 NotificationMethod 參數設為 WINBIO_ASYNC_NOTIFY_MESSAGE，否則此值會被忽略。 該值必須在WM_APP（0x8000）至0xBFFF範圍內。

Windows 生物特徵框架將訊息的 LPARAM 值設定為包含操作結果的 WINBIO_ASYNC_RESULT 結構的位址。 使用完後，必須聯絡 WinBioFree 來釋放該結構。

[in, optional] CallbackRoutine

當使用會話句柄開始操作時，要呼叫回調例程的位址。 除非 NotificationMethod 參數設為 WINBIO_ASYNC_NOTIFY_CALLBACK，否則此值會被忽略。

[in, optional] UserData

呼叫者提供的緩衝區位址。 緩衝區不會被框架或生物辨識單元修改。 它會被歸還在 WINBIO_ASYNC_RESULT 結構中。 您的應用程式可利用這些資料來決定收到完工通知後應執行的行動，或維持關於所請求作業的額外資訊。

[in] AsynchronousOpen

指定是否要封鎖直到框架會話開啟。 指定 FALSE 會導致程序阻塞。 指定 TRUE 會使該會話以非同步方式開啟。

如果你指定 FALSE 以同步開啟框架會話，成功或失敗會直接由這個函式以 HRESULT 回傳值給呼叫者。 若會話成功開啟，應用程式收到的第一個非同步完成事件將是框架開啟後請求的非同步操作。

如果你指定 TRUE 以非同步開啟框架會話，第一個非同步完成通知將是開啟框架時收到的。 若 NotificationMethod 參數設為 WINBIO_ASYNC_NOTIFY_CALLBACK，操作結果會依照 CallbackRoutine 參數指定的回調函式中，傳送至 WINBIO_ASYNC_RESULT 結構。 若 NotificationMethod 參數設為 WINBIO_ASYNC_NOTIFY_MESSAGE，操作結果會傳送至 LPARAM 欄位指向的 WINBIO_ASYNC_RESULT 結構。

[out, optional] SessionHandle

若函式未成功，該參數將為 NULL。

若會話是同步且成功開啟，該參數將包含指向會話句柄的指標。

如果你指定非同步開啟會話，這個方法會立即回傳，會話的句柄會是 NULL，你必須檢查 WINBIO_ASYNC_RESULT 結構以判斷該會話是否成功開啟。

返回值

如果函式成功，則會傳回 S_OK。 如果函式失敗，它會傳回指出錯誤的 HRESULT 值。 可能的值包括但不限於下表中的值。 如需常見錯誤碼的清單，請參閱 常見的 HRESULT 值。

備註

WinBioAsyncOpenSession 函式回傳的會話句柄可用於產生以下任一函式的非同步完成通知：

• WinBio取消
• WinBioCapture範例
• WinBioCloseSession
• WinBioControlUnit
• WinBioControlUnit特權
• WinBioDeleteTemplate
• WinBio註冊開始
• WinBioEnrollCapture
• WinBioEnrollCommit
• WinBioEnrollDiscard（WinBioEnrollDiscard）
• WinBioEnumenrollments
• WinBioGetProperty
• WinBioIdentify
• WinBioLocateSensor
• WinBioLockUnit
• WinBioLogonIdentifiedUser
• WinBioRegisterEventMonitor
• WinBio解鎖單元
• WinBioUnregisterEventMonitor
• WinBioVerify
• WinBioWait

• WinBioCaptureSampleWithCallback
• WinBio註冊CaptureWithCallback（回撥）
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

AsynchronousOpen 參數僅決定 open 操作是否會阻塞。 此參數不影響後續使用會話句柄的呼叫的完成行為。

如果你將 AsynchronousOpen 參數設為 TRUE，這個函式會在對參數進行初步驗證後立即回傳 S_OK 。 超過該點後偵測到的任何錯誤，都會依 照 NotificationMethod 參數指定的方法回報給呼叫者。 也就是說，成功的回傳值僅表示 WinBioAsyncOpenSession 參數正常，並不代表開啟操作成功。 要判斷公開行動是否成功，必須檢視 WINBIO_ASYNC_RESULT 結構。

需求

另請參閱

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession