Função WinBioCaptureSampleWithCallback (winbio.h)
Captura uma amostra biométrica de forma assíncrona e retorna os dados brutos ou processados em um BIR (registro de informações biométricas). A função retorna imediatamente ao chamador, captura o exemplo em um thread separado e chama uma função de retorno de chamada definida pelo aplicativo para atualizar a operação status.
Recomendamos que, começando com Windows 8, você não use mais essa função para iniciar uma operação assíncrona. Em vez disso, faça o seguinte:
- Implemente uma função PWINBIO_ASYNC_COMPLETION_CALLBACK para receber aviso quando a operação for concluída.
- Chame a função WinBioAsyncOpenSession . Passe o endereço do retorno de chamada no parâmetro CallbackRoutine . Passe WINBIO_ASYNC_NOTIFY_CALLBACK no parâmetro NotificationMethod . Recupere um identificador de sessão assíncrono.
- Use o identificador de sessão assíncrona para chamar WinBioCaptureSample. Quando a operação for concluída, a Estrutura Biométrica do Windows alocará e inicializará uma estrutura WINBIO_ASYNC_RESULT com os resultados e invocará o retorno de chamada com um ponteiro para a estrutura de resultados.
- Chame WinBioFree de sua implementação de retorno de chamada para liberar a estrutura WINBIO_ASYNC_RESULT depois de terminar de usá-la.
Sintaxe
HRESULT WinBioCaptureSampleWithCallback(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_BIR_PURPOSE Purpose,
[in] WINBIO_BIR_DATA_FLAGS Flags,
[in] PWINBIO_CAPTURE_CALLBACK CaptureCallback,
[in, optional] PVOID CaptureCallbackContext
);
Parâmetros
[in] SessionHandle
Um valor WINBIO_SESSION_HANDLE que identifica uma sessão biométrica aberta.
[in] Purpose
Uma máscara de bits WINBIO_BIR_PURPOSE que especifica o uso pretendido do exemplo. Isso pode ser um OR bit a bit dos seguintes valores:
- WINBIO_PURPOSE_VERIFY
- WINBIO_PURPOSE_IDENTIFY
- WINBIO_PURPOSE_ENROLL
- WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
- WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
[in] Flags
Um valor que especifica o tipo de processamento a ser aplicado ao exemplo capturado. Isso pode ser um OR bit a bit dos seguintes sinalizadores de nível de segurança e processamento:
- WINBIO_DATA_FLAG_PRIVACY
Criptografe o exemplo.
- WINBIO_DATA_FLAG_INTEGRITY
Assine o exemplo ou proteja-o usando um MAC (código de autenticação de mensagem).
- WINBIO_DATA_FLAG_SIGNED
Se esse sinalizador e o WINBIO_DATA_FLAG_INTEGRITYflag estiverem definidos, assine o exemplo. Se esse sinalizador não estiver definido, mas o sinalizador WINBIO_DATA_FLAG_INTEGRITY estiver definido, compute um MAC.
- WINBIO_DATA_FLAG_RAW
Retorne o exemplo exatamente como foi capturado pelo sensor.
- WINBIO_DATA_FLAG_INTERMEDIATE
Retorne o exemplo depois de ter sido limpo e filtrado.
- WINBIO_DATA_FLAG_PROCESSED
Retorne o exemplo depois que ele estiver pronto para ser usado para a finalidade especificada pelo parâmetro Purpose .
[in] CaptureCallback
Endereço de uma função de retorno de chamada que será chamada pela função WinBioCaptureSampleWithCallback quando a operação de captura for bem-sucedida ou falhar. Você deve criar o retorno de chamada.
[in, optional] CaptureCallbackContext
Endereço de uma estrutura de dados definida pelo aplicativo que é passada para a função de retorno de chamada em seu parâmetro CaptureCallbackContext . Essa estrutura pode conter todos os dados que a função de retorno de chamada personalizada foi projetada para manipular.
Retornar valor
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 chamador não tem permissão para capturar amostras brutas ou a sessão não foi aberta usando o sinalizador WINBIO_FLAG_RAW . |
|
O identificador de sessão não é válido. |
|
A unidade biométrica não dá suporte à operação solicitada. |
|
Os ponteiros UnitId, Sample, SampleSize e RejectDetail não podem ser NULL. |
|
A operação não pôde ser concluída porque a unidade biométrica está sendo usada no momento para uma transação de registro (somente pool do sistema). |
Comentários
A função WinBioCaptureSampleWithCallback captura exemplos de forma assíncrona. Para chamar essa função com êxito, o identificador de sessão deve ter sido aberto especificando WINBIO_FLAG_RAW. Somente as contas Administradores e Sistema Local têm os privilégios necessários.
Combinações válidas dos parâmetros Purpose e Flags dependem dos recursos da unidade biométrica que está sendo usada. Consulte a documentação do sensor do fornecedor para determinar quais combinações têm suporte e como elas afetam os dados capturados.
Os chamadores são responsáveis por liberar a estrutura de WINBIO_BIR retornada pelo parâmetro Sample .
A rotina de retorno de chamada deve ter a seguinte assinatura:
VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
);
Exemplos
O exemplo de código a seguir captura um exemplo de forma assíncrona chamando WinBioCaptureSampleWithCallback e passando um ponteiro para uma função de retorno de chamada personalizada. A função de retorno de chamada, CaptureSampleCallback, também é mostrada. 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 CaptureSampleWithCallback(BOOL bCancel)
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
// Connect to the system pool.
hr = WinBioOpenSession(
WINBIO_TYPE_FINGERPRINT, // Service provider
WINBIO_POOL_SYSTEM, // Pool type
WINBIO_FLAG_RAW, // Raw access
NULL, // Array of biometric unit IDs
0, // Count of biometric unit IDs
WINBIO_DB_DEFAULT, // Default database
&sessionHandle // [out] Session handle
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Capture a biometric sample asynchronously.
wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
hr = WinBioCaptureSampleWithCallback(
sessionHandle, // Open session handle
WINBIO_NO_PURPOSE_AVAILABLE, // Intended use of the sample
WINBIO_DATA_FLAG_RAW, // Sample format
CaptureSampleCallback, // Callback function
NULL // Optional context
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Swipe the sensor ...\n");
// Cancel the capture process if the bCancel flag is set.
if (bCancel)
{
wprintf_s(L"\n Starting CANCEL timer...");
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 capture 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)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
)
{
UNREFERENCED_PARAMETER(CaptureCallbackContext);
wprintf_s(L"\n CaptureSampleCallback executing");
wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);
if (FAILED(OperationStatus))
{
if (OperationStatus == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
}
else
{
wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
}
goto e_Exit;
}
wprintf_s(L"\n Captured %d bytes.\n", SampleSize);
e_Exit:
if (Sample != NULL)
{
WinBioFree(Sample);
Sample = NULL;
}
}
Requisitos
| Requisito | Valor |
|---|---|
| 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