Função WinBioRegisterEventMonitor (winbio.h)
A função WinBioRegisterEventMonitor Registra uma função de retorno de chamada para receber notificações de evento do provedor de serviços associado a uma sessão aberta.
Sintaxe
HRESULT WinBioRegisterEventMonitor(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_EVENT_TYPE EventMask,
[in] PWINBIO_EVENT_CALLBACK EventCallback,
[in] PVOID EventCallbackContext
);
Parâmetros
[in] SessionHandle
Um valor WINBIO_SESSION_HANDLE que identifica a sessão biométrica aberta. Abra o identificador de sessão chamando WinBioOpenSession.
[in] EventMask
Um valor que especifica os tipos de eventos a serem monitorados. No momento, há suporte apenas para o provedor de impressão digital. Você deve especificar um dos sinalizadores a seguir.
- WINBIO_EVENT_FP_UNCLAIMED
O sensor detectou um dedo que não foi solicitado pelo aplicativo ou o aplicativo solicitante não tem o foco da janela. A Estrutura Biométrica do Windows chama sua função de retorno de chamada para indicar que ocorreu um dedo, mas não tenta identificar a impressão digital.
- WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY
O sensor detectou um dedo que não foi solicitado pelo aplicativo ou o aplicativo solicitante não tem o foco da janela. A Estrutura Biométrica do Windows tenta identificar a impressão digital e passa o resultado desse processo para sua função de retorno de chamada.
[in] EventCallback
Endereço de uma função de retorno de chamada que recebe as notificações de evento enviadas pela Estrutura Biométrica do Windows. Você deve definir essa função.
[in] EventCallbackContext
Um valor opcional definido pelo aplicativo que é retornado no parâmetro pvContext da função de retorno de chamada. Esse valor pode conter todos os dados que a função de retorno de chamada personalizada foi projetada para manipular.
Valor retornado
Se a função for bem-sucedida, ela retornará S_OK. Se a função falhar, ela retornará um valor HRESULT que indica o erro. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir. Para obter uma lista de códigos de erro comuns, consulte Valores HRESULT comuns.
| Código de retorno | Descrição |
|---|---|
|
O identificador de sessão não é válido. |
|
O endereço da função de retorno de chamada especificada pelo parâmetro EventCallback não pode ser NULL. |
|
O parâmetro EventMask não pode ser zero e você não pode especificar WINBIO_EVENT_FP_UNCLAIMED e WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY ao mesmo tempo. |
|
Um monitor de eventos ativo já foi registrado. |
|
O provedor de serviços não dá suporte à notificação de eventos. |
Comentários
Essa função só é válida para sessões conectadas a um pool de sensores do sistema.
Os retornos de chamada de evento são entregues ao aplicativo cliente serialmente. Portanto, as notificações de evento subsequentes não serão entregues até que o cliente retorne do retorno de chamada atual. Eventos que ocorrem enquanto um retorno de chamada ainda está em execução podem ser descartados pelo sistema. Para evitar perder eventos, você não deve executar nenhum trabalho demorado em sua rotina de retorno de chamada.
O aplicativo cliente deve estar preparado para receber eventos assim que WinBioRegisterEventMonitor for chamado. O aplicativo deve chamar WinBioFree para liberar a estrutura retornada no argumento Event do retorno de chamada. A falha ao fazer isso resultará em um vazamento de memória no processo de chamada.
Depois que um monitor de eventos for iniciado, a sessão com a qual o monitor está associado não poderá processar outras chamadas à API da Estrutura Biométrica do Windows até que o monitor do evento seja interrompido. Se o aplicativo precisar executar outras chamadas à API enquanto ainda recebe notificações do monitor de eventos, você deve abrir duas sessões : uma para o monitor de eventos e outra para outras operações.
Chame WinBioUnregisterEventMonitor para parar de enviar notificações de evento para sua função de retorno de chamada.
Se um aplicativo registrar um monitor de eventos do WinBio e deixar esse monitor ativo durante um ciclo de suspensão/ativação, os sistemas que implementam a autenticação de pré-inicialização biométrica (PBA)/recursos de logon único nem sempre funcionarão. O problema é que a chamada biométrica do PBA é interceptada pelo monitor de eventos antes que o provedor de credenciais biométricas do sistema tenha a chance de executar sua primeira operação WinBioIdentify . Os aplicativos que usam o recurso de monitoramento de eventos do WinBio devem cancelar o registro de seus monitores antes que o sistema durma e registrá-los novamente após a ativação do sistema. Para obter mais informações sobre como lidar com eventos durante as alterações de estado de energia, consulte Sobre o Gerenciamento de Energia.
A rotina de retorno de chamada deve ter a seguinte assinatura:
VOID CALLBACK EventCallback(
__in_opt PVOID EventCallbackContext,
__in HRESULT OperationStatus,
__in PWINBIO_EVENT Event
);
Exemplos
A função a seguir registra um monitor de eventos chamando a função WinBioRegisterEventMonitor e passando o endereço de uma rotina de retorno de chamada. O retorno de chamada, também incluído, recebe notificações de eventos da estrutura biométrica do Windows. Link para a biblioteca estática Winbio.lib e inclua os seguintes arquivos de cabeçalho:
- 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 com suporte | Windows 7 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 R2 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbio.h (inclua Winbio.h) |
| Biblioteca | Winbio.lib |
| DLL | Winbio.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de