WinBioVerify-Funktion (winbio.h)

Erfasst eine biometrische Stichprobe und bestimmt, ob das Beispiel 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
);

Die Parameter

[in] SessionHandle

Ein WINBIO_SESSION_HANDLE Wert, der eine geöffnete 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 ausgeführt hat.

[out, optional] Match

Zeigen Sie 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 Aufnahme erfolgreich war, wird dieser Parameter auf Null festgelegt. Die folgenden Werte sind 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ö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

Wenn die Erfassung der biometrischen Stichprobe fehlschlägt, enthält der UnitId-Parameter die Einheitennummer des Sensors, der versucht hat, die Aufnahme 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. Daher wird empfohlen, dass Ihre Anwendung WinBioVerify erst aufruft, wenn sie den Fokus erworben hat. Die Art und Weise, wie Sie den Fokus erwerben, 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 dieses Handle an die SetForegroundWindow-Funktion zu übergeben, um das Konsolenfenster in den Vordergrund zu erzwingen und ihm den Fokus zuzuweisen. Wenn Ihre Anwendung in einem getrennten Prozess ausgeführt wird und kein Fenster 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 wurde. Die Funktion blockiert, bis der Vorgang abgeschlossen ist oder ein Fehler aufgetreten ist.

Um WinBioVerify asynchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioAsyncOpenSession erstellt wurde. Das Framework weist eine WINBIO_ASYNC_RESULT Struktur zu und verwendet es, um Informationen zum Erfolg oder Fehler des Vorgangs 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 an die Anwendungsnachrichtenwarteschlange zurückgegeben, abhängig vom Wert, den Sie im Parameter NotificationMethod der WinBioAsyncOpenSession-Funktion festgelegt haben:

• Wenn Sie sich für den Empfang von Abschlussbenachrichtigungen mithilfe eines Rückrufs entscheiden, müssen Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion implementieren und den Parameter NotificationMethod auf WINBIO_ASYNC_NOTIFY_CALLBACK festlegen.
• Wenn Sie mithilfe der Anwendungsnachrichtenwarteschlange Abschlussbenachrichtigungen empfangen möchten, müssen Sie den Parameter NotificationMethod 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 asynchron ausführen, indem Sie die WinBioVerifyWithCallback-Funktion verwenden. 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 Der Anwendung implementierte PWINBIO_VERIFY_CALLBACK-Funktion .

Examples

Mit der folgenden Funktion wird WinBioVerify aufgerufen , um festzustellen, ob ein biometrisches Beispiel mit der angemeldeten Identität des aktuellen Benutzers übereinstimmt. Die Hilfsfunktion "GetCurrentUserIdentity" ist ebenfalls enthalten. Verknüpfen Sie die statische Winbio.lib-Bibliothek, und fügen 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

Siehe auch

WinBioVerifyWithCallback