PWINBIO_VERIFY_CALLBACK Rückruffunktion (winbio.h)

Artikel
03/03/2024

Wird vom Windows Biometric Framework aufgerufen, um Ergebnisse aus der asynchronen WinBioVerifyWithCallback-Funktion zurückzugeben. Die Clientanwendung muss diese Funktion implementieren.

Wichtig Es wird empfohlen, ab Windows 8 die kombination PWINBIO_VERIFY_CALLBACK/WinBioVerifyWithCallback nicht mehr zu verwenden. Führen Sie stattdessen die folgenden Schritte aus:

Implementieren Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion , um eine Benachrichtigung zu erhalten, wenn der Vorgang abgeschlossen ist.
Rufen Sie die WinBioAsyncOpenSession-Funktion auf. Übergeben Sie die Adresse Ihres Rückrufs im CallbackRoutine-Parameter . Übergeben Sie WINBIO_ASYNC_NOTIFY_CALLBACK im NotificationMethod-Parameter . Ruft ein asynchrones Sitzungshandle ab.
Verwenden Sie das asynchrone Sitzungshandle, um WinBioVerify aufzurufen. Wenn der Vorgang abgeschlossen ist, ordnet und initialisiert das Windows Biometric Framework eine WINBIO_ASYNC_RESULT-Struktur mit den Ergebnissen und ruft den 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

PWINBIO_VERIFY_CALLBACK PwinbioVerifyCallback;

void PwinbioVerifyCallback(
  [in, optional] PVOID VerifyCallbackContext,
  [in]           HRESULT OperationStatus,
  [in]           WINBIO_UNIT_ID UnitId,
  [in]           BOOLEAN Match,
  [in]           WINBIO_REJECT_DETAIL RejectDetail
)
{...}

Parameter

[in, optional] VerifyCallbackContext

Zeiger auf einen Puffer, der von der Anwendung definiert und an den VerifyCallbackContext-Parameter der WinBioVerifyWithCallback-Funktion übergeben wird. Der Puffer wird vom Framework oder der biometrischen Einheit nicht geändert. Ihre Anwendung kann die Daten verwenden, um zu bestimmen, welche Aktionen ausgeführt werden sollen, oder um zusätzliche Informationen zur biometrischen Erfassung beizubehalten.

[in] OperationStatus

Fehlercode, der vom Erfassungsvorgang zurückgegeben wird.

[in] UnitId

Nummer der biometrischen Einheit.

[in] Match

Ein boolescher Wert, der angibt, ob das erfasste Beispiel mit der vom Identity-Parameter angegebenen Benutzeridentität übereinstimmt.

[in] RejectDetail

Zusätzliche Informationen zum Fehler beim Ausführen des Vorgangs, falls vorhanden. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

Keine

Bemerkungen

Derzeit unterstützt das Windows Biometric Framework nur Fingerabdruckleser. Wenn ein Vorgang fehlschlägt und zusätzliche Informationen in einer WINBIO_REJECT_DETAIL -Konstanten zurückgibt, handelt es sich daher um einen der folgenden Werte:

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

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 Winbio.lib-Bibliothek, und schließen 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

Freigeben über