WinBioCaptureSample-Funktion (winbio.h)

Artikel
08/27/2023

Erfasst eine biometrische Probe und füllt einen biometrischen Datensatz (BIR) mit den Rohdaten oder verarbeiteten Daten.

Syntax

HRESULT WinBioCaptureSample(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_BIR_PURPOSE    Purpose,
  [in]            WINBIO_BIR_DATA_FLAGS Flags,
  [out, optional] WINBIO_UNIT_ID        *UnitId,
                  PWINBIO_BIR           *Sample,
  [out, optional] SIZE_T                *SampleSize,
  [out, optional] WINBIO_REJECT_DETAIL  *RejectDetail
);

Parameter

[in] SessionHandle

Ein WINBIO_SESSION_HANDLE Wert, der eine offene biometrische Sitzung identifiziert. Öffnen Sie ein synchrones Sitzungshandle, indem Sie WinBioOpenSession aufrufen. Öffnen Sie ein asynchrones Sitzungshandle, indem Sie WinBioAsyncOpenSession aufrufen.

[in] Purpose

Eine WINBIO_BIR_PURPOSE Bitmaske, die die beabsichtigte Verwendung des Beispiels angibt. Dies kann ein bitweises 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 bitweises OR der folgenden Flags auf 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 das WINBIO_DATA_FLAG_INTEGRITY-Flag 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 die Stichprobe genau so zurück, wie sie vom Sensor erfasst wurde.

WINBIO_DATA_FLAG_INTERMEDIATE

Gibt 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.

[out, optional] UnitId

Ein Zeiger auf einen WINBIO_UNIT_ID Wert, der die ID der biometrischen Einheit enthält, die die Stichprobe generiert hat.

Sample

Adresse einer Variablen, die einen Zeiger auf eine WINBIO_BIR Struktur empfängt, die das Beispiel enthält. Wenn Sie die Verwendung der -Struktur abgeschlossen haben, müssen Sie den Zeiger an WinBioFree übergeben, um den für das Beispiel zugewiesenen Arbeitsspeicher freizugeben.

[out, optional] SampleSize

Ein Zeiger auf einen SIZE_T Wert, der die Größe der im Sample-Parameter zurückgegebenen WINBIO_BIR-Struktur in Bytes enthält.

[out, optional] RejectDetail

Ein Zeiger auf einen WINBIO_REJECT_DETAIL Wert, der zusätzliche Informationen über den Fehler beim Erfassen einer biometrischen Stichprobe enthält. Wenn die Erfassung erfolgreich war, wird dieser Parameter auf 0 (null) festgelegt. Die folgenden Werte werden 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ö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 zum Erfassen von Rohbeispielen, oder die Sitzung wurde nicht mit dem flag WINBIO_FLAG_RAW 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, Sample, 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.
WINBIO_E_INVALID_OPERATION	Der Vorgang konnte nicht abgeschlossen werden, da im Sensorpool ein sicherer Sensor vorhanden ist.

Hinweise

Um diese Funktion erfolgreich aufzurufen, müssen Sie das Sitzungshandle öffnen, indem Sie WINBIO_FLAG_RAW im Flags-Parameter der WinBioOpenSession - oder WinBioAsyncOpenSession-Funktionen angeben. Derzeit verfügen nur Anwendungen, die unter den Konten "Administratoren" und "Lokales System" ausgeführt werden, über die erforderlichen Berechtigungen.

Gültige Kombinationen der Parameter Purpose und Flags hängen von den Funktionen der verwendeten biometrischen Einheit ab. Lesen Sie die Sensordokumentation des Herstellers, um zu ermitteln, welche Kombinationen aus gültigen Zweck - und Flagwerten unterstützt werden und wie sie sich auf die erfassten Daten auswirken. Nachdem Sie mit der Verwendung des Beispiels fertig sind, muss Ihre Anwendung WinBioFree aufrufen, um den von der WinBioCaptureSample-Funktion dafür zugewiesenen Arbeitsspeicher freizugeben.

Um WinBioCaptureSample synchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioOpenSession erstellt wird. Die Funktion blockiert, bis eine Stichprobe erfasst wurde oder ein Fehler auftritt. Aufrufe von WinBioCaptureSample mithilfe des Systempools werden blockiert, bis die aufrufende Anwendung den Fensterfokus hat und der Benutzer ein Beispiel für einen der Sensoren im Pool bereitstellt. Wenn der vom Benutzer ausgewählte Sensor bereits für eine Registrierungstransaktion verwendet wird, schlägt die Funktion fehl und gibt WINBIO_E_ENROLLMENT_IN_PROGRESS zurück.

Um WinBioCaptureSample asynchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioAsyncOpenSession erstellt wird. Das Framework ordnet eine WINBIO_ASYNC_RESULT-Struktur zu und verwendet sie, um Informationen über erfolgreiche oder fehlgeschlagene Vorgänge zurückzugeben. Wenn der Erfassungsvorgang erfolgreich ist, gibt das Framework Informationen zum Beispiel in einer geschachtelten CaptureSample-Struktur zurück. Wenn der Vorgang nicht erfolgreich ist, gibt das Framework Fehlerinformationen zurück. Die WINBIO_ASYNC_RESULT-Struktur wird an den Anwendungsrückruf oder die Anwendungsnachrichtenwarteschlange zurückgegeben, je nachdem, welche Werte Sie im NotificationMethod-Parameter der WinBioAsyncOpenSession-Funktion festgelegt haben:

Wenn Sie Vervollständigungsbenachrichtigungen mithilfe eines Rückrufs erhalten möchten, müssen Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion implementieren und den NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_CALLBACK festlegen.
Wenn Sie Vervollständigungsbenachrichtigungen mithilfe der Anwendungsnachrichtenwarteschlange empfangen möchten, müssen Sie den NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_MESSAGE festlegen. Das Framework gibt einen WINBIO_ASYNC_RESULT Zeiger auf das LPARAM-Feld der Fenstermeldung zurück.

Um Speicherverluste zu verhindern, müssen Sie WinBioFree aufrufen, um die WINBIO_ASYNC_RESULT-Struktur freizugeben, nachdem Sie sie verwendet haben.

Windows 7: Sie können diesen Vorgang asynchron ausführen, indem Sie die WinBioCaptureSampleWithCallback-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 Ihrer Anwendung implementierte PWINBIO_CAPTURE_CALLBACK-Funktion .

Beispiele

Die folgende Funktion ruft WinBioCaptureSample auf, um eine biometrische Stichprobe von einem Benutzer zu erfassen. 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 CaptureSample()
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    PWINBIO_BIR sample = NULL;
    SIZE_T sampleSize = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Access: Capture raw data
            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.
    wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
    hr = WinBioCaptureSample(
            sessionHandle,
            WINBIO_NO_PURPOSE_AVAILABLE,
            WINBIO_DATA_FLAG_RAW,
            &unitId,
            &sample,
            &sampleSize,
            &rejectDetail
            );
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    wprintf_s(L"\n Captured %d bytes.\n", sampleSize);


e_Exit:
    if (sample != NULL)
    {
        WinBioFree(sample);
        sample = NULL;
    }

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

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;
}

Anforderungen


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 (winbio.h einschließen)
Bibliothek	Winbio.lib
DLL	Winbio.dll

Weitere Informationen

WinBioCaptureSampleWithCallback

Share via