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值，指定將在會話中使用的生物特徵辨識單位類型。 這個值可以是下列其中一個值：

值	意義
WINBIO_POOL_SYSTEM	會話會連線到服務提供者所管理生物特徵辨識單位的共用集合。
WINBIO_POOL_PRI加值稅E	會話會連線到呼叫端所管理生物特徵辨識單位的集合。

[in] Flags

ULONG值，指定新會話的生物特徵辨識單位組態和存取特性。 組態旗標會指定會話中單位的一般設定。 存取旗標會指定應用程式如何使用生物特徵辨識單位。 您必須指定一個組態旗標，但您可以將該旗標與任何存取旗標結合。

值	意義
WINBIO_FLAG_DEFAULT	群組：組態 生物特徵辨識單位會以安裝期間指定的方式運作。 當 PoolType 參數 WINBIO_POOL_SYSTEM時，您必須使用此值。
WINBIO_FLAG_BASIC	群組：組態 生物特徵辨識單位只會以基本擷取裝置的形式運作。 所有處理、比對和儲存作業都是由軟體外掛程式執行。
WINBIO_FLAG_ADVANCED	群組：組態 生物特徵辨識單位使用內部處理和儲存功能。
WINBIO_FLAG_RAW	群組：存取 用戶端應用程式會使用 WinBioCaptureSample擷取原始生物特徵辨識資料。
WINBIO_FLAG_MAINTENANCE	群組：存取 用戶端會呼叫 WinBioControlUnitPrivileged，在生物特徵辨識單位上執行廠商定義的控制作業。

[in, optional] UnitArray

要包含在會話中的生物特徵辨識單位識別碼陣列指標。 您可以呼叫 WinBioEnumBiometricUnits 來列舉生物特徵辨識單位。 如果PoolType參數WINBIO_POOL_SYSTEM，請將此值設定為Null。

[in, optional] UnitCount

值，指定 UnitArray 參數所指向之陣列中的專案數目。 如果 PoolType 參數 WINBIO_POOL_SYSTEM，請將此值設定為零。

[in, optional] DatabaseId

值，指定會話要使用的資料庫 () 。 如果 PoolType 參數 WINBIO_POOL_PRI加值稅E，您必須指定已安裝資料庫的 GUID。 如果 PoolType 參數未 WINBIO_POOL_PRI加值稅E，您可以指定下列其中一個通用值。

值	意義
WINBIO_DB_DEFAULT	感應器集區中的每個生物特徵辨識單位都會使用預設生物特徵辨識單位設定中指定的預設資料庫。 如果 PoolType 參數 WINBIO_POOL_SYSTEM，您必須指定此值。 如果PoolType參數WINBIO_POOL_PRI加值稅E，則無法使用此值
WINBIO_DB_BOOTSTRAP	您可以在啟動 Windows 之前，指定要用於案例的這個值。 一般而言，資料庫是感應器晶片的一部分，或是 BIOS 的一部分，而且只能用於範本註冊和刪除。
WINBIO_DB_ONCHIP	資料庫位於感應器晶片上，可供註冊和比對。

[in] NotificationMethod

指定此生物特徵辨識會話中非同步作業的完成通知如何傳遞至用戶端應用程式。 這必須是下列其中一個值。

值	意義
WINBIO_ASYNC_NOTIFY_CALLBACK	會話會叫用應用程式所定義的回呼函式。
WINBIO_ASYNC_NOTIFY_MESSAGE	會話會將視窗訊息張貼至應用程式的訊息佇列。

[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 值。

傳回碼	描述
E_OUTOFMEMORY	沒有足夠的記憶體可用來建立生物特徵辨識會話。
E_INVALIDARG	如果您將通知方法設定為 WINBIO_ASYNC_NOTIFY_MESSAGE， TargetWindow 參數不能是 Null 或 HWND_BROADCAST ， 而且 MessageCode 參數不能是零 (0) 。
E_POINTER	必須設定 SessionHandle 參數和 AsynchronousOpen 參數。 如果您將通知方法設定為 WINBIO_ASYNC_NOTIFY_CALLBACK，您也必須在 CallbackRoutine 參數中指定回呼函式的位址。
E_ACCESSDENIED	Flags參數包含WINBIO_FLAG_RAW或WINBIO_FLAG_MAINTENANCE旗標，而且呼叫端尚未獲得任何存取權限。
WINBIO_E_INVALID_UNIT	UnitArray參數中指定的一或多個生物特徵辨識單位編號無效。
WINBIO_E_NOT_ACTIVE_CONSOLE	用戶端應用程式正在遠端桌面用戶端上執行，並嘗試開啟系統集區會話。
WINBIO_E_SENSOR_UNAVAILABLE	PoolType參數設定為WINBIO_POOL_PRI加值稅E，且該集區中一或多個要求的感應器無法使用。
WINBIO_E_DISABLED	目前的系統管理原則禁止使用 Windows 生物特徵辨識架構 API。

備註

WinBioAsyncOpenSession函式所傳回的會話控制碼可用來產生下列任一函式的非同步完成通知：

• WinBioCancel
• WinBioCaptureSample
• WinBioCloseSession
• WinBioControlUnit
• WinBioControlUnitPrivileged
• WinBioDeleteTemplate
• WinBioEnrollBegin
• WinBioEnrollCapture
• WinBioEnrollCommit
• WinBioEnrollDiscard
• WinBioEnumEnrollments
• WinBioGetProperty
• WinBioIdentify
• WinBioLocateSensor
• WinBioLockUnit
• WinBioLogonIdentifiedUser
• WinBioRegisterEventMonitor
• WinBioUnlockUnit
• WinBioUnregisterEventMonitor
• WinBioVerify
• WinBioWait

WinBioAsyncOpenSession傳回的會話控制碼無法搭配下列函式使用：

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

這些函式會先在 Windows 7 中提供，具有不相容的回呼簽章，不建議在新的應用程式中使用。 想要非同步回呼的開發人員應該改用WinBioAsyncOpenSession搭配WINBIO_ASYNC_NOTIFY_CALLBACK的NotificationMethod。

SyncOpen參數只會決定開啟的作業是否會封鎖。 此參數不會影響使用會話控制碼之後續呼叫的完成行為。

如果您將 SyncOpen 參數設定為 TRUE，此函式會在執行引數的初始驗證後立即傳回 S_OK 。 超過該點之後偵測到的任何錯誤，都會使用 NotificationMethod 參數所指定的方法來向呼叫端回報。 也就是說，成功的傳回值只會指出 WinBioAsyncOpenSession 參數正常，而不是開啟的作業成功。 若要判斷開啟作業是否成功，您必須檢查 WINBIO_ASYNC_RESULT 結構。

規格需求

最低支援的用戶端	Windows 8 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 [僅限傳統型應用程式]
目標平台	Windows
標頭	winbio.h (包含 Winbio.h)
程式庫	Winbio.lib
Dll	Winbio.dll

另請參閱

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession