Função WinBioVerify (winbio.h)
Captura uma amostra biométrica e determina se o exemplo corresponde à identidade do usuário especificada. A partir do Windows 10, build 1607, essa função está disponível para uso com uma imagem móvel.
Sintaxe
HRESULT WinBioVerify(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_IDENTITY *Identity,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[out, optional] WINBIO_UNIT_ID *UnitId,
[out, optional] BOOLEAN *Match,
[out, optional] WINBIO_REJECT_DETAIL *RejectDetail
);
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.
[in] Identity
Ponteiro para uma estrutura WINBIO_IDENTITY que contém o GUID ou SID do usuário que fornece a amostra biométrica.
[in] SubFactor
Um valor WINBIO_BIOMETRIC_SUBTYPE que especifica o subfator associado à amostra biométrica. Atualmente, o WBF (Windows Biometric Framework) dá suporte apenas à captura de impressão digital e pode usar as constantes a seguir para representar informações de subtipo.
- WINBIO_ANSI_381_POS_RH_THUMB
- WINBIO_ANSI_381_POS_RH_INDEX_FINGER
- WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_RH_RING_FINGER
- WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_LH_THUMB
- WINBIO_ANSI_381_POS_LH_INDEX_FINGER
- WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_LH_RING_FINGER
- WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_RH_FOUR_FINGERS
- WINBIO_ANSI_381_POS_LH_FOUR_FINGERS
- WINBIO_SUBTYPE_ANY
[out, optional] UnitId
Um ponteiro para um valor WINBIO_UNIT_ID que especifica a unidade biométrica que executou a verificação.
[out, optional] Match
Ponteiro para um valor booliano que especifica se o exemplo capturado correspondeu à identidade do usuário especificada pelo parâmetro Identity .
[out, optional] RejectDetail
Um ponteiro para um valor ULONG que contém informações adicionais sobre a falha ao capturar uma amostra biométrica. Se a captura for bem-sucedida, esse parâmetro será definido como zero. Os seguintes valores são definidos para captura de impressão digital:
- WINBIO_FP_TOO_HIGH
- WINBIO_FP_TOO_LOW
- WINBIO_FP_TOO_LEFT
- WINBIO_FP_TOO_RIGHT
- WINBIO_FP_TOO_FAST
- WINBIO_FP_TOO_SLOW
- WINBIO_FP_POOR_QUALITY
- WINBIO_FP_TOO_SKEWED
- WINBIO_FP_TOO_SHORT
- WINBIO_FP_MERGE_FAILURE
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 argumento SubFactor está incorreto. |
|
O ponteiro especificado pelos parâmetros UnitId, Identity, SubFactor ou RejectDetail não pode ser NULL. |
|
Não foi possível capturar a amostra biométrica. Use o valor RejectDetail para obter mais informações. |
|
Não foi possível concluir a operação porque a unidade biométrica especificada está sendo usada para uma transação de registro (somente pool do sistema). |
|
O exemplo biométrico não corresponde à combinação de Identidade e SubFator especificada. |
Comentários
Se a captura da amostra biométrica falhar, o parâmetro UnitId conterá o número da unidade do sensor que tentou executar a captura.
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. Recomendamos, portanto, que seu aplicativo não chame WinBioVerify 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 WinBioVerify 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 WinBioVerify 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. Se a operação for bem-sucedida, a estrutura retornará um valor de correspondência BOOLEAN em uma estrutura Verify aninhada. Se a operação não for bem-sucedida, a estrutura retornará WINBIO_REJECT_DETAIL informações na estrutura Verify . 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 WinBioVerifyWithCallback . 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_VERIFY_CALLBACK implementada pelo aplicativo.
Exemplos
A função a seguir chama WinBioVerify para determinar se uma amostra biométrica corresponde à identidade conectada do usuário atual. A função auxiliar GetCurrentUserIdentity também está incluída. 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 Verify(WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
WINBIO_IDENTITY identity = {0};
BOOLEAN match = FALSE;
// Find the identity of the user.
hr = GetCurrentUserIdentity( &identity );
if (FAILED(hr))
{
wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
goto e_Exit;
}
// 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;
}
// Verify a biometric sample.
wprintf_s(L"\n Calling WinBioVerify - Swipe finger on sensor...\n");
hr = WinBioVerify(
sessionHandle,
&identity,
subFactor,
&unitId,
&match,
&rejectDetail
);
wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
if (FAILED(hr))
{
if (hr == WINBIO_E_NO_MATCH)
{
wprintf_s(L"\n- NO MATCH - identity verification failed.\n");
}
else if (hr == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n- Bad capture; reason: %d\n", rejectDetail);
}
else
{
wprintf_s(L"\n WinBioVerify failed. hr = 0x%x\n", hr);
}
goto e_Exit;
}
wprintf_s(L"\n Fingerprint verified:\n", unitId);
e_Exit:
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function retrieves the identity of the current user.
// This is a helper function and is not part of the Windows Biometric
// Framework API.
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
// Declare variables.
HRESULT hr = S_OK;
HANDLE tokenHandle = NULL;
DWORD bytesReturned = 0;
struct{
TOKEN_USER tokenUser;
BYTE buffer[SECURITY_MAX_SID_SIZE];
} tokenInfoBuffer;
// Zero the input identity and specify the type.
ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
Identity->Type = WINBIO_ID_TYPE_NULL;
// Open the access token associated with the
// current process
if (!OpenProcessToken(
GetCurrentProcess(), // Process handle
TOKEN_READ, // Read access only
&tokenHandle)) // Access token handle
{
DWORD win32Status = GetLastError();
wprintf_s(L"Cannot open token handle: %d\n", win32Status);
hr = HRESULT_FROM_WIN32(win32Status);
goto e_Exit;
}
// Zero the tokenInfoBuffer structure.
ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));
// Retrieve information about the access token. In this case,
// retrieve a SID.
if (!GetTokenInformation(
tokenHandle, // Access token handle
TokenUser, // User for the token
&tokenInfoBuffer.tokenUser, // Buffer to fill
sizeof(tokenInfoBuffer), // Size of the buffer
&bytesReturned)) // Size needed
{
DWORD win32Status = GetLastError();
wprintf_s(L"Cannot query token information: %d\n", win32Status);
hr = HRESULT_FROM_WIN32(win32Status);
goto e_Exit;
}
// Copy the SID from the tokenInfoBuffer structure to the
// WINBIO_IDENTITY structure.
CopySid(
SECURITY_MAX_SID_SIZE,
Identity->Value.AccountSid.Data,
tokenInfoBuffer.tokenUser.User.Sid
);
// Specify the size of the SID and assign WINBIO_ID_TYPE_SID
// to the type member of the WINBIO_IDENTITY structure.
Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
Identity->Type = WINBIO_ID_TYPE_SID;
e_Exit:
if (tokenHandle != NULL)
{
CloseHandle(tokenHandle);
}
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 |