Fonction WinBioLocateSensor (winbio.h)

Article
08/27/2023

Récupère le numéro d’ID d’une unité biométrique sélectionnée de manière interactive par un utilisateur.

Syntaxe

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

Paramètres

[in] SessionHandle

Valeur WINBIO_SESSION_HANDLE qui identifie une session biométrique ouverte. Ouvrez un handle de session synchrone en appelant WinBioOpenSession. Ouvrez un handle de session asynchrone en appelant WinBioAsyncOpenSession.

[out, optional] UnitId

Pointeur vers une valeur ULONG qui spécifie l’unité biométrique.

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	Le pointeur spécifié par le paramètre UnitId ne peut pas être NULL.
WINBIO_E_ENROLLMENT_IN_PROGRESS	L’opération n’a pas pu être effectuée, car l’unité biométrique est actuellement utilisée pour une transaction d’inscription (pool système uniquement).

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.

Les appels à cette fonction à l’aide du pool système sont bloqués jusqu’à ce que l’application acquière le focus de fenêtre et que l’utilisateur ait fourni un exemple biométrique. Nous vous recommandons donc de ne pas appeler WinBioLocateSensor tant qu’elle n’a pas acquis le focus. 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.

Pour utiliser WinBioLocateSensor de manière synchrone, appelez la fonction avec un handle de session créé en appelant WinBioOpenSession. La fonction est bloquée jusqu’à ce que l’opération se termine ou qu’une erreur soit rencontrée.

Pour utiliser WinBioLocateSensor de manière asynchrone, appelez la fonction avec un handle de session créé en appelant WinBioAsyncOpenSession. L’infrastructure alloue une structure de WINBIO_ASYNC_RESULT et l’utilise pour retourner des informations sur la réussite ou l’échec de l’opération. La structure WINBIO_ASYNC_RESULT est retournée au rappel de l’application ou à la file d’attente des messages de l’application, en fonction de la valeur que vous définissez dans le paramètre NotificationMethod de la fonction WinBioAsyncOpenSession :

Si vous choisissez de recevoir des notifications d’achèvement à l’aide d’un rappel, vous devez implémenter une fonction PWINBIO_ASYNC_COMPLETION_CALLBACK et définir le paramètre NotificationMethod sur WINBIO_ASYNC_NOTIFY_CALLBACK.
Si vous choisissez de recevoir des notifications d’achèvement à l’aide de la file d’attente de messages d’application, vous devez définir le paramètre NotificationMethodsur WINBIO_ASYNC_NOTIFY_MESSAGE. L’infrastructure retourne un pointeur WINBIO_ASYNC_RESULT vers le champ LPARAM du message de fenêtre.

Pour éviter les fuites de mémoire, vous devez appeler WinBioFree pour libérer la structure WINBIO_ASYNC_RESULT une fois que vous avez terminé de l’utiliser.

Windows 7 : Vous pouvez effectuer cette opération de manière asynchrone à l’aide de la fonction WinBioLocateSensorWithCallback . La fonction vérifie les arguments d’entrée et retourne immédiatement. Si les arguments d’entrée ne sont pas valides, la fonction retourne un code d’erreur. Sinon, l’infrastructure démarre l’opération sur un autre thread. Lorsque l’opération asynchrone se termine ou rencontre une erreur, l’infrastructure envoie les résultats à la fonction PWINBIO_LOCATE_SENSOR_CALLBACK implémentée par votre application.

Exemples

La fonction suivante appelle WinBioLocateSensor pour localiser un capteur biométrique installé. 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 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;
}

Configuration requise


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

WinBioLocateSensorWithCallback

Partager via