WinBioRegisterEventMonitor-Funktion (winbio.h)
Die WinBioRegisterEventMonitor-Funktion registriert eine Rückruffunktion, um Ereignisbenachrichtigungen vom Dienstanbieter zu empfangen, der einer geöffneten Sitzung zugeordnet ist.
Syntax
HRESULT WinBioRegisterEventMonitor(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_EVENT_TYPE EventMask,
[in] PWINBIO_EVENT_CALLBACK EventCallback,
[in] PVOID EventCallbackContext
);
Parameter
[in] SessionHandle
Ein WINBIO_SESSION_HANDLE Wert, der die offene biometrische Sitzung identifiziert. Öffnen Sie das Sitzungshandle, indem Sie WinBioOpenSession aufrufen.
[in] EventMask
Ein Wert, der die Zu überwachenden Ereignistypen angibt. Derzeit wird nur der Fingerabdruckanbieter unterstützt. Sie müssen eines der folgenden Flags angeben.
- WINBIO_EVENT_FP_UNCLAIMED
Der Sensor hat einen Finger wischen erkannt, der von der Anwendung nicht angefordert wurde, oder die anfordernde Anwendung hat keinen Fensterfokus. Das Windows Biometric Framework ruft Ihre Rückruffunktion auf, um anzugeben, dass ein Finger wischen stattgefunden hat, aber nicht versucht, den Fingerabdruck zu identifizieren.
- WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY
Der Sensor hat einen Finger wischen erkannt, der von der Anwendung nicht angefordert wurde, oder die anfordernde Anwendung hat keinen Fensterfokus. Das Windows Biometric Framework versucht, den Fingerabdruck zu identifizieren, und übergibt das Ergebnis dieses Prozesses an Ihre Rückruffunktion.
[in] EventCallback
Adresse einer Rückruffunktion, die die vom Windows Biometric Framework gesendeten Ereignisbenachrichtigungen empfängt. Sie müssen diese Funktion definieren.
[in] EventCallbackContext
Ein optionaler anwendungsdefinierter Wert, der im pvContext-Parameter der Rückruffunktion zurückgegeben wird. Dieser Wert kann alle Daten enthalten, für die die benutzerdefinierte Rückruffunktion konzipiert ist.
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 |
|---|---|
|
Das Sitzungshandle ist ungültig. |
|
Die Adresse der Rückruffunktion, die durch den EventCallback-Parameter angegeben wird, darf nicht NULL sein. |
|
Der EventMask-Parameter darf nicht 0 sein, und Sie können nicht gleichzeitig WINBIO_EVENT_FP_UNCLAIMED und WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY angeben. |
|
Ein aktiver Ereignismonitor wurde bereits registriert. |
|
Der Dienstanbieter unterstützt keine Ereignisbenachrichtigungen. |
Hinweise
Diese Funktion ist nur für Sitzungen gültig, die mit einem Systemsensorpool verbunden sind.
Ereignisrückrufe werden seriell an die Clientanwendung übermittelt. Daher werden nachfolgende Ereignisbenachrichtigungen erst übermittelt, wenn der Client vom aktuellen Rückruf zurückkehrt. Ereignisse, die auftreten, während ein Rückruf noch ausgeführt wird, werden möglicherweise vom System verworfen. Um Den Verlust von Ereignissen zu vermeiden, sollten Sie keine zeitaufwendigen Arbeiten in Ihrer Rückrufroutine ausführen.
Die Clientanwendung sollte auf den Empfang von Ereignissen vorbereitet sein, sobald WinBioRegisterEventMonitor aufgerufen wird. Die Anwendung muss WinBioFree aufrufen, um die im Ereignisargument des Rückrufs zurückgegebene Struktur freizugeben. Wenn dies nicht geschieht, führt dies zu einem Speicherverlust im aufrufenden Prozess.
Nachdem ein Ereignismonitor gestartet wurde, kann die Sitzung, der der Monitor zugeordnet ist, andere Aufrufe der Windows Biometric Framework-API erst verarbeiten, wenn der Ereignismonitor beendet wurde. Wenn Ihre Anwendung andere API-Aufrufe ausführen muss, während sie weiterhin Ereignismonitorbenachrichtigungen empfängt, sollten Sie zwei Sitzungen öffnen – eine für den Ereignismonitor und eine andere für andere Vorgänge.
Rufen Sie WinBioUnregisterEventMonitor auf, um das Senden von Ereignisbenachrichtigungen an Ihre Rückruffunktion zu beenden.
Wenn eine Anwendung einen WinBio-Ereignismonitor registriert und diesen Monitor während eines Standby-/Aktivierungszyklus aktiv lässt, funktionieren Systeme, die die biometrische Pre-Boot-Authentifizierung (PBA)/Single Sign-On-Features implementieren, möglicherweise nicht immer. Das Problem besteht darin, dass der biometrische PBA-Aufruf vom Ereignismonitor abgefangen wird, bevor der Anbieter biometrischer Anmeldeinformationen des Systems die Möglichkeit hat, seinen ersten WinBioIdentify-Vorgang auszuführen. Apps, die das WinBio-Ereignisüberwachungsfeature verwenden, sollten die Registrierung ihrer Monitore aufheben, bevor das System in den Ruhezustand versetzt wird, und sie nach der Systemreaktivierung erneut registrieren. Weitere Informationen zum Behandeln von Ereignissen bei Änderungen des Energiezustands finden Sie unter Informationen zur Energieverwaltung.
Die Rückrufroutine muss die folgende Signatur aufweisen:
VOID CALLBACK EventCallback(
__in_opt PVOID EventCallbackContext,
__in HRESULT OperationStatus,
__in PWINBIO_EVENT Event
);
Beispiele
Die folgende Funktion registriert einen Ereignismonitor, indem die WinBioRegisterEventMonitor-Funktion aufgerufen und die Adresse einer Rückrufroutine übergeben wird. Der ebenfalls enthaltene Rückruf empfängt Ereignisbenachrichtigungen vom biometrischen Windows-Framework. Verknüpfen Sie die statische Bibliothek Winbio.lib, und fügen Sie die folgenden Headerdateien ein:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT RegisterSystemEventMonitor(BOOL bCancel)
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
// Connect to the system pool.
hr = WinBioOpenSession(
WINBIO_TYPE_FINGERPRINT, // Service provider
WINBIO_POOL_SYSTEM, // Pool type
WINBIO_FLAG_DEFAULT, // Configuration and access
NULL, // Array of biometric unit IDs
0, // Count of biometric unit IDs
NULL, // Database ID
&sessionHandle // [out] Session handle
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Call the WinBioRegisterEventMonitor function.
wprintf_s(L"\n Calling WinBioRegisterEventMonitor.\n");
hr = WinBioRegisterEventMonitor(
sessionHandle, // Open session handle
WINBIO_EVENT_FP_UNCLAIMED, // Events to monitor
EventMonitorCallback, // Callback function
NULL // Optional context.
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioRegisterEventMonitor failed.");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Waiting for an event.\n");
// Cancel the identification if the bCancel flag is set.
if (bCancel)
{
wprintf_s(L"\n Starting CANCEL timer...\n");
Sleep( 7000 );
wprintf_s(L"\n Calling WinBioCancel\n");
hr = WinBioCancel( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioCancel failed. hr = 0x%x\n", hr);
goto e_Exit;
}
}
// Wait for an event to happen.
//wprintf_s(L"\n Swipe the sensor to receive an event notice ");
//wprintf_s(L"\n or press any key to stop waiting...\n");
wprintf_s(L"\n Swipe the sensor one or more times ");
wprintf_s(L"to generate events.");
wprintf_s(L"\n When done, press a key to exit...\n");
_getch();
// Unregister the event monitor.
wprintf_s(L"\n Calling WinBioUnregisterEventMonitor\n");
hr = WinBioUnregisterEventMonitor( sessionHandle);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioUnregisterEventMonitor failed.");
wprintf_s(L"hr = 0x%x\n", hr);
}
e_Exit:
if (sessionHandle != NULL)
{
wprintf_s(L"\n Closing the session.\n");
hr = WinBioCloseSession(sessionHandle);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioCloseSession failed. hr = 0x%x\n", hr);
}
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function is the callback for WinBioRegisterEventMonitor.
// The function filters any event notice from the biometric subsystem and
// writes a result to the console window.
//
VOID CALLBACK EventMonitorCallback(
__in_opt PVOID EventCallbackContext,
__in HRESULT OperationStatus,
__in PWINBIO_EVENT Event
)
{
UNREFERENCED_PARAMETER(EventCallbackContext);
wprintf_s(L"\n EventMonitorCallback executing.");
// Failure.
if (FAILED(OperationStatus))
{
wprintf_s(L"\n EventMonitorCallback failed. ");
wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
goto e_Exit;
}
// An event notice was received.
if (Event != NULL)
{
wprintf_s(L"\n MonitorEvent: ");
switch (Event->Type)
{
case WINBIO_EVENT_FP_UNCLAIMED:
wprintf_s(L"WINBIO_EVENT_FP_UNCLAIMED");
wprintf_s(L"\n Unit ID: %d",
Event->Parameters.Unclaimed.UnitId);
wprintf_s(L"\n Reject detail: %d\n",
Event->Parameters.Unclaimed.RejectDetail);
break;
case WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY:
wprintf_s(L"WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY");
wprintf_s(L"\n Unit ID: %d",
Event->Parameters.UnclaimedIdentify.UnitId);
wprintf_s(L"\n Reject detail: %d\n",
Event->Parameters.UnclaimedIdentify.RejectDetail);
break;
case WINBIO_EVENT_ERROR:
wprintf_s(L"WINBIO_EVENT_ERROR\n");
break;
default:
wprintf_s(L"(0x%08x - Invalid type)\n", Event->Type);
break;
}
}
e_Exit:
if (Event != NULL)
{
//wprintf_s(L"\n Press any key to continue...\n");
WinBioFree(Event);
Event = NULL;
}
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 7 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 R2 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winbio.h (einschließlich Winbio.h) |
| Bibliothek | Winbio.lib |
| DLL | Winbio.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für