WinBioAsyncOpenSession-Funktion (winbio.h)

Artikel
08/27/2023

Stellt asynchron eine Verbindung mit einem biometrischen Dienstanbieter und einer oder mehreren biometrischen Einheiten her. 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
);

Parameter

[in] Factor

Eine Bitmaske mit WINBIO_BIOMETRIC_TYPE Flags, die die zu enumerierten biometrischen Einheitentypen angibt. 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. Mögliche Werte:

Wert	Bedeutung
WINBIO_POOL_SYSTEM	Die Sitzung stellt eine Verbindung mit einer freigegebenen Sammlung biometrischer Einheiten her, die vom Dienstanbieter verwaltet werden.
WINBIO_POOL_PRIVATE	Die Sitzung stellt eine Verbindung mit einer Sammlung biometrischer Einheiten her, die vom Aufrufer verwaltet werden.

[in] Flags

Ein ULONG-Wert , der die Konfiguration der biometrischen Einheit und die Zugriffsmerkmale für die neue Sitzung angibt. Konfigurationsflags geben die allgemeine Konfiguration von Einheiten in der Sitzung an. Zugriffsflags geben an, wie die Anwendung die biometrischen Einheiten verwendet. Sie müssen ein Konfigurationsflag angeben, aber Sie können dieses Flag mit einem beliebigen Zugriffsflag kombinieren.

Wert	Bedeutung
WINBIO_FLAG_DEFAULT	Gruppe: Konfiguration Die biometrischen Einheiten funktionieren in der während der Installation angegebenen Weise. Sie müssen diesen Wert verwenden, wenn der PoolType-ParameterWINBIO_POOL_SYSTEM ist.
WINBIO_FLAG_BASIC	Gruppe: Konfiguration Die biometrischen Einheiten funktionieren nur als einfache Erfassungsgeräte. Alle Verarbeitungs-, Abgleichs- und Speichervorgänge werden von Software-Plug-Ins ausgeführt.
WINBIO_FLAG_ADVANCED	Gruppe: Konfiguration Die biometrischen Einheiten verwenden interne Verarbeitungs- und Speicherfunktionen.
WINBIO_FLAG_RAW	Gruppe: Access Die Clientanwendung erfasst biometrische Rohdaten mithilfe von WinBioCaptureSample.
WINBIO_FLAG_MAINTENANCE	Gruppe: Access Der Client führt vom Hersteller definierte Kontrollvorgänge für eine biometrische Einheit durch, indem WinBioControlUnitPrivileged aufgerufen wird.

[in, optional] UnitArray

Zeiger auf ein Array von biometrischen Einheitenbezeichnern, die in die Sitzung eingeschlossen werden sollen. Sie können WinBioEnumBiometricUnits aufrufen, um die biometrischen Einheiten aufzulisten. 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 das der UnitArray-Parameter verweist. Legen Sie diesen Wert auf 0 fest, wenn der Parameter PoolTypeWINBIO_POOL_SYSTEM ist.

[in, optional] DatabaseId

Ein -Wert, der die von der Sitzung zu verwendenden Datenbanken angibt. Wenn der PoolType-ParameterWINBIO_POOL_PRIVATE ist, müssen Sie die GUID einer installierten Datenbank angeben. Wenn der PoolType-Parameter nicht WINBIO_POOL_PRIVATE ist, können Sie einen der folgenden allgemeinen Werte angeben.

Wert	Bedeutung
WINBIO_DB_DEFAULT	Jede biometrische Einheit im Sensorpool verwendet die Standarddatenbank, die in der Konfiguration der biometrischen Standardeinheit angegeben ist. Sie müssen diesen Wert angeben, wenn der Parameter PoolTypeWINBIO_POOL_SYSTEM ist. Sie können diesen Wert nicht verwenden, wenn der PoolType-ParameterWINBIO_POOL_PRIVATE
WINBIO_DB_BOOTSTRAP	Sie können diesen Wert angeben, der für Szenarien vor dem Starten von Windows verwendet werden soll. In der Regel ist die Datenbank Teil des Sensorchips oder Teil des BIOS und kann nur zum Registrieren und Löschen von Vorlagen verwendet werden.
WINBIO_DB_ONCHIP	Die Datenbank befindet sich auf dem Sensorchip und steht für die Registrierung und den Abgleich zur Verfügung.

[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.

Wert	Bedeutung
WINBIO_ASYNC_NOTIFY_CALLBACK	Die Sitzung ruft die von der Anwendung definierte Rückruffunktion auf.
WINBIO_ASYNC_NOTIFY_MESSAGE	Die Sitzung sendet eine Fensternachricht an die Nachrichtenwarteschlange der Anwendung.

[in, optional] TargetWindow

Handle des Fensters, das die Vervollständigungsbenachrichtigungen empfängt. Dieser Wert wird ignoriert, es sei denn, der NotificationMethod-Parameter ist auf WINBIO_ASYNC_NOTIFY_MESSAGE festgelegt.

[in, optional] MessageCode

Fensternachrichtencode, den das Framework senden muss, um Vervollständigungshinweise zu kennzeichnen. Dieser Wert wird ignoriert, es sei denn, der NotificationMethod-Parameter ist auf WINBIO_ASYNC_NOTIFY_MESSAGE festgelegt. Der Wert muss innerhalb des Bereichs liegen, der WM_APP(0x8000) 0xBFFF werden soll.

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

Adresse der Rückrufroutine, die aufgerufen werden soll, wenn der Vorgang mithilfe des Sitzungshandles gestartet wird. Dieser Wert wird ignoriert, es sei denn, der NotificationMethod-Parameter ist auf WINBIO_ASYNC_NOTIFY_CALLBACK festgelegt.

[in, optional] UserData

Adresse eines vom Aufrufer bereitgestellten Puffers. Der Puffer wird vom Framework oder der biometrischen Einheit nicht 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 der Abschlussbenachrichtigung ausgeführt werden sollen, oder um zusätzliche Informationen zum angeforderten Vorgang zu verwalten.

[in] AsynchronousOpen

Gibt an, ob blockiert werden soll, bis die Frameworksitzung geöffnet wurde. Die Angabe von FALSE bewirkt, dass der Prozess blockiert wird. Die Angabe von TRUE bewirkt, dass die Sitzung asynchron geöffnet wird.

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 wurde, ist das erste asynchrone Abschlussereignis, das Ihre Anwendung empfängt, für einen asynchronen Vorgang, der nach dem Öffnen des Frameworks angefordert wird.

Wenn Sie TRUE angeben, um die Frameworksitzung asynchron zu öffnen, wird der erste asynchrone Abschlusshinweis zum Öffnen des Frameworks empfangen. Wenn der NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_CALLBACK festgelegt ist, werden die Vorgangsergebnisse an die WINBIO_ASYNC_RESULT-Struktur in der rückruffunktion übermittelt, die durch den CallbackRoutine-Parameter angegeben wird. Wenn der NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_MESSAGE festgelegt ist, werden die Vorgangsergebnisse an die WINBIO_ASYNC_RESULT Struktur übermittelt, auf die das LPARAM-Feld der Fenstermeldung 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, das Sitzungshandle ist NULL, und Sie müssen die WINBIO_ASYNC_RESULT Struktur untersuchen, um festzustellen, 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ögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle. Eine Liste allgemeiner Fehlercodes finden Sie unter Allgemeine HRESULT-Werte.

Rückgabecode	Beschreibung
E_OUTOFMEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar, um die biometrische Sitzung zu erstellen.
E_INVALIDARG	Wenn Sie die Benachrichtigungsmethode auf WINBIO_ASYNC_NOTIFY_MESSAGE festlegen, kann der Parameter TargetWindow nicht NULL oder HWND_BROADCAST und der MessageCode-Parameter nicht null (0) sein.
E_POINTER	Der SessionHandle-Parameter und der AsynchronousOpen-Parameter müssen festgelegt werden. Wenn Sie die Benachrichtigungsmethode auf WINBIO_ASYNC_NOTIFY_CALLBACK festlegen, müssen Sie auch die Adresse einer Rückruffunktion im Parameter CallbackRoutine angeben.
E_ACCESSDENIED	Der Flags-Parameter enthält das WINBIO_FLAG_RAW - oder das WINBIO_FLAG_MAINTENANCE-Flag , und dem Aufrufer wurde keine Zugriffsberechtigung erteilt.
WINBIO_E_INVALID_UNIT	Mindestens eine der im UnitArray-Parameter angegebenen biometrischen Einheitennummern ist ungültig.
WINBIO_E_NOT_ACTIVE_CONSOLE	Die Clientanwendung wird auf einem Remotedesktopclient ausgeführt und versucht, eine Systempoolsitzung zu öffnen.
WINBIO_E_SENSOR_UNAVAILABLE	Der Parameter PoolType ist auf WINBIO_POOL_PRIVATE festgelegt, und mindestens einer der angeforderten Sensoren in diesem Pool ist nicht verfügbar.
WINBIO_E_DISABLED	Die aktuelle Verwaltungsrichtlinie verbietet die Verwendung der Windows Biometric Framework-API.

Hinweise

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

Das von WinBioAsyncOpenSession zurückgegebene Sitzungshandle kann nicht mit den folgenden Funktionen verwendet werden:

Diese Funktionen, die zuerst in Windows 7 verfügbar sind, verfügen über eine inkompatible Rückrufsignatur, und von der Verwendung in neuen Anwendungen wird abgeraten. Entwickler, die asynchrone Rückrufe wünschen, sollten stattdessen WinBioAsyncOpenSession mit einer NotificationMethodWINBIO_ASYNC_NOTIFY_CALLBACK verwenden.

Der AsynchronousOpen-Parameter bestimmt nur, ob der geöffnete Vorgang blockiert wird. Dieser Parameter hat keine Auswirkungen auf das Vervollständigungsverhalten von nachfolgenden Aufrufen, die das Sitzungshandle verwenden.

Wenn Sie den AsynchronousOpen-Parameter auf TRUE festlegen, gibt diese Funktion S_OK zurück, sobald sie eine erste Validierung der Argumente durchgeführt hat. Alle Fehler, die über diesen Punkt hinaus erkannt werden, werden dem Aufrufer mithilfe der vom NotificationMethod-Parameter angegebenen Methode gemeldet. Das heißt, ein erfolgreicher Rückgabewert gibt nur an, dass die WinBioAsyncOpenSession-Parameter in Ordnung waren und nicht, dass der geöffnete Vorgang erfolgreich war. Um zu ermitteln, ob der Geöffnete Vorgang erfolgreich war, müssen Sie die WINBIO_ASYNC_RESULT Struktur untersuchen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbio.h (winbio.h einschließen)
Bibliothek	Winbio.lib
DLL	Winbio.dll

Weitere Informationen

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession

Freigeben über