WinBioEnrollCapture-Funktion (winbio.h)

Artikel
08/27/2023

Erfasst ein biometrisches Beispiel und fügt es einer Vorlage hinzu. Ab Windows 10 Build 1607 ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar.

Syntax

HRESULT WinBioEnrollCapture(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [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.

[out, optional] RejectDetail

Ein Zeiger auf einen ULONG-Wert , der zusätzliche Informationen enthält, wenn eine biometrische Stichprobe nicht erfasst werden kann. 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	Das Anrufkonto ist nicht berechtigt, die Registrierung durchzuführen.
E_HANDLE	Das Sitzungshandle ist ungültig.
E_POINTER	Der durch den RejectDetail-Parameter angegebene Zeiger darf nicht NULL sein.
WINBIO_E_BAD_CAPTURE	Das Beispiel konnte nicht erfasst werden. Verwenden Sie den RejectDetail-Wert für weitere Informationen.
WINBIO_E_LOCK_VIOLATION	Die biometrische Einheit wird verwendet und gesperrt.
WINBIO_I_MORE_DATA	Die übereinstimmende Engine erfordert ein oder mehrere zusätzliche Beispiele, um eine zuverlässige Vorlage zu generieren. Sie sollten die Anweisungen für den Benutzer aktualisieren, um weitere Beispiele zu übermitteln und WinBioEnrollCapture erneut aufzurufen.

Hinweise

Jede Anwendung, die sich mit einer biometrischen Einheit im Systempool registriert, muss beim Aufrufen von WinBioEnrollBegin den Fensterfokus haben. Andernfalls wird der Aufruf blockiert, bis die Anwendung den Fensterfokus erhält und der Benutzer ein biometrisches Beispiel bereitgestellt hat. Wir empfehlen daher, dass Ihre Anwendung WinBioEnrollBegin erst aufruft, wenn sie den Fokus erlangt hat. Die Art und Weise, wie Sie den Fokus erhalten, hängt von der Art der Anwendung ab, die Sie schreiben. Wenn Sie beispielsweise eine GUI-Anwendung erstellen, können Sie einen Nachrichtenhandler implementieren, der eine WM_ACTIVATE, WM_SETFOCUS oder eine andere geeignete Nachricht erfasst. Wenn Sie eine CUI-Anwendung schreiben, rufen Sie GetConsoleWindow auf, um ein Handle an das Konsolenfenster abzurufen, und übergeben Sie dieses Handle an die SetForegroundWindow-Funktion , um das Konsolenfenster im Vordergrund zu erzwingen und ihm den Fokus zuzuweisen. Wenn Ihre Anwendung in einem getrennten Prozess ausgeführt wird und kein Fenster aufweist oder ein Windows-Dienst ist, verwenden Sie WinBioAcquireFocus und WinBioReleaseFocus , um den Fokus manuell zu steuern.

Um WinBioEnrollCapture synchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioOpenSession erstellt wird. Die Funktion wird blockiert, bis der Vorgang abgeschlossen ist oder ein Fehler auftritt.

Um WinBioEnrollCapture 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 Vorgang nicht erfolgreich ist, gibt das Framework WINBIO_REJECT_DETAIL Informationen in einer geschachtelten EnrollCapture-Struktur 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 aus Ihrer Rückrufimplementierung aufrufen, um die WINBIO_ASYNC_RESULT-Struktur freizugeben, nachdem Sie sie verwendet haben.

Windows 7: Sie können diesen Vorgang mithilfe der WinBioEnrollCaptureWithCallback-Funktion asynchron ausführen. 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_ENROLL_CAPTURE_CALLBACK-Funktion .

Beispiele

Die folgende Funktion registriert eine biometrische Vorlage im Systempool, indem WinBioEnrollCapture aufgerufen wird. 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 EnrollSysPool(
                      BOOL discardEnrollment, 
                      WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    BOOLEAN isNewTemplate = TRUE;

    // 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. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate a sensor.
    wprintf_s(L"\n Swipe your finger on the sensor...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Begin the enrollment sequence. 
    wprintf_s(L"\n Starting enrollment sequence...\n");
    hr = WinBioEnrollBegin(
            sessionHandle,      // Handle to open biometric session
            subFactor,          // Finger to create template for
            unitId              // Biometric unit ID
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnrollBegin failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture enrollment information by swiping the sensor with
    // the finger identified by the subFactor argument in the 
    // WinBioEnrollBegin function.
    for (int swipeCount = 1;; ++swipeCount)
    {
        wprintf_s(L"\n Swipe the sensor to capture %s sample.",
                 (swipeCount == 1)?L"the first":L"another");

        hr = WinBioEnrollCapture(
                sessionHandle,  // Handle to open biometric session
                &rejectDetail   // [out] Failure information
                );

        wprintf_s(L"\n Sample %d captured from unit number %d.", 
                  swipeCount, 
                  unitId);

        if (hr == WINBIO_I_MORE_DATA)
        {
            wprintf_s(L"\n    More data required.\n");
            continue;
        }
        if (FAILED(hr))
        {
            if (hr == WINBIO_E_BAD_CAPTURE)
            {
                wprintf_s(L"\n  Error: Bad capture; reason: %d", 
                          rejectDetail);
                continue;
            }
            else
            {
                wprintf_s(L"\n WinBioEnrollCapture failed. hr = 0x%x", hr);
                goto e_Exit;
            }
        }
        else
        {
            wprintf_s(L"\n    Template completed.\n");
            break;
        }
    }

    // Discard the enrollment if the appropriate flag is set.
    // Commit the enrollment if it is not discarded.
    if (discardEnrollment == TRUE)
    {
        wprintf_s(L"\n Discarding enrollment...\n\n");
        hr = WinBioEnrollDiscard( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;    
    }
    else
    {
        wprintf_s(L"\n Committing enrollment...\n");
        hr = WinBioEnrollCommit( 
                sessionHandle,      // Handle to open biometric session
                &identity,          // WINBIO_IDENTITY object for the user
                &isNewTemplate);    // Is this a new template

        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioEnrollCommit failed. hr = 0x%x\n", hr);
            goto e_Exit;
        }
    }


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

    wprintf_s(L" Press any key to continue...");
    _getch();

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