Función WinBioRegisterEventMonitor (winbio.h)
La función WinBioRegisterEventMonitor Registra una función de devolución de llamada para recibir notificaciones de eventos del proveedor de servicios asociado a una sesión abierta.
Sintaxis
HRESULT WinBioRegisterEventMonitor(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_EVENT_TYPE EventMask,
[in] PWINBIO_EVENT_CALLBACK EventCallback,
[in] PVOID EventCallbackContext
);
Parámetros
[in] SessionHandle
Valor de WINBIO_SESSION_HANDLE que identifica la sesión biométrica abierta. Abra el identificador de sesión mediante una llamada a WinBioOpenSession.
[in] EventMask
Valor que especifica los tipos de eventos que se van a supervisar. Actualmente solo se admite el proveedor de huellas digitales. Debe especificar una de las marcas siguientes.
- WINBIO_EVENT_FP_UNCLAIMED
El sensor detectó un dedo que no solicitó la aplicación o que la aplicación solicitante no tiene el foco de la ventana. Windows Biometric Framework llama a la función de devolución de llamada para indicar que se ha producido un dedo dedo pero no intenta identificar la huella digital.
- WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY
El sensor detectó un dedo que no solicitó la aplicación o que la aplicación solicitante no tiene el foco de la ventana. Windows Biometric Framework intenta identificar la huella digital y pasa el resultado de ese proceso a la función de devolución de llamada.
[in] EventCallback
Dirección de una función de devolución de llamada que recibe las notificaciones de eventos enviadas por Windows Biometric Framework. Debe definir esta función.
[in] EventCallbackContext
Valor opcional definido por la aplicación que se devuelve en el parámetro pvContext de la función de devolución de llamada. Este valor 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 |
|---|---|
|
El identificador de sesión no es válido. |
|
La dirección de la función de devolución de llamada especificada por el parámetro EventCallback no puede ser NULL. |
|
El parámetro EventMask no puede ser cero y no puede especificar WINBIO_EVENT_FP_UNCLAIMED y WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY al mismo tiempo. |
|
Ya se ha registrado un monitor de eventos activo. |
|
El proveedor de servicios no admite la notificación de eventos. |
Comentarios
Esta función solo es válida para las sesiones conectadas a un grupo de sensores del sistema.
Las devoluciones de llamada de eventos se entregan a la aplicación cliente en serie. Por lo tanto, las notificaciones de eventos posteriores no se entregarán hasta que el cliente vuelva de la devolución de llamada actual. El sistema puede descartar los eventos que se producen mientras se está ejecutando una devolución de llamada. Para evitar perder eventos, no debe realizar ningún trabajo lento en la rutina de devolución de llamada.
La aplicación cliente debe estar preparada para recibir eventos tan pronto como se llame a WinBioRegisterEventMonitor . La aplicación debe llamar a WinBioFree para liberar la estructura devuelta en el argumento Event de la devolución de llamada. Si no lo hace, se producirá una pérdida de memoria en el proceso de llamada.
Una vez iniciado un monitor de eventos, la sesión con la que está asociado el monitor no podrá procesar otras llamadas a la API de Windows Biometric Framework hasta que se haya detenido el monitor de eventos. Si la aplicación necesita realizar otras llamadas API mientras sigue recibiendo notificaciones del monitor de eventos, debe abrir dos sesiones: una para el monitor de eventos y otra para otras operaciones.
Llame a WinBioUnregisterEventMonitor para dejar de enviar notificaciones de eventos a la función de devolución de llamada.
Si una aplicación registra un monitor de eventos WinBio y deja ese monitor activo durante un ciclo de suspensión o reactivación, es posible que los sistemas que implementan la autenticación biométrica previa al arranque (PBA)/las características de inicio de sesión único no siempre funcionen. El problema es que el monitor de eventos intercepta la llamada biométrica PBA antes de que el proveedor de credenciales biométricas del sistema tenga la oportunidad de realizar su primera operación WinBioIdentify . Las aplicaciones que usan la característica de supervisión de eventos winBio deben anular el registro de sus monitores antes de que el sistema se suspenda y volver a registrarlos después de la reactivación del sistema. Para obtener más información sobre el control de eventos durante los cambios de estado de energía, consulte Acerca de la administración de energía.
La rutina de devolución de llamada debe tener la siguiente firma:
VOID CALLBACK EventCallback(
__in_opt PVOID EventCallbackContext,
__in HRESULT OperationStatus,
__in PWINBIO_EVENT Event
);
Ejemplos
La siguiente función registra un monitor de eventos llamando a la función WinBioRegisterEventMonitor y pasando la dirección de una rutina de devolución de llamada. La devolución de llamada, también incluida, recibe notificaciones de eventos del marco biométrico de Windows. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT RegisterSystemEventMonitor(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;
}
// Call the WinBioRegisterEventMonitor function.
wprintf_s(L"\n Calling WinBioRegisterEventMonitor.\n");
hr = WinBioRegisterEventMonitor(
sessionHandle, // Open session handle
WINBIO_EVENT_FP_UNCLAIMED, // Events to monitor
EventMonitorCallback, // Callback function
NULL // Optional context.
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioRegisterEventMonitor failed.");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Waiting for an event.\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 an event to happen.
//wprintf_s(L"\n Swipe the sensor to receive an event notice ");
//wprintf_s(L"\n or press any key to stop waiting...\n");
wprintf_s(L"\n Swipe the sensor one or more times ");
wprintf_s(L"to generate events.");
wprintf_s(L"\n When done, press a key to exit...\n");
_getch();
// Unregister the event monitor.
wprintf_s(L"\n Calling WinBioUnregisterEventMonitor\n");
hr = WinBioUnregisterEventMonitor( sessionHandle);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioUnregisterEventMonitor failed.");
wprintf_s(L"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 Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function is the callback for WinBioRegisterEventMonitor.
// The function filters any event notice from the biometric subsystem and
// writes a result to the console window.
//
VOID CALLBACK EventMonitorCallback(
__in_opt PVOID EventCallbackContext,
__in HRESULT OperationStatus,
__in PWINBIO_EVENT Event
)
{
UNREFERENCED_PARAMETER(EventCallbackContext);
wprintf_s(L"\n EventMonitorCallback executing.");
// Failure.
if (FAILED(OperationStatus))
{
wprintf_s(L"\n EventMonitorCallback failed. ");
wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
goto e_Exit;
}
// An event notice was received.
if (Event != NULL)
{
wprintf_s(L"\n MonitorEvent: ");
switch (Event->Type)
{
case WINBIO_EVENT_FP_UNCLAIMED:
wprintf_s(L"WINBIO_EVENT_FP_UNCLAIMED");
wprintf_s(L"\n Unit ID: %d",
Event->Parameters.Unclaimed.UnitId);
wprintf_s(L"\n Reject detail: %d\n",
Event->Parameters.Unclaimed.RejectDetail);
break;
case WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY:
wprintf_s(L"WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY");
wprintf_s(L"\n Unit ID: %d",
Event->Parameters.UnclaimedIdentify.UnitId);
wprintf_s(L"\n Reject detail: %d\n",
Event->Parameters.UnclaimedIdentify.RejectDetail);
break;
case WINBIO_EVENT_ERROR:
wprintf_s(L"WINBIO_EVENT_ERROR\n");
break;
default:
wprintf_s(L"(0x%08x - Invalid type)\n", Event->Type);
break;
}
}
e_Exit:
if (Event != NULL)
{
//wprintf_s(L"\n Press any key to continue...\n");
WinBioFree(Event);
Event = NULL;
}
}
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 |