WinBioAsyncOpenFramework-Funktion (winbio.h)

Artikel
08/27/2023

Öffnet ein Handle für das biometrische Framework. Ab Windows 10, Build 1607, ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar. Sie können dieses Handle verwenden, um biometrische Einheiten, Datenbanken und Dienstanbieter asynchron aufzulisten und asynchrone Benachrichtigungen zu erhalten, wenn biometrische Einheiten an den Computer angefügt oder entfernt werden.

Syntax

HRESULT WinBioAsyncOpenFramework(
  [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]          WINBIO_FRAMEWORK_HANDLE           *FrameworkHandle
);

Parameter

[in] NotificationMethod

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

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

[in, optional] TargetWindow

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

[in, optional] MessageCode

Fenstermeldungscode, 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.

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 für Vervollständigungsbenachrichtigungen aufgerufen werden soll. Dieser Wert wird ignoriert, es sei denn, der NotificationMethod-Parameter ist auf WINBIO_ASYNC_NOTIFY_CALLBACK festgelegt.

[in, optional] UserData

Adresse eines Puffers, der vom Aufrufer bereitgestellt wird. 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 führt dazu, dass die Sitzung asynchron geöffnet wird.

Wenn Sie FALSE angeben, um die Frameworksitzung synchron zu öffnen, wird der Erfolg oder Fehler direkt von dieser Funktion im HRESULT-Rückgabewert an den Aufrufer zurückgegeben. Wenn die Sitzung erfolgreich geöffnet wurde, wird das erste asynchrone Vervollständigungsereignis, 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 Frameworksitzung asynchron zu öffnen, wird der erste asynchrone Vervollständigungshinweis 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 Feld LPARAM der Fensternachricht verweist.

[out] FrameworkHandle

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, gibt sie S_OK zurück. Wenn die Funktion fehlschlägt, gibt sie einen HRESULT-Wert zurück, 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 Frameworksitzung zu erstellen.
E_INVALIDARG	Wenn Sie die Benachrichtigungsmethode auf WINBIO_ASYNC_NOTIFY_MESSAGE festlegen, kann der TargetWindow-Parameter nicht NULL oder HWND_BROADCAST und der MessageCode-Parameter nicht 0 (0) sein.
E_POINTER	Der FrameworkHandle-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 CallbackRoutine-Parameter angeben.

Hinweise

Das von der WinBioAsyncOpenFramework-Funktion zurückgegebene Frameworkhandle kann verwendet werden, um asynchrone Vervollständigungsbenachrichtigungen für die folgenden Funktionen zu generieren:

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

Wenn Sie den AsynchronousOpen-Parameter auf TRUE festlegen, gibt diese Funktion S_OK zurück, sobald sie eine erste Überprüfung der Argumente durchgeführt hat. Alle Fehler, die über diesen Punkt hinaus erkannt werden, werden dem Aufrufer mit der vom NotificationMethod-Parameter angegebenen Methode gemeldet. Das heißt, ein erfolgreicher Rückgabewert gibt nur an, dass die WinBioAsyncOpenFramework-Parameter in Ordnung waren und nicht, dass der geöffnete Vorgang erfolgreich war. Um festzustellen, 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 (einschließlich Winbio.h)
Bibliothek	Winbio.lib
DLL	Winbio.dll

Weitere Informationen

WinBioAsyncOpenSession

Freigeben über