WinBioLocateSensor-Funktion (winbio.h)

  • Artikel

Ruft die ID-Nummer einer biometrischen Einheit ab, die von einem Benutzer interaktiv ausgewählt wurde.

Syntax

HRESULT WinBioLocateSensor(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [out, optional] WINBIO_UNIT_ID        *UnitId
);

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] UnitId

Ein Zeiger auf einen ULONG-Wert , der die biometrische Einheit angibt.

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
 Der vom UnitId-Parameter angegebene Zeiger darf 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

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.

Aufrufe dieser Funktion mithilfe des Systempools werden blockiert, bis die Anwendung den Fensterfokus erhält und der Benutzer ein biometrisches Beispiel bereitgestellt hat. Wir empfehlen daher, dass Ihre Anwendung WinBioLocateSensor erst aufruft, wenn der Fokus erreicht wurde. 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 WinBioLocateSensor 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 WinBioLocateSensor 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. 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 WinBioLocateSensorWithCallback-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_LOCATE_SENSOR_CALLBACK-Funktion .

Beispiele

Die folgende Funktion ruft WinBioLocateSensor auf, um einen installierten biometrischen Sensor zu suchen. 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 LocateSensor( )
{
    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 WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate the sensor.
    wprintf_s(L"\n Tap the sensor once...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Sensor located successfully. ");
    wprintf_s(L"\n Unit ID = %d \n", unitId);

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

    wprintf_s(L"\n Hit 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

WinBioLocateSensorWithCallback