Función WinBioEnrollCapture (winbio.h)

Artículo
08/27/2023

Captura un ejemplo biométrico y lo agrega a una plantilla. A partir de Windows 10, compilación 1607, esta función está disponible para su uso con una imagen móvil.

Sintaxis

HRESULT WinBioEnrollCapture(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [out, optional] WINBIO_REJECT_DETAIL  *RejectDetail
);

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

Puntero a un valor de ULONG que contiene información adicional que no se puede capturar una muestra biométrica. Si la captura se realizó correctamente, este parámetro se establece en cero. Los siguientes valores se definen para la captura de huellas digitales:

WINBIO_FP_TOO_HIGH
WINBIO_FP_TOO_LOW
WINBIO_FP_TOO_LEFT
WINBIO_FP_TOO_RIGHT
WINBIO_FP_TOO_FAST
WINBIO_FP_TOO_SLOW
WINBIO_FP_POOR_QUALITY
WINBIO_FP_TOO_SKEWED
WINBIO_FP_TOO_SHORT
WINBIO_FP_MERGE_FAILURE

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_ACCESSDENIED	No se permite que la cuenta de llamada realice la inscripción.
E_HANDLE	El identificador de sesión no es válido.
E_POINTER	El puntero especificado por el parámetro RejectDetail no puede ser NULL.
WINBIO_E_BAD_CAPTURE	No se pudo capturar el ejemplo. Use el valor RejectDetail para obtener más información.
WINBIO_E_LOCK_VIOLATION	La unidad biométrica está en uso y está bloqueada.
WINBIO_I_MORE_DATA	El motor coincidente requiere uno o varios ejemplos adicionales para generar una plantilla confiable. Debe actualizar las instrucciones al usuario para enviar más ejemplos y llamar a WinBioEnrollCapture de nuevo.

Comentarios

Cualquier aplicación que se inscriba mediante una unidad biométrica en el grupo de sistemas debe tener el foco de ventana cuando llama a WinBioEnrollBegin. Si no es así, la llamada se bloquea hasta que la aplicación adquiere el foco de la ventana y el usuario ha proporcionado una muestra biométrica. Por lo tanto, se recomienda que la aplicación no llame a WinBioEnrollBegin hasta que haya adquirido el foco. La manera en que adquiere el foco depende del tipo de aplicación que está escribiendo. Por ejemplo, si va a crear una aplicación de GUI, puede implementar un controlador de mensajes que capture un WM_ACTIVATE, WM_SETFOCUS u otro mensaje adecuado. Si va a escribir una aplicación CUI, llame a GetConsoleWindow para recuperar un identificador en la ventana de la consola y pase ese identificador a la función SetForegroundWindow para forzar la ventana de consola en primer plano y asignarle el foco. Si la aplicación se ejecuta en un proceso desasociado y no tiene ninguna ventana o es un servicio de Windows, use WinBioAcquireFocus y WinBioReleaseFocus para controlar manualmente el foco.

Para usar WinBioEnrollCapture 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 WinBioEnrollCapture 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 no se realiza correctamente, el marco devuelve WINBIO_REJECT_DETAIL información en una estructura EnrollCapture anidada. 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, debe llamar a WinBioFree desde la implementación de devolución de llamada para liberar la estructura de WINBIO_ASYNC_RESULT una vez que haya terminado de usarlo.

Windows 7: Puede realizar esta operación de forma asincrónica mediante la función WinBioEnrollCaptureWithCallback . La función comprueba los argumentos de entrada y devuelve inmediatamente. Si los argumentos de entrada no son válidos, la función devuelve un código de error. De lo contrario, el marco inicia la operación en otro subproceso. Cuando la operación asincrónica se completa o encuentra un error, el marco envía los resultados a la función PWINBIO_ENROLL_CAPTURE_CALLBACK implementada por la aplicación.

Ejemplos

La siguiente función inscribe una plantilla biométrica en el grupo del sistema mediante una llamada a WinBioEnrollCapture. 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