WinBioIdentify-Funktion (winbio.h)

Erfasst eine biometrische Stichprobe und bestimmt, ob sie mit einer vorhandenen biometrischen Vorlage übereinstimmt. Ab Windows 10, Build 1607, ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar.

Syntax

HRESULT WinBioIdentify(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [out, optional] WINBIO_UNIT_ID           *UnitId,
  [out, optional] WINBIO_IDENTITY          *Identity,
  [out, optional] WINBIO_BIOMETRIC_SUBTYPE *SubFactor,
  [out, optional] WINBIO_REJECT_DETAIL     *RejectDetail
);

Die Parameter

[in] SessionHandle

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

[out, optional] UnitId

Ein Zeiger auf einen ULONG-Wert , der die biometrische Einheit angibt, die zum Ausführen der Identifizierung verwendet wird.

[out, optional] Identity

Zeiger auf eine WINBIO_IDENTITY Struktur, die die GUID oder SID des Benutzers empfängt, der die biometrische Stichprobe bereitstellt.

[out, optional] SubFactor

Zeigen Sie auf einen WINBIO_BIOMETRIC_SUBTYPE Wert, der den teilbezogenen Faktor erhält, der der biometrischen Stichprobe zugeordnet ist. Weitere Informationen finden Sie im Abschnitt "Hinweise".

[out, optional] RejectDetail

Ein Zeiger auf einen ULONG-Wert , der ggf. zusätzliche Informationen zum Fehler enthält, um ein biometrisches Beispiel zu erfassen. Wenn die Aufnahme erfolgreich war, wird dieser Parameter auf Null festgelegt. Die folgenden Werte sind 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ögliche Werte sind die Werte in der folgenden Tabelle, sind jedoch nicht beschränkt. Eine Liste allgemeiner Fehlercodes finden Sie unter "Allgemeine HRESULT-Werte".

Bemerkungen

Der im Parameter SubFactor zurückgegebene Wert gibt den Teilfaktor an, der der biometrischen Stichprobe zugeordnet ist. Das Windows Biometric Framework (WBF) unterstützt derzeit nur die Fingerabdruckerfassung und verwendet die folgenden Konstanten, um Untertypinformationen darzustellen.

• WINBIO_ANSI_381_POS_RH_THUMB
• WINBIO_ANSI_381_POS_RH_INDEX_FINGER
• WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
• WINBIO_ANSI_381_POS_RH_RING_FINGER
• WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
• WINBIO_ANSI_381_POS_LH_THUMB
• WINBIO_ANSI_381_POS_LH_INDEX_FINGER
• WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
• WINBIO_ANSI_381_POS_LH_RING_FINGER
• WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
• WINBIO_ANSI_381_POS_RH_FOUR_FINGERS
• WINBIO_ANSI_381_POS_LH_FOUR_FINGERS

Um WinBioIdentify asynchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioAsyncOpenSession erstellt wurde. Das Framework weist eine WINBIO_ASYNC_RESULT Struktur zu und verwendet es, um Informationen zum Erfolg oder Fehler des Vorgangs zurückzugeben. Wenn der Vorgang erfolgreich ist, gibt das Framework WINBIO_IDENTITY und WINBIO_BIOMETRIC_SUBTYPE Informationen in einer geschachtelten Identifizierungsstruktur zurück. Wenn der Vorgang nicht erfolgreich ist, gibt das Framework WINBIO_REJECT_DETAIL Informationen in der "Identifizieren" -Struktur zurück. Die WINBIO_ASYNC_RESULT Struktur wird an den Anwendungsrückruf oder an die Anwendungsnachrichtenwarteschlange zurückgegeben, abhängig vom Wert, den Sie im Parameter NotificationMethod der WinBioAsyncOpenSession-Funktion festgelegt haben:

• Wenn Sie sich für den Empfang von Abschlussbenachrichtigungen mithilfe eines Rückrufs entscheiden, müssen Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion implementieren und den Parameter NotificationMethod auf WINBIO_ASYNC_NOTIFY_CALLBACK festlegen.
• Wenn Sie mithilfe der Anwendungsnachrichtenwarteschlange Abschlussbenachrichtigungen empfangen möchten, müssen Sie den Parameter NotificationMethod auf WINBIO_ASYNC_NOTIFY_MESSAGE festlegen. Das Framework gibt einen WINBIO_ASYNC_RESULT Zeiger auf das LPARAM-Feld der Fenstermeldung zurück.

Windows 7: Sie können diesen Vorgang asynchron mithilfe der WinBioIdentifyWithCallback-Funktion 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 Der Anwendung implementierte PWINBIO_IDENTIFY_CALLBACK Funktion.

Examples

Die folgende Funktion ruft WinBioEnumEnrollments auf, um die für eine Vorlage registrierten biometrischen Unterfaktoren aufgezählt zu werden, und winBioIdentify wird aufgerufen, um ein WINBIO_IDENTITY-Objekt abzurufen, das den Benutzer identifiziert. Verknüpfen Sie die statische Winbio.lib-Bibliothek, und fügen Sie die folgenden Headerdateien ein:

• Windows.h
• Stdio.h
• Conio.h
• Winbio.h

HRESULT EnumEnrollments( )
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    PWINBIO_BIOMETRIC_SUBTYPE subFactorArray = NULL;
    WINBIO_BIOMETRIC_SUBTYPE SubFactor = 0;
    SIZE_T subFactorCount = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_BIOMETRIC_SUBTYPE subFactor = WINBIO_SUBTYPE_NO_INFORMATION;

    // 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;
    }

    // Locate the biometric sensor and retrieve a WINBIO_IDENTITY object.
    wprintf_s(L"\n Calling WinBioIdentify - Swipe finger on sensor...\n");
    hr = WinBioIdentify( 
            sessionHandle,              // Session handle
            &unitId,                    // Biometric unit ID
            &identity,                  // User SID
            &subFactor,                 // Finger sub factor
            &rejectDetail               // Rejection information
            );
    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_UNKNOWN_ID)
        {
            wprintf_s(L"\n Unknown identity.\n");
        }
        else if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    // Retrieve the biometric sub-factors for the template.
    hr = WinBioEnumEnrollments( 
            sessionHandle,              // Session handle
            unitId,                     // Biometric unit ID
            &identity,                  // Template ID
            &subFactorArray,            // Subfactors
            &subFactorCount             // Count of subfactors
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnumEnrollments failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Print the sub-factor(s) to the console.
    wprintf_s(L"\n Enrollments for this user on Unit ID %d:", unitId);
    for (SIZE_T index = 0; index < subFactorCount; ++index)
    {
        SubFactor = subFactorArray[index];
        switch (SubFactor)
        {
            case WINBIO_ANSI_381_POS_RH_THUMB:
                wprintf_s(L"\n   RH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_RH_INDEX_FINGER:
                wprintf_s(L"\n   RH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER:
                wprintf_s(L"\n   RH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_RING_FINGER:
                wprintf_s(L"\n   RH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_LITTLE_FINGER:
                wprintf_s(L"\n   RH little finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_THUMB:
                wprintf_s(L"\n   LH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_LH_INDEX_FINGER:
                wprintf_s(L"\n   LH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER:
                wprintf_s(L"\n   LH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_RING_FINGER:
                wprintf_s(L"\n   LH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_LITTLE_FINGER:
                wprintf_s(L"\n   LH little finger\n");
                break;
            default:
                wprintf_s(L"\n   The sub-factor is not correct\n");
                break;
        }
 
    }

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

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

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

    return hr;
}

Anforderungen

Siehe auch

WinBioIdentifyWithCallback