Fonction WinBioLocateSensor (winbio.h)

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 incluent, mais ne sont pas limitées à celles du tableau suivant. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

Remarques

Vous pouvez utiliser cette fonction sur les systèmes avec plusieurs capteurs pour déterminer quel capteur est 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 bloquent jusqu’à ce que l’application acquiert 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 obtenez 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 affecter le focus. Si votre application s’exécute dans un processus détaché et n’a pas de fenêtre ou qu’elle est un service Windows, utilisez WinBioAcquireFocus et WinBioReleaseFocus pour contrôler manuellement le focus.

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

Pour utiliser WinBioLocateSensor de façon asynchrone, appelez la fonction avec un handle de session créé en appelant WinBioAsyncOpenSession. L’infrastructure alloue une structure 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 d’application ou à la file d’attente des messages de l’application, selon la valeur que vous avez définie 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 des messages d’application, vous devez définir le paramètre NotificationMethod sur WINBIO_ASYNC_NOTIFY_MESSAGE. L’infrastructure retourne un pointeur WINBIO_ASYNC_RESULT vers le champ LPARAM du message de fenêtre.

Windows 7 : Vous pouvez effectuer cette opération de façon 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.

Examples

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

Spécifications

Voir aussi

WinBioLocateSensorWithCallback