WinBioAsyncOpenSession-Funktion (winbio.h)

Stellt asynchron eine Verbindung mit einem biometrischen Dienstanbieter und einer oder mehreren biometrischen Einheiten sicher. Ab Windows 10, Build 1607, ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar. Bei erfolgreicher Ausführung gibt die Funktion ein biometrisches Sitzungshandle zurück. Jeder vorgang, der mit diesem Handle ausgeführt wird, wird asynchron abgeschlossen, einschließlich WinBioCloseSession, und die Ergebnisse werden mithilfe der im NotificationMethod-Parameter angegebenen Methode an die Clientanwendung zurückgegeben.

Eine synchrone Version dieser Funktion finden Sie unter 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
);

Die Parameter

[in] Factor

Eine Bitmaske von WINBIO_BIOMETRIC_TYPE Flags, die die biometrischen Einheitentypen angibt, die aufgezählt werden sollen. Derzeit wird nur WINBIO_TYPE_FINGERPRINT unterstützt.

[in] PoolType

Ein ULONG-Wert , der den Typ der biometrischen Einheiten angibt, die in der Sitzung verwendet werden. Dies kann einer der folgenden Werte sein:

[in] Flags

Ein ULONG-Wert , der die Konfiguration und Zugriffsmerkmale der biometrischen Einheit für die neue Sitzung angibt. Konfigurationskennzeichnungen geben die allgemeine Konfiguration von Einheiten in der Sitzung an. Zugriffskennzeichnungen geben an, wie die Anwendung die biometrischen Einheiten verwendet. Sie müssen ein Konfigurationsflagge angeben, aber Sie können dieses Kennzeichen mit jeder Zugriffskennzeichnung kombinieren.

[in, optional] UnitArray

Zeiger auf ein Array von biometrischen Einheitenbezeichnern, die in die Sitzung aufgenommen werden sollen. Sie können WinBioEnumBiometricUnits aufrufen, um die biometrischen Einheiten aufzählen zu können. Legen Sie diesen Wert auf NULL fest, wenn der PoolType-ParameterWINBIO_POOL_SYSTEM ist.

[in, optional] UnitCount

Ein Wert, der die Anzahl der Elemente im Array angibt, auf die der UnitArray-Parameter verweist. Legen Sie diesen Wert auf Null fest, wenn der Parameter "PoolType " WINBIO_POOL_SYSTEM ist.

[in, optional] DatabaseId

Ein Wert, der die datenbank(n) angibt, die von der Sitzung verwendet werden soll. Wenn der Parameter "PoolType " WINBIO_POOL_PRIVATE ist, müssen Sie die GUID einer installierten Datenbank angeben. Wenn der Parameter "PoolType " nicht WINBIO_POOL_PRIVATE ist, können Sie einen der folgenden allgemeinen Werte angeben.

[in] NotificationMethod

Gibt an, wie Abschlussbenachrichtigungen für asynchrone Vorgänge in dieser biometrischen Sitzung an die Clientanwendung übermittelt werden sollen. Dies muss einer der folgenden Werte sein.

[in, optional] TargetWindow

Handle des Fensters, das die Abschlusshinweise erhält. Dieser Wert wird ignoriert, es sei denn, der Parameter NotificationMethod ist auf WINBIO_ASYNC_NOTIFY_MESSAGE festgelegt.

[in, optional] MessageCode

Window message code the framework must send to signify completion notices. Dieser Wert wird ignoriert, es sei denn, der Parameter NotificationMethod ist auf WINBIO_ASYNC_NOTIFY_MESSAGE festgelegt. Der Wert muss sich innerhalb des Bereichs WM_APP(0x8000) befinden, um 0xBFFF.

Das Windows Biometric Framework legt den LPARAM-Wert der Nachricht auf die Adresse der WINBIO_ASYNC_RESULT Struktur fest, die die Ergebnisse des Vorgangs enthält. Sie müssen WinBioFree aufrufen, um die Struktur freizugeben, nachdem Sie sie verwendet haben.

[in, optional] CallbackRoutine

Die Adresse der Rückrufroutine, die aufgerufen werden soll, wenn der Vorgang mit dem Sitzungshandle gestartet wird. Dieser Wert wird ignoriert, es sei denn, der Parameter NotificationMethod ist auf WINBIO_ASYNC_NOTIFY_CALLBACK festgelegt.

[in, optional] UserData

Adresse eines vom Aufrufer bereitgestellten Puffers. Der Puffer wird nicht vom Framework oder der biometrischen Einheit geändert. Sie wird in der WINBIO_ASYNC_RESULT-Struktur zurückgegeben. Ihre Anwendung kann die Daten verwenden, um zu bestimmen, welche Aktionen nach Erhalt des Abschlusshinweiss ausgeführt werden sollen, oder um zusätzliche Informationen über den angeforderten Vorgang zu erhalten.

[in] AsynchronousOpen

Gibt an, ob blockiert werden soll, bis die Frameworksitzung geöffnet wurde. Das Angeben von FALSE bewirkt, dass der Prozess blockiert wird. Wenn WAHR angegeben wird, wird die Sitzung asynchron geöffnet.

Wenn Sie FALSE angeben, um die Frameworksitzung synchron zu öffnen, wird Erfolg oder Fehler direkt von dieser Funktion im HRESULT-Rückgabewert an den Aufrufer zurückgegeben. Wenn die Sitzung erfolgreich geöffnet wird, wird das erste asynchrone Abschlussereignis, das Ihre Anwendung empfängt, für einen asynchronen Vorgang verwendet, der nach dem Öffnen des Frameworks angefordert wird.

Wenn Sie TRUE angeben, um die Framework-Sitzung asynchron zu öffnen, wird der erste empfangene asynchrone Abschlusshinweis zum Öffnen des Frameworks verwendet. Wenn der Parameter NotificationMethod auf WINBIO_ASYNC_NOTIFY_CALLBACK festgelegt ist, werden die Vorgangsergebnisse in der durch den CallbackRoutine-Parameter angegebenen Rückruffunktion an die WINBIO_ASYNC_RESULT Struktur übermittelt. Wenn der Parameter NotificationMethod auf WINBIO_ASYNC_NOTIFY_MESSAGE festgelegt ist, werden die Vorgangsergebnisse an die WINBIO_ASYNC_RESULT Struktur übermittelt, auf die das LPARAM-Feld der Fensternachricht verweist.

[out, optional] SessionHandle

Wenn die Funktion nicht erfolgreich ist, ist dieser Parameter NULL.

Wenn die Sitzung synchron und erfolgreich geöffnet wird, enthält dieser Parameter einen Zeiger auf das Sitzungshandle.

Wenn Sie angeben, dass die Sitzung asynchron geöffnet wird, gibt diese Methode sofort zurück, der Sitzungshandle ist NULL, und Sie müssen die WINBIO_ASYNC_RESULT Struktur untersuchen, um zu ermitteln, ob die Sitzung erfolgreich geöffnet wurde.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, wird ein HRESULT-Wert zurückgegeben, der den Fehler angibt. Mögliche Werte sind die Werte in der folgenden Tabelle, sind jedoch nicht beschränkt. Eine Liste allgemeiner Fehlercodes finden Sie unter "Allgemeine HRESULT-Werte".

Bemerkungen

Das von der WinBioAsyncOpenSession-Funktion zurückgegebene Sitzungshandle kann verwendet werden, um asynchrone Abschlussbenachrichtigungen für eine der folgenden Funktionen zu generieren:

• 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

Der Parameter "AsynchronousOpen" bestimmt nur, ob der Öffnenvorgang blockiert wird. Dieser Parameter hat keine Auswirkungen auf das Vervollständigungsverhalten der nachfolgenden Aufrufe, die das Sitzungshandle verwenden.

Wenn Sie den Parameter "AsynchronousOpen" auf TRUE festlegen, gibt diese Funktion S_OK zurück, sobald sie eine anfängliche Überprüfung der Argumente ausgeführt hat. Alle über diesen Punkt erkannten Fehler werden dem Aufrufer mithilfe der durch den Parameter NotificationMethod angegebenen Methode gemeldet. Das heißt, ein erfolgreicher Rückgabewert gibt nur an, dass die WinBioAsyncOpenSession-Parameter einwandfrei waren und nicht, dass der Öffnenvorgang erfolgreich war. Um festzustellen, ob der Öffnenvorgang erfolgreich war, müssen Sie die WINBIO_ASYNC_RESULT Struktur untersuchen.

Anforderungen

Siehe auch

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession