Función WinBioEnrollCommit (winbio.h)

  • Artículo

Finaliza una plantilla biométrica pendiente y la guarda en la base de datos asociada a la unidad biométrica usada para la inscripción. A partir de Windows 10, compilación 1607, esta función está disponible para su uso con una imagen móvil.

Sintaxis

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

Parámetros

[in] SessionHandle

Valor WINBIO_SESSION_HANDLE que identifica una sesión biométrica abierta. Abra un identificador de sesión sincrónico llamando a WinBioOpenSession. Abra un identificador de sesión asincrónico llamando a WinBioAsyncOpenSession.

[out, optional] Identity

Puntero a una estructura de WINBIO_IDENTITY que recibe el identificador (GUID o SID) de la plantilla.

[out, optional] IsNewTemplate

Puntero a un valor booleano que especifica si la plantilla que se va a agregar a la base de datos es nueva.

Valor devuelto

Si la función se realiza correctamente, devuelve S_OK. Si se produce un error en la función, devuelve un valor HRESULT que indica el error. Entre los valores posibles se incluyen los que se indican en la tabla siguiente, entre otros. Para obtener una lista de códigos de error comunes, consulte Valores HRESULT comunes.

Código devuelto Descripción
E_HANDLE
 El identificador de sesión no es válido.
E_POINTER
 Los punteros especificados por los parámetros Identity e IsNewTemplate no pueden ser NULL.
WINBIO_E_DATABASE_FULL
 No hay espacio disponible en la base de datos para la plantilla.
WINBIO_E_DUPLICATE_TEMPLATE
 La plantilla coincide con una ya guardada en la base de datos con una identidad o subfactor diferente (solo grupo de sistemas).
WINBIO_E_LOCK_VIOLATION
 La unidad biométrica está en uso y está bloqueada.

Comentarios

Si la plantilla pendiente es un duplicado de uno que ya existe en la base de datos, el parámetro Identity apuntará a la plantilla existente y el valor al que apunta el parámetro IsNewTemplate será FALSE.

Si la función WinBioEnrollCommit se realiza correctamente, el siguiente valor del Registro se establece en 0x01.

HKEY_LOCAL_MACHINE
   System
      CurrentControlSet
         Services
            WbioSrvc
               Parameters
                  EnrollmentCommitted
Nota El marco biométrico de Windows (WBF) nunca elimina este valor del Registro.
 
Para usar WinBioEnrollCommit de forma sincrónica, llame a la función con un identificador de sesión creado mediante una llamada a WinBioOpenSession. La función se bloquea hasta que se completa la operación o se produce un error.

Para usar WinBioEnrollCommit de forma asincrónica, llame a la función con un identificador de sesión creado mediante una llamada a WinBioAsyncOpenSession. El marco asigna una estructura de WINBIO_ASYNC_RESULT y la usa para devolver información sobre el éxito o el error de la operación. Si la operación se realiza correctamente, el marco devuelve WINBIO_IDENTITY información y una marca que indica si la plantilla es nueva en una estructura EnrollCommit anidada. Si la operación no se realiza correctamente, el marco devuelve información de error. La estructura WINBIO_ASYNC_RESULT se devuelve a la devolución de llamada de la aplicación o a la cola de mensajes de la aplicación, según el valor establecido en el parámetro NotificationMethod de la función WinBioAsyncOpenSession :

  • Si decide recibir avisos de finalización mediante una devolución de llamada, debe implementar una función de PWINBIO_ASYNC_COMPLETION_CALLBACK y establecer el parámetro NotificationMethod en WINBIO_ASYNC_NOTIFY_CALLBACK.
  • Si decide recibir notificaciones de finalización mediante la cola de mensajes de la aplicación, debe establecer el parámetro NotificationMethoden WINBIO_ASYNC_NOTIFY_MESSAGE. El marco devuelve un puntero WINBIO_ASYNC_RESULT al campo LPARAM del mensaje de ventana.
Para evitar pérdidas de memoria, debes llamar a WinBioFree para liberar la estructura WINBIO_ASYNC_RESULT después de haber terminado de usarlo.

Ejemplos

La siguiente función llama a WinBioEnrollCommit para confirmar una inscripción biométrica en el grupo del sistema. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:

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

Requisitos

Requisito Value
Cliente mínimo compatible Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado winbio.h (incluye Winbio.h)
Library Winbio.lib
Archivo DLL Winbio.dll

Consulte también

WinBioEnrollBegin

WinBioEnrollCapture

WinBioEnrollCaptureWithCallback

WinBioEnrollDiscard