WinBioLocateSensorWithCallback-Funktion (winbio.h)

Artikel
08/27/2023

Ruft asynchron die ID-Nummer der biometrischen Einheit ab, die von einem Benutzer interaktiv ausgewählt wurde. Die Funktion kehrt sofort an den Aufrufer zurück, verarbeitet in einem separaten Thread und meldet die ausgewählte biometrische Einheit, indem sie eine anwendungsdefinierte Rückruffunktion aufruft.

Wichtig

Es wird empfohlen, diese Funktion ab Windows 8 nicht mehr zum Starten eines asynchronen Vorgangs zu verwenden. Führen Sie stattdessen die folgenden Schritte aus:

Implementieren Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion , um eine Benachrichtigung zu erhalten, wenn der Vorgang abgeschlossen ist.
Rufen Sie die WinBioAsyncOpenSession-Funktion auf. Übergeben Sie die Adresse Ihres Rückrufs im CallbackRoutine-Parameter . Übergeben Sie WINBIO_ASYNC_NOTIFY_CALLBACK im NotificationMethod-Parameter . Ruft ein asynchrones Sitzungshandle ab.
Verwenden Sie das asynchrone Sitzungshandle, um WinBioLocateSensor aufzurufen. Wenn der Vorgang abgeschlossen ist, ordnet und initialisiert das Windows Biometric Framework eine WINBIO_ASYNC_RESULT-Struktur mit den Ergebnissen und ruft den 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 WinBioLocateSensorWithCallback(
  [in]           WINBIO_SESSION_HANDLE          SessionHandle,
  [in]           PWINBIO_LOCATE_SENSOR_CALLBACK LocateCallback,
  [in, optional] PVOID                          LocateCallbackContext
);

Parameter

[in] SessionHandle

Ein WINBIO_SESSION_HANDLE Wert, der eine offene biometrische Sitzung identifiziert.

[in] LocateCallback

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

[in, optional] LocateCallbackContext

Adresse einer anwendungsdefinierten Datenstruktur, die im LocateCallbackContext-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, 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_HANDLE	Das Sitzungshandle ist ungültig.
E_POINTER	Die vom LocateCallback-Parameter angegebene Adresse darf nicht NULL sein.

Hinweise

Sie können diese Funktion auf Systemen mit mehreren Sensoren verwenden, um zu bestimmen, welcher Sensor für die Registrierung durch den Benutzer bevorzugt wird. Diese Funktion gibt keine Identifikationsinformationen zurück. Sie wird nur bereitgestellt, um die Auswahl des Benutzersensors anzugeben.

Wenn der SessionHandle-Parameter auf den Systemsensorpool verweist, wird die Rückruffunktion erst aufgerufen, wenn die Anwendung den Fensterfokus erhält und der Benutzer ein biometrisches Beispiel bereitgestellt 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.

Die Rückrufroutine muss über die folgende Signatur verfügen:


VOID CALLBACK LocateCallback(
__in_opt PVOID LocateCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId
);

Beispiele

Die folgende Funktion ruft WinBioLocateSensorWithCallback auf, um einen biometrischen Sensor zu finden. WinBioLocateSensorWithCallback ist eine asynchrone Funktion, die das biometrische Subsystem so konfiguriert, dass der Sensor in einem anderen Thread gesucht wird. Die Ausgabe des biometrischen Subsystems wird an eine benutzerdefinierte Rückruffunktion namens LocateSensorCallback gesendet. 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 LocateSensorWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;

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

    wprintf_s(L"\n Calling WinBioLocateSensorWithCallback.");
    hr = WinBioLocateSensorWithCallback(
                sessionHandle,          // Open biometric session
                LocateSensorCallback,   // Callback function
                NULL                    // Optional context
                );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensorWithCallback failed.");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the identification if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...\n");
        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 identification 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)
    {
       wprintf_s(L"\n Closing the session.\n");

        hr = WinBioCloseSession(sessionHandle);
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCloseSession failed. hr = 0x%x\n", hr);
        }
        sessionHandle = NULL;
    }

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

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for 
// WinBioLocateSensorWithCallback. The function filters the response 
// from the biometric subsystem and writes a result to the console window.
// 
VOID CALLBACK LocateSensorCallback(
    __in_opt PVOID LocateCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId
    )
{
    UNREFERENCED_PARAMETER(LocateCallbackContext);

    wprintf_s(L"\n LocateSensorCallback executing.");

    // A sensor could not be located.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n LocateSensorCallback failed.");
        wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
    }
    // A sensor was located.
    else
    {
        wprintf_s(L"\n Selected unit ID: %d\n", UnitId);
    }
}

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

Weitere Informationen

WinBioLocateSensor

Freigeben über