Función WinBioCaptureSample (winbio.h)

  • Artículo

Captura una muestra biométrica y rellena un registro de información biométrica (BIR) con los datos sin procesar o procesados.

Sintaxis

HRESULT WinBioCaptureSample(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_BIR_PURPOSE    Purpose,
  [in]            WINBIO_BIR_DATA_FLAGS Flags,
  [out, optional] WINBIO_UNIT_ID        *UnitId,
                  PWINBIO_BIR           *Sample,
  [out, optional] SIZE_T                *SampleSize,
  [out, optional] WINBIO_REJECT_DETAIL  *RejectDetail
);

Parámetros

[in] SessionHandle

Valor de 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.

[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

Firmar el ejemplo o protegerlo mediante un código de autenticación de mensajes (MAC)

  • WINBIO_DATA_FLAG_SIGNED

Si se establece esta marca y la marca de WINBIO_DATA_FLAG_INTEGRITY, 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.

[out, optional] UnitId

Puntero a un valor de WINBIO_UNIT_ID que contiene el identificador de la unidad biométrica que generó la muestra.

Sample

Dirección de una variable que recibe un puntero a una estructura de WINBIO_BIR que contiene el ejemplo. Cuando haya terminado de usar la estructura, debe pasar el puntero a WinBioFree para liberar la memoria asignada para el ejemplo.

[out, optional] SampleSize

Puntero a un valor de SIZE_T que contiene el tamaño, en bytes, de la estructura WINBIO_BIR devuelta en el parámetro Sample .

[out, optional] RejectDetail

Puntero a un valor de WINBIO_REJECT_DETAIL que contiene información adicional sobre el error de captura de una muestra biométrica. Si la captura se realizó correctamente, este parámetro se establece en cero. Los valores siguientes 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 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).
WINBIO_E_INVALID_OPERATION
 No se pudo completar la operación porque hay un sensor seguro en el grupo de sensores.

Comentarios

Para llamar correctamente a esta función, debe abrir el identificador de sesión especificando WINBIO_FLAG_RAW en el parámetro Flags de las funciones WinBioOpenSession o WinBioAsyncOpenSession . Actualmente, solo las aplicaciones que se ejecutan en las cuentas administradores y 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 del proveedor para determinar qué combinaciones de valores válidos de Propósito y Marcas son compatibles y cómo afectan a los datos capturados. Una vez que haya terminado de usar el ejemplo, la aplicación debe llamar a WinBioFree para liberar la memoria asignada por la función WinBioCaptureSample .

Para usar WinBioCaptureSample 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 haya capturado un ejemplo o se encuentre un error. Las llamadas a WinBioCaptureSample mediante el grupo de sistemas se bloquearán hasta que la aplicación que realiza la llamada tenga el foco de ventana y el usuario proporcione un ejemplo a uno de los sensores del grupo. Si el sensor elegido por el usuario ya se está usando para una transacción de inscripción, se produce un error en la función y se devuelve WINBIO_E_ENROLLMENT_IN_PROGRESS.

Para usar WinBioCaptureSample 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 error de la operación. Si la operación de captura se realiza correctamente, el marco devuelve información sobre el ejemplo en una estructura CaptureSample 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, en función del 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 avisos de finalización mediante la cola de mensajes de la aplicación, debe establecer el parámetro NotificationMethod en 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 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 WinBioCaptureSampleWithCallback . 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 finaliza o encuentra un error, el marco envía los resultados a la función PWINBIO_CAPTURE_CALLBACK implementada por la aplicación.

Ejemplos

La siguiente función llama a WinBioCaptureSample para capturar un ejemplo biométrico de un usuario. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:

  • Windows.h
  • Stdio.h
  • Conio.h
  • Winbio.h
HRESULT CaptureSample()
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    PWINBIO_BIR sample = NULL;
    SIZE_T sampleSize = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Access: Capture raw data
            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.
    wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
    hr = WinBioCaptureSample(
            sessionHandle,
            WINBIO_NO_PURPOSE_AVAILABLE,
            WINBIO_DATA_FLAG_RAW,
            &unitId,
            &sample,
            &sampleSize,
            &rejectDetail
            );
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    wprintf_s(L"\n Captured %d bytes.\n", sampleSize);


e_Exit:
    if (sample != NULL)
    {
        WinBioFree(sample);
        sample = NULL;
    }

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

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

    return hr;
}

Requisitos

   
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

WinBioCaptureSampleWithCallback