Функция WinBioVerifyWithCallback (winbio.h)
Асинхронно захватывает биометрическую выборку и определяет, соответствует ли образец указанному удостоверению пользователя. Функция немедленно возвращается вызывающей стороне, выполняет запись и проверку в отдельном потоке и вызывает функцию обратного вызова, определяемую приложением, для обновления состояния операции.
Начиная с Windows 8 мы рекомендуем больше не использовать эту функцию для запуска асинхронной операции. Вместо этого выполните следующие действия.
- Реализуйте функцию PWINBIO_ASYNC_COMPLETION_CALLBACK для получения уведомления по завершении операции.
- Вызовите функцию WinBioAsyncOpenSession . Передайте адрес обратного вызова в параметре CallbackRoutine . Передайте WINBIO_ASYNC_NOTIFY_CALLBACK в параметре NotificationMethod . Получение асинхронного дескриптора сеанса.
- Используйте асинхронный дескриптор сеанса для вызова WinBioVerify. Когда операция завершится, Windows Biometric Framework выделит и инициализирует структуру WINBIO_ASYNC_RESULT с результатами и вызовет обратный вызов с указателем на структуру результатов.
- Вызовите WinBioFree из реализации обратного вызова, чтобы освободить структуру WINBIO_ASYNC_RESULT после завершения ее использования.
Синтаксис
HRESULT WinBioVerifyWithCallback(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_IDENTITY *Identity,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[in] PWINBIO_VERIFY_CALLBACK VerifyCallback,
[in, optional] PVOID VerifyCallbackContext
);
Параметры
[in] SessionHandle
Значение WINBIO_SESSION_HANDLE, определяющее открытый биометрический сеанс.
[in] Identity
Указатель на структуру WINBIO_IDENTITY , содержащую GUID или идентификатор безопасности пользователя, предоставляющего биометрическую выборку.
[in] SubFactor
Значение WINBIO_BIOMETRIC_SUBTYPE , указывающее подфактор, связанный с биометрической выборкой. Дополнительные сведения см. в разделе "Примечания".
[in] VerifyCallback
Адрес функции обратного вызова, которая будет вызываться функцией WinBioVerifyWithCallback при успешной или неудачной проверке. Необходимо создать обратный вызов.
[in, optional] VerifyCallbackContext
Необязательная структура, определяемая приложением, которая возвращается в параметре VerifyCallbackContext функции обратного вызова. Эта структура может содержать любые данные, которые предназначена для обработки пользовательской функции обратного вызова.
Возвращаемое значение
Если функция выполняется успешно, она возвращает S_OK. Если функция завершается сбоем, она возвращает значение HRESULT , указывающее на ошибку. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице. Список распространенных кодов ошибок см. в разделе Общие значения HRESULT.
| Код возврата | Описание |
|---|---|
|
Недопустимый дескриптор сеанса. |
|
Неправильный аргумент SubFactor . |
|
Указатель, заданный параметрами Identity и VerifyCallback , не может иметь значение NULL. |
Комментарии
Параметр SubFactor указывает подфактор, связанный с биометрической выборкой. Windows Биометрическая платформа (WBF) в настоящее время поддерживает только захват отпечатков пальцев и использует следующие константы для представления сведений о подтипе.
- 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
Функция WinBioVerifyWithCallback немедленно возвращается и передает S_OK вызывающей стороне. Чтобы определить состояние процесса записи и проверки, необходимо изучить параметр OperationStatus в функции обратного вызова.
Для отмены ожидающей операции обратного вызова можно вызвать функцию WinBioCancel . Закрытие сеанса также неявно отменяет обратные вызовы для этого сеанса.
Подпрограмма обратного вызова должна иметь следующую сигнатуру:
VOID CALLBACK VerifyCallback(
__in_opt PVOID VerifyCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in BOOLEAN Match,
__in WINBIO_REJECT_DETAIL RejectDetail
);
Примеры
Следующая функция вызывает WinBioVerifyWithCallback , чтобы асинхронно определить, соответствует ли биометрическая выборка удостоверению текущего пользователя, выполнившего вход. Также включены подпрограмма обратного вызова VerifyCallback и вспомогащая функция GetCurrentUserIdentity. Ссылка на статическую библиотеку Winbio.lib и включение следующих файлов заголовков:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT VerifyWithCallback(BOOL bCancel, WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
// Declare variables.
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
WINBIO_IDENTITY identity = {0};
// 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 asynchronously.
wprintf_s(L"\n Calling WinBioVerifyWithCallback.\n");
hr = WinBioVerifyWithCallback(
sessionHandle, // Open session handle
&identity, // User SID or GUID
subFactor, // Sample sub-factor
VerifyCallback, // Callback function
NULL // Optional context
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioVerifyWithCallback failed. hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Swipe the sensor ...\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 the asynchronous identification 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 Hit any key to continue...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function is the callback for WinBioVerifyWithCallback.
// The function filters the response from the biometric subsystem and
// writes a result to the console window.
//
VOID CALLBACK VerifyCallback(
__in_opt PVOID VerifyCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in BOOLEAN Match,
__in WINBIO_REJECT_DETAIL RejectDetail
)
{
UNREFERENCED_PARAMETER(VerifyCallbackContext);
UNREFERENCED_PARAMETER(Match);
wprintf_s(L"\n VerifyCallback executing");
wprintf_s(L"\n Swipe processed for unit ID %d\n", UnitId);
// The identity could not be verified.
if (FAILED(OperationStatus))
{
wprintf_s(L"\n Verification failed for the following reason:");
if (OperationStatus == WINBIO_E_NO_MATCH)
{
wprintf_s(L"\n No match.\n");
}
else if (OperationStatus == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Bad capture.\n ");
wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
}
else
{
wprintf_s(L"VerifyCallback failed.");
wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
}
goto e_Exit;
}
// The user identity was verified.
wprintf_s(L"\n Fingerprint verified:\n");
e_Exit:
return;
}
//------------------------------------------------------------------------
// 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;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 7 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 R2 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbio.h (включая Winbio.h) |
| Библиотека | Winbio.lib |
| DLL | Winbio.dll |