Função WinBioLocateSensor (winbio.h)
Recupera o número de ID de uma unidade biométrica selecionada interativamente por um usuário.
Sintaxe
HRESULT WinBioLocateSensor(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[out, optional] WINBIO_UNIT_ID *UnitId
);
Parâmetros
[in] SessionHandle
Um valor WINBIO_SESSION_HANDLE que identifica uma sessão biométrica aberta. Abra um identificador de sessão síncrona chamando WinBioOpenSession. Abra um identificador de sessão assíncrona chamando WinBioAsyncOpenSession.
[out, optional] UnitId
Um ponteiro para um valor ULONG que especifica a unidade biométrica.
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 ponteiro especificado pelo parâmetro UnitId não pode ser NULL. |
|
A operação não pôde ser concluída porque a unidade biométrica está sendo usada atualmente para uma transação de registro (somente pool do sistema). |
Comentários
Você pode usar essa função em sistemas com vários sensores para determinar qual sensor é preferencial para registro pelo usuário. Nenhuma informação de identificação é retornada por essa função. Ele é fornecido apenas para indicar a seleção do sensor de usuário.
As chamadas para essa função usando o pool do sistema serão bloqueadas até que o aplicativo adquira o foco da janela e o usuário tenha fornecido uma amostra biométrica. Portanto, recomendamos que seu aplicativo não chame WinBioLocateSensor até que ele tenha adquirido o foco. A maneira como você adquire foco depende do tipo de aplicativo que você está escrevendo. Por exemplo, se você estiver criando um aplicativo de GUI, poderá implementar um manipulador de mensagens que captura um WM_ACTIVATE, WM_SETFOCUS ou outra mensagem apropriada. Se você estiver escrevendo um aplicativo CUI, chame GetConsoleWindow para recuperar um identificador para a janela do console e passe esse identificador para a função SetForegroundWindow para forçar a janela do console para o primeiro plano e atribuí-lo ao foco. Se o aplicativo estiver em execução em um processo desanexado e não tiver janela ou for um serviço Windows, use WinBioAcquireFocus e WinBioReleaseFocus para controlar manualmente o foco.
Para usar WinBioLocateSensor de forma síncrona, chame a função com um identificador de sessão criado chamando WinBioOpenSession. A função é bloqueada até que a operação seja concluída ou um erro seja encontrado.
Para usar WinBioLocateSensor de forma assíncrona, chame a função com um identificador de sessão criado chamando WinBioAsyncOpenSession. A estrutura aloca uma estrutura WINBIO_ASYNC_RESULT e a usa para retornar informações sobre êxito ou falha da operação. A estrutura WINBIO_ASYNC_RESULT é retornada para o retorno de chamada do aplicativo ou para a fila de mensagens do aplicativo, dependendo do valor definido no parâmetro NotificationMethod da função WinBioAsyncOpenSession :
- Se você optar por receber avisos de conclusão usando um retorno de chamada, deverá implementar uma função PWINBIO_ASYNC_COMPLETION_CALLBACK e definir o parâmetro NotificationMethod como WINBIO_ASYNC_NOTIFY_CALLBACK.
- Se você optar por receber avisos de conclusão usando a fila de mensagens do aplicativo, deverá definir o parâmetro NotificationMethod como WINBIO_ASYNC_NOTIFY_MESSAGE. A estrutura retorna um ponteiro WINBIO_ASYNC_RESULT para o campo LPARAM da mensagem da janela.
Windows 7: Você pode executar essa operação de forma assíncrona usando a função WinBioLocateSensorWithCallback . A função verifica os argumentos de entrada e retorna imediatamente. Se os argumentos de entrada não forem válidos, a função retornará um código de erro. Caso contrário, a estrutura iniciará a operação em outro thread. Quando a operação assíncrona é concluída ou encontra um erro, a estrutura envia os resultados para a função PWINBIO_LOCATE_SENSOR_CALLBACK implementada pelo aplicativo.
Exemplos
A função a seguir chama WinBioLocateSensor para localizar um sensor biométrico instalado. 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 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 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 |