Función WinBioCaptureSampleWithCallback (winbio.h)

Artículo
08/27/2023

Captura una muestra biométrica de forma asincrónica y devuelve los datos sin procesar o procesados en un registro de información biométrica (BIR). La función vuelve inmediatamente al autor de la llamada, captura el ejemplo en un subproceso independiente y llama a una función de devolución de llamada definida por la aplicación para actualizar el estado de la operación.

Importante

Se recomienda que, a partir de Windows 8, ya no use esta función para iniciar una operación asincrónica. En su lugar, haga lo siguiente:

Implemente una función de PWINBIO_ASYNC_COMPLETION_CALLBACK para recibir aviso cuando se complete la operación.
Llame a la función WinBioAsyncOpenSession . Pase la dirección de la devolución de llamada en el parámetro CallbackRoutine . Pase WINBIO_ASYNC_NOTIFY_CALLBACK en el parámetro NotificationMethod . Recupere un identificador de sesión asincrónico.
Use el identificador de sesión asincrónico para llamar a WinBioCaptureSample. Cuando finalice la operación, Windows Biometric Framework asignará e inicializará una estructura de WINBIO_ASYNC_RESULT con los resultados e invocará la devolución de llamada con un puntero a la estructura de resultados.
Llame 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.

Sintaxis

HRESULT WinBioCaptureSampleWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_BIR_PURPOSE       Purpose,
  [in]           WINBIO_BIR_DATA_FLAGS    Flags,
  [in]           PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  [in, optional] PVOID                    CaptureCallbackContext
);

Parámetros

[in] SessionHandle

Valor de WINBIO_SESSION_HANDLE que identifica una sesión biométrica abierta.

[in] Purpose

Máscara de bits WINBIO_BIR_PURPOSE que especifica el uso previsto del ejemplo. Puede ser un OR bit a bit de los siguientes valores:

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

Valor que especifica el tipo de procesamiento que se va a aplicar al ejemplo capturado. Puede ser un OR bit a bit de las siguientes marcas de nivel de seguridad y procesamiento:

WINBIO_DATA_FLAG_PRIVACY

Cifre el ejemplo.

WINBIO_DATA_FLAG_INTEGRITY

Firme el ejemplo o protéjalo mediante un código de autenticación de mensajes (MAC).

WINBIO_DATA_FLAG_SIGNED

Si se establece esta marca y el WINBIO_DATA_FLAG_INTEGRITYflag, firme el ejemplo. Si no se establece esta marca, pero se establece la marca WINBIO_DATA_FLAG_INTEGRITY, calcule un MAC.

WINBIO_DATA_FLAG_RAW

Devuelve la muestra exactamente como lo capturó el sensor.

WINBIO_DATA_FLAG_INTERMEDIATE

Devuelve el ejemplo después de limpiarlo y filtrarlo.

WINBIO_DATA_FLAG_PROCESSED

Devuelve el ejemplo después de que esté listo para usarse para el propósito especificado por el parámetro Purpose .

[in] CaptureCallback

Dirección de una función de devolución de llamada a la que llamará la función WinBioCaptureSampleWithCallback cuando la operación de captura se realice correctamente o se produzca un error. Debe crear la devolución de llamada.

[in, optional] CaptureCallbackContext

Dirección de una estructura de datos definida por la aplicación que se pasa a la función de devolución de llamada en su parámetro CaptureCallbackContext . Esta estructura puede contener los datos que la función de devolución de llamada personalizada está diseñada para controlar.

Valor devuelto

Si la función se ejecuta 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	El autor de la llamada no tiene permiso para capturar muestras sin procesar o la sesión no se abrió mediante la marca WINBIO_FLAG_RAW .
E_HANDLE	El identificador de sesión no es válido.
E_NOTIMPL	La unidad biométrica no admite la operación solicitada.
E_POINTER	Los punteros UnitId, Sample, SampleSize y RejectDetail no pueden ser NULL.
WINBIO_E_ENROLLMENT_IN_PROGRESS	No se pudo completar la operación porque la unidad biométrica se está usando actualmente para una transacción de inscripción (solo para el grupo de sistemas).

Comentarios

La función WinBioCaptureSampleWithCallback captura muestras de forma asincrónica. Para llamar correctamente a esta función, el identificador de sesión debe haberse abierto especificando WINBIO_FLAG_RAW. Solo los administradores y las cuentas del sistema local tienen los privilegios necesarios.

Las combinaciones válidas de los parámetrosPurpose y Flags dependen de las funcionalidades de la unidad biométrica que se usa. Consulte la documentación del sensor de proveedor para determinar qué combinaciones se admiten y cómo afectan a los datos capturados.

Los autores de llamadas son responsables de liberar la estructura de WINBIO_BIR devuelta por el parámetro Sample .

La rutina de devolución de llamada debe tener la siguiente firma:

VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
);

Ejemplos

En el ejemplo de código siguiente se captura un ejemplo de forma asincrónica llamando a WinBioCaptureSampleWithCallback y pasando un puntero a una función de devolución de llamada personalizada. También se muestra la función de devolución de llamada CaptureSampleCallback. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT CaptureSampleWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Raw access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample asynchronously.
    wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
    hr = WinBioCaptureSampleWithCallback(
            sessionHandle,                  // Open session handle
            WINBIO_NO_PURPOSE_AVAILABLE,    // Intended use of the sample
            WINBIO_DATA_FLAG_RAW,           // Sample format
            CaptureSampleCallback,          // Callback function
            NULL                            // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the capture process if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...");
        Sleep( 7000 );

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

    // Wait for the asynchronous capture process to complete 
    // or be canceled.
    hr = WinBioWait( sessionHandle );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
    }

e_Exit:

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

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
    __in_opt PVOID CaptureCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in_bcount(SampleSize) PWINBIO_BIR Sample,
    __in SIZE_T SampleSize,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(CaptureCallbackContext);

    wprintf_s(L"\n CaptureSampleCallback executing");
    wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);

    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
         }
        else
        {
            wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
            wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Captured %d bytes.\n", SampleSize);

e_Exit:

    if (Sample != NULL)
    {
        WinBioFree(Sample);
        Sample = NULL;
    }
}

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 (incluya Winbio.h)
Library	Winbio.lib
Archivo DLL	Winbio.dll

Consulte también

WinBioCaptureSample

Compartir a través de

Función WinBioCaptureSampleWithCallback (winbio.h)

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplos

Requisitos

Consulte también

Comentarios

Recursos adicionales