Freigeben über


WinBioVerifyWithCallback-Funktion (winbio.h)

Erfasst asynchron eine biometrische Stichprobe und bestimmt, ob die Stichprobe der angegebenen Benutzeridentität entspricht. Die Funktion kehrt sofort an den Aufrufer zurück, führt die Erfassung und Überprüfung für einen separaten Thread aus und ruft eine anwendungsdefinierte Rückruffunktion auf, um den Vorgang status zu aktualisieren.

Wichtig  

Es wird empfohlen, ab Windows 8 diese Funktion nicht mehr zum Starten eines asynchronen Vorgangs zu verwenden. Gehen Sie stattdessen wie folgt vor:

  • Implementieren Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion , um Benachrichtigungen zu erhalten, wenn der Vorgang abgeschlossen ist.
  • Rufen Sie die WinBioAsyncOpenSession-Funktion auf. Übergeben Sie die Adresse Ihres Rückrufs im Parameter CallbackRoutine . Übergeben Sie WINBIO_ASYNC_NOTIFY_CALLBACK im NotificationMethod-Parameter . Rufen Sie ein asynchrones Sitzungshandle ab.
  • Verwenden Sie das asynchrone Sitzungshandle, um WinBioVerify aufzurufen. Nach Abschluss des Vorgangs ordnet und initialisiert das Biometrische Windows-Framework eine WINBIO_ASYNC_RESULT-Struktur mit den Ergebnissen und ruft Ihren Rückruf mit einem Zeiger auf die Ergebnisstruktur auf.
  • Rufen Sie WinBioFree aus Ihrer Rückrufimplementierung auf, um die WINBIO_ASYNC_RESULT-Struktur freizugeben, nachdem Sie sie verwendet haben.
 

Syntax

HRESULT WinBioVerifyWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_IDENTITY          *Identity,
  [in]           WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in]           PWINBIO_VERIFY_CALLBACK  VerifyCallback,
  [in, optional] PVOID                    VerifyCallbackContext
);

Parameter

[in] SessionHandle

Ein WINBIO_SESSION_HANDLE Wert, der eine offene biometrische Sitzung identifiziert.

[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. Weitere Details finden Sie im Abschnitt „Anmerkungen“.

[in] VerifyCallback

Adresse einer Rückruffunktion, die von der WinBioVerifyWithCallback-Funktion aufgerufen wird, wenn die Überprüfung erfolgreich ist oder fehlschlägt. Sie müssen den Rückruf erstellen.

[in, optional] VerifyCallbackContext

Eine optionale anwendungsdefinierte Struktur, die im VerifyCallbackContext-Parameter der Rückruffunktion zurückgegeben wird. Diese Struktur kann alle Daten enthalten, die von der benutzerdefinierten Rückruffunktion verarbeitet werden sollen.

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_HANDLE
Das Sitzungshandle ist ungültig.
E_INVALIDARG
Das SubFactor-Argument ist falsch.
E_POINTER
Der durch die Parameter Identity und VerifyCallback angegebene Zeiger darf nicht NULL sein.

Hinweise

Der SubFactor-Parameter gibt den Teilfaktor an, der der biometrischen Stichprobe zugeordnet ist. Das Windows Biometric Framework (WBF) unterstützt derzeit nur die Fingerabdruckerfassung und verwendet die folgenden Konstanten, 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
Die Rückrufroutine wird im Kontext eines beliebigen Threads im aufrufenden Prozess ausgeführt. Der Aufrufer ist für die Synchronisierung des Zugriffs auf jeden Arbeitsspeicher verantwortlich, der zwischen dem Rückruf und anderen Teilen der Anwendung freigegeben werden kann.

Die WinBioVerifyWithCallback-Funktion gibt sofort zurück und übergibt S_OK an den Aufrufer. Um die status des Erfassungs- und Überprüfungsprozesses zu ermitteln, müssen Sie den Parameter OperationStatus in Ihrer Rückruffunktion untersuchen.

Sie können die WinBioCancel-Funktion aufrufen, um einen ausstehenden Rückrufvorgang abzubrechen. Das Schließen einer Sitzung bricht auch implizit Rückrufe für diese Sitzung ab.

Die Rückrufroutine muss die folgende Signatur aufweisen:


VOID CALLBACK VerifyCallback(
__in_opt PVOID VerifyCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in BOOLEAN Match,
__in WINBIO_REJECT_DETAIL RejectDetail
);

Beispiele

Die folgende Funktion ruft WinBioVerifyWithCallback auf, um asynchron zu bestimmen, ob ein biometrisches Beispiel mit der angemeldeten Identität des aktuellen Benutzers übereinstimmt. Die Rückrufroutine VerifyCallback und die Hilfsfunktion GetCurrentUserIdentity sind ebenfalls enthalten. 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 VerifyWithCallback(BOOL bCancel, WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_IDENTITY identity = {0};

    // 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 asynchronously.
    wprintf_s(L"\n Calling WinBioVerifyWithCallback.\n");
    hr = WinBioVerifyWithCallback(
            sessionHandle,              // Open session handle
            &identity,                  // User SID or GUID
            subFactor,                  // Sample sub-factor
            VerifyCallback,             // Callback function
            NULL                        // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioVerifyWithCallback failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\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 the asynchronous identification process to complete 
    // or be canceled.
    hr = WinBioWait( sessionHandle );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
    }

e_Exit:
    if (sessionHandle != NULL)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Hit any key to continue...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioVerifyWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
// 
VOID CALLBACK VerifyCallback(
  __in_opt PVOID VerifyCallbackContext,
  __in HRESULT OperationStatus,
  __in WINBIO_UNIT_ID UnitId,
  __in BOOLEAN Match,
  __in WINBIO_REJECT_DETAIL RejectDetail
  )
{
    UNREFERENCED_PARAMETER(VerifyCallbackContext);
    UNREFERENCED_PARAMETER(Match);

    wprintf_s(L"\n VerifyCallback executing");
    wprintf_s(L"\n Swipe processed for unit ID %d\n", UnitId);

    // The identity could not be verified.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n Verification failed for the following reason:");
        if (OperationStatus == WINBIO_E_NO_MATCH)
        {
            wprintf_s(L"\n No match.\n");
        }
        else if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture.\n ");
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
        }
        else
        {
            wprintf_s(L"VerifyCallback failed.");
            wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus); 
        }
        goto e_Exit;
    }

    // The user identity was verified.
    wprintf_s(L"\n Fingerprint verified:\n");

e_Exit:
    return;
}

//------------------------------------------------------------------------
// 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

Anforderung Wert
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

WinBioCancel

WinBioVerify