Función WinBioLocateSensor (winbio.h)

  • Artículo

Recupera el número de identificador de una unidad biométrica seleccionada interactivamente por un usuario.

Sintaxis

HRESULT WinBioLocateSensor(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [out, optional] WINBIO_UNIT_ID        *UnitId
);

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

Puntero a un valor ULONG que especifica la unidad biométrica.

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
 El puntero especificado por el parámetro UnitId no puede 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

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.

Las llamadas a esta función mediante el grupo de sistemas se bloquearán hasta que la aplicación adquiera el foco de la ventana y el usuario haya proporcionado una muestra biométrica. Por lo tanto, se recomienda que la aplicación no llame a WinBioLocateSensor 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 WinBioLocateSensor 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 WinBioLocateSensor 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. 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.

Windows 7: Puede realizar esta operación de forma asincrónica mediante la función WinBioLocateSensorWithCallback . 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_LOCATE_SENSOR_CALLBACK implementada por la aplicación.

Ejemplos

La siguiente función llama a WinBioLocateSensor para localizar un sensor biométrico instalado. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:

  • Windows.h
  • Stdio.h
  • Conio.h
  • Winbio.h
HRESULT LocateSensor( )
{
    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 WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate the sensor.
    wprintf_s(L"\n Tap the sensor once...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Sensor located successfully. ");
    wprintf_s(L"\n Unit ID = %d \n", unitId);

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

    wprintf_s(L"\n Hit 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

WinBioLocateSensorWithCallback