Fonction WinBioLocateSensorWithCallback (winbio.h)

Article
08/27/2023

Récupère de manière asynchrone le numéro d’ID de l’unité biométrique sélectionnée de manière interactive par un utilisateur. La fonction retourne immédiatement à l’appelant, traite sur un thread distinct et signale l’unité biométrique sélectionnée en appelant une fonction de rappel définie par l’application.

Important

Nous vous recommandons, à compter de Windows 8, de ne plus utiliser cette fonction pour démarrer une opération asynchrone. Au lieu de cela, procédez comme suit :

Implémentez une fonction PWINBIO_ASYNC_COMPLETION_CALLBACK pour recevoir une notification à la fin de l’opération.
Appelez la fonction WinBioAsyncOpenSession . Transmettez l’adresse de votre rappel dans le paramètre CallbackRoutine . Passez WINBIO_ASYNC_NOTIFY_CALLBACK dans le paramètre NotificationMethod . Récupérer un handle de session asynchrone.
Utilisez le handle de session asynchrone pour appeler WinBioLocateSensor. Une fois l’opération terminée, l’infrastructure biométrique Windows alloue et initialise une structure WINBIO_ASYNC_RESULT avec les résultats et appelle votre rappel avec un pointeur vers la structure des résultats.
Appelez WinBioFree à partir de votre implémentation de rappel pour libérer la structure WINBIO_ASYNC_RESULT une fois que vous avez terminé de l’utiliser.

Syntaxe

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

Paramètres

[in] SessionHandle

Valeur WINBIO_SESSION_HANDLE qui identifie une session biométrique ouverte.

[in] LocateCallback

Adresse d’une fonction de rappel qui sera appelée par la fonction WinBioLocateSensorWithCallback lorsque l’emplacement du capteur réussit ou échoue. Vous devez créer le rappel.

[in, optional] LocateCallbackContext

Adresse d’une structure de données définie par l’application qui est passée à la fonction de rappel dans son paramètre LocateCallbackContext . Cette structure peut contenir toutes les données que la fonction de rappel personnalisée est conçue pour gérer.

Valeur retournée

Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle retourne une valeur HRESULT qui indique l’erreur. Les valeurs possibles sont notamment celles figurant dans le tableau suivant. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

Code de retour	Description
E_HANDLE	Le handle de session n’est pas valide.
E_POINTER	L’adresse spécifiée par le paramètre LocateCallback ne peut pas être NULL.

Remarques

Vous pouvez utiliser cette fonction sur les systèmes avec plusieurs capteurs pour déterminer le capteur préféré pour l’inscription par l’utilisateur. Aucune information d’identification n’est retournée par cette fonction. Il est fourni uniquement pour indiquer la sélection du capteur utilisateur.

Si le paramètre SessionHandle fait référence au pool de capteurs système, la fonction de rappel n’est pas appelée tant que l’application n’aura pas acquis le focus de la fenêtre et que l’utilisateur n’aura pas fourni un exemple biométrique. La façon dont vous acquérez le focus dépend du type d’application que vous écrivez. Par exemple, si vous créez une application GUI, vous pouvez implémenter un gestionnaire de messages qui capture un WM_ACTIVATE, un WM_SETFOCUS ou un autre message approprié. Si vous écrivez une application CUI, appelez GetConsoleWindow pour récupérer un handle dans la fenêtre de console et passer ce handle à la fonction SetForegroundWindow pour forcer la fenêtre de console au premier plan et lui attribuer le focus. Si votre application s’exécute dans un processus détaché et n’a pas de fenêtre ou s’il s’agit d’un service Windows, utilisez WinBioAcquireFocus et WinBioReleaseFocus pour contrôler manuellement le focus.

La routine de rappel doit avoir la signature suivante :


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

Exemples

La fonction suivante appelle WinBioLocateSensorWithCallback pour localiser le capteur biométrique. WinBioLocateSensorWithCallback est une fonction asynchrone qui configure le sous-système biométrique pour localiser le capteur sur un autre thread. La sortie du sous-système biométrique est envoyée à une fonction de rappel personnalisée nommée LocateSensorCallback. Créez un lien vers la bibliothèque statique Winbio.lib et incluez les fichiers d’en-tête suivants :

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbio.h (inclure Winbio.h)
Bibliothèque	Winbio.lib
DLL	Winbio.dll

Voir aussi

WinBioLocateSensor

Partager via