Fonction WinBioEnrollCommit (winbio.h)

Article
08/27/2023

Finalise un modèle biométrique en attente et l’enregistre dans la base de données associée à l’unité biométrique utilisée pour l’inscription. À compter de Windows 10 build 1607, cette fonction peut être utilisée avec une image mobile.

Syntaxe

HRESULT WinBioEnrollCommit(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [out, optional] WINBIO_IDENTITY       *Identity,
  [out, optional] BOOLEAN               *IsNewTemplate
);

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

Pointeur vers une structure WINBIO_IDENTITY qui reçoit l’identificateur (GUID ou SID) du modèle.

[out, optional] IsNewTemplate

Pointeur vers une valeur booléenne qui spécifie si le modèle ajouté à la base de données est nouveau.

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	Les pointeurs spécifiés par les paramètres Identity et IsNewTemplate ne peuvent pas être NULL.
WINBIO_E_DATABASE_FULL	Il n’y a pas d’espace disponible dans la base de données pour le modèle.
WINBIO_E_DUPLICATE_TEMPLATE	Le modèle correspond à un modèle déjà enregistré dans la base de données avec une identité ou un sous-facteur différent (pool système uniquement).
WINBIO_E_LOCK_VIOLATION	L’unité biométrique est en cours d’utilisation et est verrouillée.

Remarques

Si le modèle en attente est un doublon de celui qui existe déjà dans la base de données, le paramètre Identity pointe vers le modèle existant et la valeur pointée par le paramètre IsNewTemplate est FALSE.

Si la fonction WinBioEnrollCommit réussit, la valeur de Registre suivante est définie sur 0x01.

HKEY_LOCAL_MACHINE
   System
      CurrentControlSet
         Services
            WbioSrvc
               Parameters
                  EnrollmentCommitted

Note Cette valeur de Registre n’est jamais supprimée par le Framework biométrique Windows (WBF).

Pour utiliser WinBioEnrollCommit 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 WinBioEnrollCommit 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. Si l’opération réussit, l’infrastructure retourne WINBIO_IDENTITY informations et un indicateur indiquant si le modèle est nouveau dans une structure EnrollCommit imbriquée. Si l’opération échoue, l’infrastructure retourne les informations d’erreur. 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.

Exemples

La fonction suivante appelle WinBioEnrollCommit pour valider une inscription biométrique dans le pool système. 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 EnrollSysPool(
                      BOOL discardEnrollment, 
                      WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    BOOLEAN isNewTemplate = TRUE;

    // 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. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate a sensor.
    wprintf_s(L"\n Swipe your finger on the sensor...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Begin the enrollment sequence. 
    wprintf_s(L"\n Starting enrollment sequence...\n");
    hr = WinBioEnrollBegin(
            sessionHandle,      // Handle to open biometric session
            subFactor,          // Finger to create template for
            unitId              // Biometric unit ID
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnrollBegin failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture enrollment information by swiping the sensor with
    // the finger identified by the subFactor argument in the 
    // WinBioEnrollBegin function.
    for (int swipeCount = 1;; ++swipeCount)
    {
        wprintf_s(L"\n Swipe the sensor to capture %s sample.",
                 (swipeCount == 1)?L"the first":L"another");

        hr = WinBioEnrollCapture(
                sessionHandle,  // Handle to open biometric session
                &rejectDetail   // [out] Failure information
                );

        wprintf_s(L"\n Sample %d captured from unit number %d.", 
                  swipeCount, 
                  unitId);

        if (hr == WINBIO_I_MORE_DATA)
        {
            wprintf_s(L"\n    More data required.\n");
            continue;
        }
        if (FAILED(hr))
        {
            if (hr == WINBIO_E_BAD_CAPTURE)
            {
                wprintf_s(L"\n  Error: Bad capture; reason: %d", 
                          rejectDetail);
                continue;
            }
            else
            {
                wprintf_s(L"\n WinBioEnrollCapture failed. hr = 0x%x", hr);
                goto e_Exit;
            }
        }
        else
        {
            wprintf_s(L"\n    Template completed.\n");
            break;
        }
    }

    // Discard the enrollment if the appropriate flag is set.
    // Commit the enrollment if it is not discarded.
    if (discardEnrollment == TRUE)
    {
        wprintf_s(L"\n Discarding enrollment...\n\n");
        hr = WinBioEnrollDiscard( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;    
    }
    else
    {
        wprintf_s(L"\n Committing enrollment...\n");
        hr = WinBioEnrollCommit( 
                sessionHandle,      // Handle to open biometric session
                &identity,          // WINBIO_IDENTITY object for the user
                &isNewTemplate);    // Is this a new template

        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioEnrollCommit failed. hr = 0x%x\n", hr);
            goto e_Exit;
        }
    }


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

    wprintf_s(L" Press any key to continue...");
    _getch();

    return hr;
}

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