Funzione WinBioLocateSensorWithCallback (winbio.h)

Articolo
08/27/2023

Recupera in modo asincrono il numero ID dell'unità biometrica selezionata in modo interattivo da un utente. La funzione restituisce immediatamente al chiamante, elabora in un thread separato e segnala l'unità biometrica selezionata chiamando una funzione di callback definita dall'applicazione.

Importante

È consigliabile, a partire da Windows 8, non usare più questa funzione per avviare un'operazione asincrona. Eseguire invece le operazioni seguenti:

Implementare una funzione PWINBIO_ASYNC_COMPLETION_CALLBACK per ricevere un avviso al termine dell'operazione.
Chiamare la funzione WinBioAsyncOpenSession . Passare l'indirizzo del callback nel parametro CallbackRoutine . Passare WINBIO_ASYNC_NOTIFY_CALLBACK nel parametro NotificationMethod . Recuperare un handle di sessione asincrono.
Usare l'handle di sessione asincrona per chiamare WinBioLocateSensor. Al termine dell'operazione, Windows Biometric Framework alloca e inizializza una struttura WINBIO_ASYNC_RESULT con i risultati e richiama il callback con un puntatore alla struttura dei risultati.
Chiamare WinBioFree dall'implementazione del callback per rilasciare la struttura di WINBIO_ASYNC_RESULT al termine dell'uso.

Sintassi

HRESULT WinBioLocateSensorWithCallback(
  [in]           WINBIO_SESSION_HANDLE          SessionHandle,
  [in]           PWINBIO_LOCATE_SENSOR_CALLBACK LocateCallback,
  [in, optional] PVOID                          LocateCallbackContext
);

Parametri

[in] SessionHandle

Valore WINBIO_SESSION_HANDLE che identifica una sessione biometrica aperta.

[in] LocateCallback

Indirizzo di una funzione di callback che verrà chiamata dalla funzione WinBioLocateSensorWithCallback quando la posizione del sensore ha esito positivo o ha esito negativo. È necessario creare il callback.

[in, optional] LocateCallbackContext

Indirizzo di una struttura di dati definita dall'applicazione passata alla funzione di callback nel parametro LocateCallbackContext . Questa struttura può contenere tutti i dati che la funzione di callback personalizzata è progettata per gestire.

Valore restituito

Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, restituisce un valore HRESULT che indica l'errore. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente. Per un elenco di codici di errore comuni, vedere Valori HRESULT comuni.

Codice restituito	Descrizione
E_HANDLE	L'handle di sessione non è valido.
E_POINTER	L'indirizzo specificato dal parametro LocateCallback non può essere NULL.

Commenti

È possibile usare questa funzione nei sistemi con più sensori per determinare quale sensore è preferito per la registrazione dall'utente. Nessuna informazione di identificazione viene restituita da questa funzione. Viene fornito solo per indicare la selezione del sensore utente.

Se il parametro SessionHandle fa riferimento al pool di sensori di sistema, la funzione di callback non verrà chiamata finché l'applicazione acquisisce lo stato attivo della finestra e l'utente ha fornito un campione biometrico. Il modo in cui si acquisisce lo stato attivo dipende dal tipo di applicazione che si scrive. Ad esempio, se si sta creando un'applicazione GUI, è possibile implementare un gestore messaggi che acquisisce un WM_ACTIVATE, WM_SETFOCUS o un altro messaggio appropriato. Se si scrive un'applicazione CUI, chiamare GetConsoleWindow per recuperare un handle nella finestra della console e passare tale handle alla funzione SetForegroundWindow per forzare la finestra della console in primo piano e assegnarla lo stato attivo. Se l'applicazione è in esecuzione in un processo scollegato e non ha una finestra o è un servizio Windows, usare WinBioAcquireFocus e WinBioReleaseFocus per controllare manualmente lo stato attivo.

La routine di callback deve avere la firma seguente:


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

Esempio

La funzione seguente chiama WinBioLocateSensorWithCallback per individuare il sensore biometrico. WinBioLocateSensorWithCallback è una funzione asincrona che configura il sottosistema biometrico per individuare il sensore in un altro thread. L'output del sottosistema biometrico viene inviato a una funzione di callback personalizzata denominata LocateSensorCallback. Collegare alla libreria statica Winbio.lib e includere i file di intestazione seguenti:

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbio.h (include Winbio.h)
Libreria	Winbio.lib
DLL	Winbio.dll

Vedi anche

WinBioLocateSensor

Condividi tramite