Функция WinBioIdentify (winbio.h)
Записывает биометрический образец и определяет, соответствует ли он существующему биометрического шаблона. Начиная с Windows 10 сборки 1607 эта функция доступна для использования с мобильным образом.
Синтаксис
HRESULT WinBioIdentify(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[out, optional] WINBIO_UNIT_ID *UnitId,
[out, optional] WINBIO_IDENTITY *Identity,
[out, optional] WINBIO_BIOMETRIC_SUBTYPE *SubFactor,
[out, optional] WINBIO_REJECT_DETAIL *RejectDetail
);
Параметры
[in] SessionHandle
Значение WINBIO_SESSION_HANDLE , определяющее открытый биометрический сеанс. Откройте синхронный дескриптор сеанса, вызвав WinBioOpenSession. Откройте асинхронный дескриптор сеанса, вызвав WinBioAsyncOpenSession.
[out, optional] UnitId
Указатель на значение ULONG , указывающее биометрическую единицу, используемую для идентификации.
[out, optional] Identity
Указатель на структуру WINBIO_IDENTITY , которая получает ИДЕНТИФИКАТОР GUID или ИДЕНТИФИКАТОР пользователя, предоставляющего биометрический образец.
[out, optional] SubFactor
Указатель на WINBIO_BIOMETRIC_SUBTYPE значение, которое получает подфактор, связанный с биометрической выборкой. Дополнительные сведения см. в разделе "Примечания".
[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.
| Код возврата | Описание |
|---|---|
|
Недопустимый дескриптор сеанса. |
|
Указатель, заданный параметрами UnitId, Identity, SubFactor или RejectDetail , не может иметь значение NULL. |
|
Не удалось записать образец. Для получения дополнительных сведений используйте значение RejectDetail . |
|
Не удалось завершить операцию, так как биометрическая единица в настоящее время используется для транзакции регистрации (только системный пул). |
|
Биометрический образец не соответствует ни одному из сохраненных в базе данных. |
Комментарии
Значение, возвращаемое в параметре SubFactor , указывает подфактор, связанный с биометрической выборкой. Windows Biometric Framework (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
Чтобы использовать WinBioIdentify асинхронно, вызовите функцию с дескриптором сеанса, созданным путем вызова WinBioAsyncOpenSession. Платформа выделяет структуру WINBIO_ASYNC_RESULT и использует ее для возврата сведений об успешном или неудачном выполнении операции. Если операция выполнена успешно, платформа возвращает WINBIO_IDENTITY и WINBIO_BIOMETRIC_SUBTYPE сведения во вложенной структуре Identify . Если операция завершается неудачно, платформа возвращает 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: Эту операцию можно выполнить асинхронно с помощью функции WinBioIdentifyWithCallback . Функция проверяет входные аргументы и возвращает немедленно. Если входные аргументы недопустимы, функция возвращает код ошибки. В противном случае платформа запускает операцию в другом потоке. Когда асинхронная операция завершается или возникает ошибка, платформа отправляет результаты в функцию PWINBIO_IDENTIFY_CALLBACK , реализованную приложением.
Примеры
Следующая функция вызывает WinBioEnumEnrollments для перечисления биометрических под факторов, зарегистрированных для шаблона, и вызывает WinBioIdentify для получения объекта WINBIO_IDENTITY , который идентифицирует пользователя. Ссылка на статическую библиотеку Winbio.lib и включение следующих файлов заголовков:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT EnumEnrollments( )
{
// Declare variables.
HRESULT hr = S_OK;
WINBIO_IDENTITY identity = {0};
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
PWINBIO_BIOMETRIC_SUBTYPE subFactorArray = NULL;
WINBIO_BIOMETRIC_SUBTYPE SubFactor = 0;
SIZE_T subFactorCount = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
WINBIO_BIOMETRIC_SUBTYPE subFactor = WINBIO_SUBTYPE_NO_INFORMATION;
// 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;
}
// Locate the biometric sensor and retrieve a WINBIO_IDENTITY object.
wprintf_s(L"\n Calling WinBioIdentify - Swipe finger on sensor...\n");
hr = WinBioIdentify(
sessionHandle, // Session handle
&unitId, // Biometric unit ID
&identity, // User SID
&subFactor, // Finger sub factor
&rejectDetail // Rejection information
);
wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
if (FAILED(hr))
{
if (hr == WINBIO_E_UNKNOWN_ID)
{
wprintf_s(L"\n Unknown identity.\n");
}
else if (hr == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
}
else
{
wprintf_s(L"\n WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
}
goto e_Exit;
}
// Retrieve the biometric sub-factors for the template.
hr = WinBioEnumEnrollments(
sessionHandle, // Session handle
unitId, // Biometric unit ID
&identity, // Template ID
&subFactorArray, // Subfactors
&subFactorCount // Count of subfactors
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnumEnrollments failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Print the sub-factor(s) to the console.
wprintf_s(L"\n Enrollments for this user on Unit ID %d:", unitId);
for (SIZE_T index = 0; index < subFactorCount; ++index)
{
SubFactor = subFactorArray[index];
switch (SubFactor)
{
case WINBIO_ANSI_381_POS_RH_THUMB:
wprintf_s(L"\n RH thumb\n");
break;
case WINBIO_ANSI_381_POS_RH_INDEX_FINGER:
wprintf_s(L"\n RH index finger\n");
break;
case WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER:
wprintf_s(L"\n RH middle finger\n");
break;
case WINBIO_ANSI_381_POS_RH_RING_FINGER:
wprintf_s(L"\n RH ring finger\n");
break;
case WINBIO_ANSI_381_POS_RH_LITTLE_FINGER:
wprintf_s(L"\n RH little finger\n");
break;
case WINBIO_ANSI_381_POS_LH_THUMB:
wprintf_s(L"\n LH thumb\n");
break;
case WINBIO_ANSI_381_POS_LH_INDEX_FINGER:
wprintf_s(L"\n LH index finger\n");
break;
case WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER:
wprintf_s(L"\n LH middle finger\n");
break;
case WINBIO_ANSI_381_POS_LH_RING_FINGER:
wprintf_s(L"\n LH ring finger\n");
break;
case WINBIO_ANSI_381_POS_LH_LITTLE_FINGER:
wprintf_s(L"\n LH little finger\n");
break;
default:
wprintf_s(L"\n The sub-factor is not correct\n");
break;
}
}
e_Exit:
if (subFactorArray!= NULL)
{
WinBioFree(subFactorArray);
subFactorArray = NULL;
}
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 7 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 R2 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbio.h (включая Winbio.h) |
| Библиотека | Winbio.lib |
| DLL | Winbio.dll |