PWINBIO_CAPTURE_CALLBACK Rückruffunktion (winbio.h)

Artikel
03/03/2024

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

Wichtig Es wird empfohlen, ab Windows 8 die Kombination PWINBIO_CAPTURE_CALLBACK/WinBioCaptureSampleWithCallback nicht mehr 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 WinBioCaptureSample 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

PWINBIO_CAPTURE_CALLBACK PwinbioCaptureCallback;

void PwinbioCaptureCallback(
  [in, optional] PVOID CaptureCallbackContext,
  [in]           HRESULT OperationStatus,
  [in]           WINBIO_UNIT_ID UnitId,
  [in]           PWINBIO_BIR Sample,
  [in]           SIZE_T SampleSize,
  [in]           WINBIO_REJECT_DETAIL RejectDetail
)
{...}

Parameter

[in, optional] CaptureCallbackContext

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

[in] OperationStatus

Fehlercode, der vom Erfassungsvorgang zurückgegeben wird.

[in] UnitId

Biometrische Einheits-ID-Nummer.

[in] Sample

Zeiger auf die Beispieldaten.

[in] SampleSize

Größe der Beispieldaten in Bytes, auf die der Sample-Parameter verweist.

[in] RejectDetail

Zusätzliche Informationen zum Fehler, falls vorhanden, für die Ausführung des Vorgangs. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

Keine

Bemerkungen

Derzeit unterstützt das Windows Biometric Framework nur Fingerabdruckleser. Wenn ein Vorgang also fehlschlägt und zusätzliche Informationen in einer WINBIO_REJECT_DETAIL Konstanten zurückgibt, handelt es sich 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

Im folgenden Codebeispiel wird ein Beispiel asynchron erfasst, indem WinBioCaptureSampleWithCallback aufgerufen und ein Zeiger an die benutzerdefinierte Rückruffunktion CaptureSampleCallback übergeben wird. 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 CaptureSampleWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Raw access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample asynchronously.
    wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
    hr = WinBioCaptureSampleWithCallback(
            sessionHandle,                  // Open session handle
            WINBIO_NO_PURPOSE_AVAILABLE,    // Intended use of the sample
            WINBIO_DATA_FLAG_RAW,           // Sample format
            CaptureSampleCallback,          // Callback function
            NULL                            // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the capture process if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...");
        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 capture 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 Press any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
    __in_opt PVOID CaptureCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in_bcount(SampleSize) PWINBIO_BIR Sample,
    __in SIZE_T SampleSize,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(CaptureCallbackContext);

    wprintf_s(L"\n CaptureSampleCallback executing");
    wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);

    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
         }
        else
        {
            wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
            wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Captured %d bytes.\n", SampleSize);

e_Exit:

    if (Sample != NULL)
    {
        WinBioFree(Sample);
        Sample = NULL;
    }
}

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

Weitere Informationen

WINBIO_REJECT_DETAIL Konstanten

WinBioCaptureSampleWithCallback

Share via