WinBioCaptureSampleWithCallback-Funktion (winbio.h)

  • Artikel

Erfasst eine biometrische Stichprobe asynchron und gibt die rohen oder verarbeiteten Daten in einem biometrischen Informationsdatensatz (BIR) zurück. Die Funktion kehrt sofort an den Aufrufer zurück, erfasst das Beispiel in einem separaten Thread 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 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

HRESULT WinBioCaptureSampleWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_BIR_PURPOSE       Purpose,
  [in]           WINBIO_BIR_DATA_FLAGS    Flags,
  [in]           PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  [in, optional] PVOID                    CaptureCallbackContext
);

Parameter

[in] SessionHandle

Ein WINBIO_SESSION_HANDLE Wert, der eine offene biometrische Sitzung identifiziert.

[in] Purpose

Eine WINBIO_BIR_PURPOSE Bitmaske, die die beabsichtigte Verwendung des Beispiels angibt. Dies kann ein bitweiser OR der folgenden Werte sein:

  • WINBIO_PURPOSE_VERIFY
  • WINBIO_PURPOSE_IDENTIFY
  • WINBIO_PURPOSE_ENROLL
  • WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
  • WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

Ein Wert, der den Verarbeitungstyp angibt, der auf das erfasste Beispiel angewendet werden soll. Dies kann ein bitweiser OR der folgenden Flags für Sicherheits- und Verarbeitungsebene sein:

  • WINBIO_DATA_FLAG_PRIVACY

Verschlüsseln Sie das Beispiel.

  • WINBIO_DATA_FLAG_INTEGRITY

Signieren Sie das Beispiel, oder schützen Sie es mithilfe eines Nachrichtenauthentifizierungscodes (MAC).

  • WINBIO_DATA_FLAG_SIGNED

Wenn dieses Flag und die WINBIO_DATA_FLAG_INTEGRITYflag festgelegt sind, signieren Sie das Beispiel. Wenn dieses Flag nicht festgelegt ist, aber das WINBIO_DATA_FLAG_INTEGRITY-Flag festgelegt ist, berechnen Sie einen MAC.

  • WINBIO_DATA_FLAG_RAW

Geben Sie das Beispiel genau so zurück, wie es vom Sensor erfasst wurde.

  • WINBIO_DATA_FLAG_INTERMEDIATE

Geben Sie das Beispiel zurück, nachdem es bereinigt und gefiltert wurde.

  • WINBIO_DATA_FLAG_PROCESSED

Gibt das Beispiel zurück, nachdem es für den vom Purpose-Parameter angegebenen Zweck verwendet werden kann.

[in] CaptureCallback

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

[in, optional] CaptureCallbackContext

Adresse einer anwendungsdefinierten Datenstruktur, die im CaptureCallbackContext-Parameter an die Rückruffunktion übergeben 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_ACCESSDENIED
 Der Aufrufer verfügt nicht über die Berechtigung, Rohbeispiele zu erfassen, oder die Sitzung wurde nicht mit dem WINBIO_FLAG_RAW-Flag geöffnet.
E_HANDLE
 Das Sitzungshandle ist ungültig.
E_NOTIMPL
 Die biometrische Einheit unterstützt den angeforderten Vorgang nicht.
E_POINTER
 Die Zeiger UnitId, SampleSize und RejectDetail dürfen nicht NULL sein.
WINBIO_E_ENROLLMENT_IN_PROGRESS
 Der Vorgang konnte nicht abgeschlossen werden, da die biometrische Einheit derzeit für eine Registrierungstransaktion (nur Systempool) verwendet wird.

Hinweise

Die WinBioCaptureSampleWithCallback-Funktion erfasst Beispiele asynchron. Um diese Funktion erfolgreich aufzurufen, muss das Sitzungshandle durch Angabe WINBIO_FLAG_RAW geöffnet worden sein. Nur die Administratoren- und lokalen Systemkonten verfügen über die erforderlichen Berechtigungen.

Gültige Kombinationen der Parameter Purpose und Flags hängen von den Funktionen der verwendeten biometrischen Einheit ab. In der Dokumentation zum Herstellersensor erfahren Sie, welche Kombinationen unterstützt werden und wie sie sich auf die erfassten Daten auswirken.

Aufrufer sind dafür verantwortlich, die vomSample-Parameter zurückgegebene WINBIO_BIR-Struktur freizugeben.

Die Rückrufroutine muss die folgende Signatur aufweisen:

VOID CALLBACK CaptureCallback(
__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
);

Beispiele

Im folgenden Codebeispiel wird ein Beispiel asynchron erfasst, indem WinBioCaptureSampleWithCallback aufgerufen und ein Zeiger an eine benutzerdefinierte Rückruffunktion übergeben wird. Die Rückruffunktion CaptureSampleCallback wird ebenfalls angezeigt. 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 (einschließlich Winbio.h)
Bibliothek Winbio.lib
DLL Winbio.dll

Weitere Informationen

WinBioCaptureSample