Функция WinBioVerify (winbio.h)
Захватывает биометрическую выборку и определяет, соответствует ли образец указанному удостоверению пользователя. Начиная с Windows 10 сборки 1607 эта функция доступна для использования с мобильным образом.
Синтаксис
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
);
Параметры
[in] SessionHandle
Значение WINBIO_SESSION_HANDLE, определяющее открытый биометрический сеанс. Откройте синхронный дескриптор сеанса, вызвав WinBioOpenSession. Откройте асинхронный дескриптор сеанса, вызвав WinBioAsyncOpenSession.
[in] Identity
Указатель на структуру WINBIO_IDENTITY , содержащую GUID или идентификатор безопасности пользователя, предоставляющего биометрическую выборку.
[in] SubFactor
Значение WINBIO_BIOMETRIC_SUBTYPE , указывающее подфактор, связанный с биометрической выборкой. 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
- WINBIO_SUBTYPE_ANY
[out, optional] UnitId
Указатель на значение WINBIO_UNIT_ID , указывающее биометрическую единицу, которая выполнила проверку.
[out, optional] Match
Указатель на логическое значение, указывающее, соответствует ли захваченный пример удостоверению пользователя, указанному параметром Identity .
[out, optional] RejectDetail
Указатель на значение ULONG , содержащее дополнительные сведения о невозможности захвата биометрической выборки. Если запись выполнена успешно, этому параметру присваивается нулевое значение. Для захвата отпечатков пальцев определяются следующие значения:
- 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
Возвращаемое значение
Если функция выполняется успешно, она возвращает S_OK. Если функция завершается сбоем, она возвращает значение HRESULT , указывающее на ошибку. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице. Список распространенных кодов ошибок см. в разделе Общие значения HRESULT.
| Код возврата | Описание |
|---|---|
|
Недопустимый дескриптор сеанса. |
|
Неправильный аргумент SubFactor . |
|
Указатель, указанный параметрами UnitId, Identity, SubFactor или RejectDetail , не может иметь значение NULL. |
|
Не удалось записать биометрическую выборку. Для получения дополнительных сведений используйте значение RejectDetail . |
|
Не удалось завершить операцию, так как указанная биометрическая единица в настоящее время используется для транзакции регистрации (только системный пул). |
|
Биометрическая выборка не соответствует указанному сочетанию Identity и SubFactor . |
Комментарии
Если запись биометрической выборки завершается сбоем, параметр UnitId будет содержать номер единицы датчика, который пытался выполнить запись.
Вызовы этой функции с использованием системного пула будут блокироваться, пока приложение не получит фокус окна и пользователь не предоставит биометрическую выборку. Поэтому рекомендуется, чтобы приложение не вызывало WinBioVerify , пока оно не получит фокус. Способ получения фокуса зависит от типа приложения, которое вы пишете. Например, при создании приложения с графическим интерфейсом можно реализовать обработчик сообщений, который захватывает WM_ACTIVATE, WM_SETFOCUS или другое соответствующее сообщение. Если вы пишете приложение CUI, вызовите Метод GetConsoleWindow , чтобы получить дескриптор в окне консоли и передать этот дескриптор в функцию SetForegroundWindow , чтобы принудительно поместить окно консоли на передний план и назначить ему фокус. Если приложение выполняется в отсоединяемом процессе и не имеет окна или является службой Windows, используйте WinBioAcquireFocus и WinBioReleaseFocus для управления фокусом вручную.
Чтобы использовать WinBioVerify синхронно, вызовите функцию с дескриптором сеанса, созданным путем вызова WinBioOpenSession. Функция блокируется, пока операция не завершится или не возникнет ошибка.
Чтобы использовать WinBioVerify асинхронно, вызовите функцию с дескриптором сеанса, созданным путем вызова WinBioAsyncOpenSession. Платформа выделяет структуру WINBIO_ASYNC_RESULT и использует ее для возврата сведений об успешном или неудачном выполнении операции. Если операция выполнена успешно, платформа возвращает значение соответствия BOOLEAN во вложенной структуре Verify . Если операция завершается неудачно, платформа возвращает WINBIO_REJECT_DETAIL сведения в структуре Проверки . Структура WINBIO_ASYNC_RESULT возвращается в обратный вызов приложения или в очередь сообщений приложения в зависимости от значения, заданного в параметре NotificationMethod функции WinBioAsyncOpenSession :
- Если вы решили получать уведомления о завершении с помощью обратного вызова, необходимо реализовать функцию PWINBIO_ASYNC_COMPLETION_CALLBACK и задать для параметра NotificationMethodзначение WINBIO_ASYNC_NOTIFY_CALLBACK.
- Если вы решили получать уведомления о завершении с помощью очереди сообщений приложения, необходимо задать для параметра NotificationMethodзначение WINBIO_ASYNC_NOTIFY_MESSAGE. Платформа возвращает указатель WINBIO_ASYNC_RESULT на поле LPARAM сообщения окна.
Windows 7: Эту операцию можно выполнить асинхронно с помощью функции WinBioVerifyWithCallback . Функция проверяет входные аргументы и возвращает немедленно. Если входные аргументы недопустимы, функция возвращает код ошибки. В противном случае платформа запускает операцию в другом потоке. Когда асинхронная операция завершается или возникает ошибка, платформа отправляет результаты в функцию PWINBIO_VERIFY_CALLBACK , реализованную приложением.
Примеры
Следующая функция вызывает WinBioVerify , чтобы определить, соответствует ли биометрическая выборка удостоверению текущего пользователя, выполнившего вход. Также включена вспомогащая функция GetCurrentUserIdentity. Ссылка на статическую библиотеку Winbio.lib и включение следующих файлов заголовков:
- 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;
}
Требования
| Минимальная версия клиента | Windows 7 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 R2 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbio.h (включая Winbio.h) |
| Библиотека | Winbio.lib |
| DLL | Winbio.dll |