Función WinBioLocateSensorWithCallback (winbio.h)

Artículo
08/27/2023

Recupera de forma asincrónica el número de identificador de la unidad biométrica seleccionada interactivamente por un usuario. La función vuelve inmediatamente al autor de la llamada, procesa en un subproceso independiente e informa de la unidad biométrica seleccionada mediante una llamada a una función de devolución de llamada definida por la aplicació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 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 . Recuperar un identificador de sesión asincrónico.
Use el identificador de sesión asincrónico para llamar a WinBioLocateSensor. Cuando finalice la operación, el marco biométrico de Windows 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 WinBioLocateSensorWithCallback(
  [in]           WINBIO_SESSION_HANDLE          SessionHandle,
  [in]           PWINBIO_LOCATE_SENSOR_CALLBACK LocateCallback,
  [in, optional] PVOID                          LocateCallbackContext
);

Parámetros

[in] SessionHandle

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

[in] LocateCallback

Dirección de una función de devolución de llamada a la que llamará la función WinBioLocateSensorWithCallback cuando la ubicación del sensor se realice correctamente o se produzca un error. Debe crear la devolución de llamada.

[in, optional] LocateCallbackContext

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 LocateCallbackContext . 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 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	La dirección especificada por el parámetro LocateCallback no puede ser NULL.

Comentarios

Puede usar esta función en sistemas con varios sensores para determinar qué sensor es el preferido para la inscripción por parte del usuario. Esta función no devuelve ninguna información de identificación. Solo se proporciona para indicar la selección del sensor de usuario.

Si el parámetro SessionHandle hace referencia al grupo de sensores del sistema, no se llamará a la función de devolución de llamada hasta que la aplicación adquiera el foco de la ventana y el usuario haya proporcionado una muestra biométrica. 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.

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


VOID CALLBACK LocateCallback(
__in_opt PVOID LocateCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId
);

Ejemplos

La siguiente función llama a WinBioLocateSensorWithCallback para localizar el sensor biométrico. WinBioLocateSensorWithCallback es una función asincrónica que configura el subsistema biométrico para localizar el sensor en otro subproceso. La salida del subsistema biométrico se envía a una función de devolución de llamada personalizada denominada LocateSensorCallback. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:

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

HRESULT LocateSensorWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;

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

    wprintf_s(L"\n Calling WinBioLocateSensorWithCallback.");
    hr = WinBioLocateSensorWithCallback(
                sessionHandle,          // Open biometric session
                LocateSensorCallback,   // Callback function
                NULL                    // Optional context
                );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensorWithCallback failed.");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the identification if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...\n");
        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 identification 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)
    {
       wprintf_s(L"\n Closing the session.\n");

        hr = WinBioCloseSession(sessionHandle);
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCloseSession failed. hr = 0x%x\n", hr);
        }
        sessionHandle = NULL;
    }

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

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for 
// WinBioLocateSensorWithCallback. The function filters the response 
// from the biometric subsystem and writes a result to the console window.
// 
VOID CALLBACK LocateSensorCallback(
    __in_opt PVOID LocateCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId
    )
{
    UNREFERENCED_PARAMETER(LocateCallbackContext);

    wprintf_s(L"\n LocateSensorCallback executing.");

    // A sensor could not be located.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n LocateSensorCallback failed.");
        wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
    }
    // A sensor was located.
    else
    {
        wprintf_s(L"\n Selected unit ID: %d\n", UnitId);
    }
}

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

WinBioLocateSensor

Compartir a través de

Función WinBioLocateSensorWithCallback (winbio.h)

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplos

Requisitos

Consulte también

Comentarios

Recursos adicionales