WinBioVerify-Funktion (winbio.h)
Erfasst eine biometrische Stichprobe und bestimmt, ob die Probe der angegebenen Benutzeridentität entspricht. Ab Windows 10 Build 1607 ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar.
Syntax
HRESULT WinBioVerify(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_IDENTITY *Identity,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[out, optional] WINBIO_UNIT_ID *UnitId,
[out, optional] BOOLEAN *Match,
[out, optional] WINBIO_REJECT_DETAIL *RejectDetail
);
Parameter
[in] SessionHandle
Ein WINBIO_SESSION_HANDLE Wert, der eine offene biometrische Sitzung identifiziert. Öffnen Sie ein synchrones Sitzungshandle, indem Sie WinBioOpenSession aufrufen. Öffnen Sie ein asynchrones Sitzungshandle, indem Sie WinBioAsyncOpenSession aufrufen.
[in] Identity
Zeiger auf eine WINBIO_IDENTITY Struktur, die die GUID oder SID des Benutzers enthält, der die biometrische Stichprobe bereitstellt.
[in] SubFactor
Ein WINBIO_BIOMETRIC_SUBTYPE Wert, der den Teilfaktor angibt, der der biometrischen Stichprobe zugeordnet ist. Das Windows Biometric Framework (WBF) unterstützt derzeit nur die Fingerabdruckerfassung und kann die folgenden Konstanten verwenden, um Untertypinformationen darzustellen.
- WINBIO_ANSI_381_POS_RH_THUMB
- WINBIO_ANSI_381_POS_RH_INDEX_FINGER
- WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_RH_RING_FINGER
- WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_LH_THUMB
- WINBIO_ANSI_381_POS_LH_INDEX_FINGER
- WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_LH_RING_FINGER
- WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_RH_FOUR_FINGERS
- WINBIO_ANSI_381_POS_LH_FOUR_FINGERS
- WINBIO_SUBTYPE_ANY
[out, optional] UnitId
Ein Zeiger auf einen WINBIO_UNIT_ID Wert, der die biometrische Einheit angibt, die die Überprüfung durchgeführt hat.
[out, optional] Match
Zeiger auf einen booleschen Wert, der angibt, ob das erfasste Beispiel mit der vom Identity-Parameter angegebenen Benutzeridentität übereinstimmt.
[out, optional] RejectDetail
Ein Zeiger auf einen ULONG-Wert , der zusätzliche Informationen zum Fehler beim Erfassen einer biometrischen Stichprobe enthält. Wenn die Erfassung erfolgreich war, wird dieser Parameter auf 0 (null) festgelegt. Die folgenden Werte werden für die Fingerabdruckerfassung definiert:
- WINBIO_FP_TOO_HIGH
- WINBIO_FP_TOO_LOW
- WINBIO_FP_TOO_LEFT
- WINBIO_FP_TOO_RIGHT
- WINBIO_FP_TOO_FAST
- WINBIO_FP_TOO_SLOW
- WINBIO_FP_POOR_QUALITY
- WINBIO_FP_TOO_SKEWED
- WINBIO_FP_TOO_SHORT
- WINBIO_FP_MERGE_FAILURE
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 |
|---|---|
|
Das Sitzungshandle ist ungültig. |
|
Das Argument SubFactor ist falsch. |
|
Der durch die Parameter UnitId, Identity, SubFactor oder RejectDetail angegebene Zeiger darf nicht NULL sein. |
|
Die biometrische Stichprobe konnte nicht erfasst werden. Verwenden Sie den RejectDetail-Wert für weitere Informationen. |
|
Der Vorgang konnte nicht abgeschlossen werden, da die angegebene biometrische Einheit derzeit für eine Registrierungstransaktion (nur Systempool) verwendet wird. |
|
Das biometrische Beispiel entspricht nicht der angegebenen Kombination aus Identität und Subfactor . |
Hinweise
Wenn die Erfassung der biometrischen Stichprobe fehlschlägt, enthält der UnitId-Parameter die Einheitennummer des Sensors, der versucht hat, die Erfassung durchzuführen.
Aufrufe dieser Funktion mithilfe des Systempools werden blockiert, bis die Anwendung den Fensterfokus erhält und der Benutzer ein biometrisches Beispiel bereitgestellt hat. Wir empfehlen daher, dass Ihre Anwendung WinBioVerify erst aufruft, wenn sie den Fokus erlangt hat. Die Art und Weise, wie Sie den Fokus erhalten, hängt von der Art der Anwendung ab, die Sie schreiben. Wenn Sie beispielsweise eine GUI-Anwendung erstellen, können Sie einen Nachrichtenhandler implementieren, der eine WM_ACTIVATE, WM_SETFOCUS oder eine andere geeignete Nachricht erfasst. Wenn Sie eine CUI-Anwendung schreiben, rufen Sie GetConsoleWindow auf, um ein Handle an das Konsolenfenster abzurufen, und übergeben Sie dieses Handle an die SetForegroundWindow-Funktion , um das Konsolenfenster im Vordergrund zu erzwingen und ihm den Fokus zuzuweisen. Wenn Ihre Anwendung in einem getrennten Prozess ausgeführt wird und kein Fenster aufweist oder ein Windows-Dienst ist, verwenden Sie WinBioAcquireFocus und WinBioReleaseFocus , um den Fokus manuell zu steuern.
Um WinBioVerify synchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioOpenSession erstellt wird. Die Funktion wird blockiert, bis der Vorgang abgeschlossen ist oder ein Fehler auftritt.
Um WinBioVerify asynchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioAsyncOpenSession erstellt wird. Das Framework ordnet eine WINBIO_ASYNC_RESULT-Struktur zu und verwendet sie, um Informationen über erfolgreiche oder fehlgeschlagene Vorgänge zurückzugeben. Wenn der Vorgang erfolgreich ist, gibt das Framework einen BOOLESCHEN Übereinstimmungswert in einer geschachtelten Verify-Struktur zurück. Wenn der Vorgang nicht erfolgreich ist, gibt das Framework WINBIO_REJECT_DETAIL Informationen in der Verify-Struktur zurück. Die WINBIO_ASYNC_RESULT-Struktur wird an den Anwendungsrückruf oder die Anwendungsnachrichtenwarteschlange zurückgegeben, je nachdem, welche Werte Sie im NotificationMethod-Parameter der WinBioAsyncOpenSession-Funktion festgelegt haben:
- Wenn Sie Vervollständigungsbenachrichtigungen mithilfe eines Rückrufs erhalten möchten, müssen Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion implementieren und den NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_CALLBACK festlegen.
- Wenn Sie Vervollständigungsbenachrichtigungen mithilfe der Anwendungsnachrichtenwarteschlange empfangen möchten, müssen Sie den NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_MESSAGE festlegen. Das Framework gibt einen WINBIO_ASYNC_RESULT Zeiger auf das LPARAM-Feld der Fenstermeldung zurück.
Windows 7: Sie können diesen Vorgang mithilfe der WinBioVerifyWithCallback-Funktion asynchron ausführen. Die Funktion überprüft die Eingabeargumente und gibt sofort zurück. Wenn die Eingabeargumente ungültig sind, gibt die Funktion einen Fehlercode zurück. Andernfalls startet das Framework den Vorgang in einem anderen Thread. Wenn der asynchrone Vorgang abgeschlossen ist oder ein Fehler auftritt, sendet das Framework die Ergebnisse an die von Ihrer Anwendung implementierte PWINBIO_VERIFY_CALLBACK-Funktion .
Beispiele
Die folgende Funktion ruft WinBioVerify auf, um festzustellen, ob eine biometrische Stichprobe mit der angemeldeten Identität des aktuellen Benutzers übereinstimmt. Die Hilfsfunktion GetCurrentUserIdentity ist ebenfalls enthalten. Verknüpfen Sie die statische Winbio.lib-Bibliothek, und schließen Sie die folgenden Headerdateien ein:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT Verify(WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
WINBIO_IDENTITY identity = {0};
BOOLEAN match = FALSE;
// Find the identity of the user.
hr = GetCurrentUserIdentity( &identity );
if (FAILED(hr))
{
wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
goto e_Exit;
}
// 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;
}
// Verify a biometric sample.
wprintf_s(L"\n Calling WinBioVerify - Swipe finger on sensor...\n");
hr = WinBioVerify(
sessionHandle,
&identity,
subFactor,
&unitId,
&match,
&rejectDetail
);
wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
if (FAILED(hr))
{
if (hr == WINBIO_E_NO_MATCH)
{
wprintf_s(L"\n- NO MATCH - identity verification failed.\n");
}
else if (hr == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n- Bad capture; reason: %d\n", rejectDetail);
}
else
{
wprintf_s(L"\n WinBioVerify failed. hr = 0x%x\n", hr);
}
goto e_Exit;
}
wprintf_s(L"\n Fingerprint verified:\n", unitId);
e_Exit:
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function retrieves the identity of the current user.
// This is a helper function and is not part of the Windows Biometric
// Framework API.
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
// Declare variables.
HRESULT hr = S_OK;
HANDLE tokenHandle = NULL;
DWORD bytesReturned = 0;
struct{
TOKEN_USER tokenUser;
BYTE buffer[SECURITY_MAX_SID_SIZE];
} tokenInfoBuffer;
// Zero the input identity and specify the type.
ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
Identity->Type = WINBIO_ID_TYPE_NULL;
// Open the access token associated with the
// current process
if (!OpenProcessToken(
GetCurrentProcess(), // Process handle
TOKEN_READ, // Read access only
&tokenHandle)) // Access token handle
{
DWORD win32Status = GetLastError();
wprintf_s(L"Cannot open token handle: %d\n", win32Status);
hr = HRESULT_FROM_WIN32(win32Status);
goto e_Exit;
}
// Zero the tokenInfoBuffer structure.
ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));
// Retrieve information about the access token. In this case,
// retrieve a SID.
if (!GetTokenInformation(
tokenHandle, // Access token handle
TokenUser, // User for the token
&tokenInfoBuffer.tokenUser, // Buffer to fill
sizeof(tokenInfoBuffer), // Size of the buffer
&bytesReturned)) // Size needed
{
DWORD win32Status = GetLastError();
wprintf_s(L"Cannot query token information: %d\n", win32Status);
hr = HRESULT_FROM_WIN32(win32Status);
goto e_Exit;
}
// Copy the SID from the tokenInfoBuffer structure to the
// WINBIO_IDENTITY structure.
CopySid(
SECURITY_MAX_SID_SIZE,
Identity->Value.AccountSid.Data,
tokenInfoBuffer.tokenUser.User.Sid
);
// Specify the size of the SID and assign WINBIO_ID_TYPE_SID
// to the type member of the WINBIO_IDENTITY structure.
Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
Identity->Type = WINBIO_ID_TYPE_SID;
e_Exit:
if (tokenHandle != NULL)
{
CloseHandle(tokenHandle);
}
return hr;
}
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 (winbio.h einschließen) |
| Bibliothek | Winbio.lib |
| DLL | Winbio.dll |