WinBioEnrollBegin 函数 (winbio.h)
启动生物识别注册序列并创建空生物识别模板。 从Windows 10版本 1607 开始，此函数可用于移动映像。
语法
HRESULT WinBioEnrollBegin(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[in] WINBIO_UNIT_ID UnitId
);
参数
[in] SessionHandle
标识打开的生物识别会话 的WINBIO_SESSION_HANDLE 值。 通过调用 WinBioOpenSession 打开同步会话句柄。 通过调用 WinBioAsyncOpenSession 打开异步会话句柄。
[in] SubFactor
一个WINBIO_BIOMETRIC_SUBTYPE值，用于提供有关注册的其他信息。 这必须是以下值之一：
- 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
[in] UnitId
标识生物识别单元 的WINBIO_UNIT_ID 值。 此值不能为零。 可以通过调用 WinBioEnumBiometricUnits 或 WinBioLocateSensor 函数来查找单元 ID。
返回值
如果函数成功，则返回S_OK。 如果函数失败，它将返回一个 指示错误的 HRESULT 值。 可能的值包括（但并不限于）下表中的项。 有关常见错误代码的列表，请参阅 通用 HRESULT 值。
| 返回代码 | 说明 |
|---|---|
|
调用方没有注册权限。 |
|
会话句柄无效。 |
|
SubFactor 参数不能等于 WINBIO_SUBTYPE_NO_INFORMATION 或 WINBIO_SUBTYPE_ANY，UnitId 参数不能等于零。 |
|
注册操作已在进行中，在给定时间只能进行一次注册。 |
|
生物识别单元正在使用并且已锁定。 |
注解
单个生物识别注册需要从一个用户收集多个样本。 在任何时候只能进行一次注册操作，并且适用于单个注册的所有生物识别样本都必须由同一传感器生成。 此传感器由 UnitId 参数指定。
使用系统池中的生物识别单元注册的任何应用程序在调用 WinBioEnrollBegin 时都必须具有窗口焦点。 否则，调用将阻止，直到应用程序获取窗口焦点，并且用户提供了生物识别示例。 因此，我们建议应用程序在获得焦点之前不要调用 WinBioEnrollBegin 。 获取焦点的方式取决于正在编写的应用程序类型。 例如，如果要创建 GUI 应用程序，则可以实现捕获WM_ACTIVATE、WM_SETFOCUS或其他相应消息的消息处理程序。 如果要编写 CUI 应用程序，请调用 GetConsoleWindow 以检索控制台窗口的句柄，并将该句柄传递给 SetForegroundWindow 函数，以强制控制台窗口进入前台并为其分配焦点。 如果应用程序在分离进程中运行，并且没有窗口或是 Windows 服务，请使用 WinBioAcquireFocus 和 WinBioReleaseFocus 手动控制焦点。
若要以同步方式使用 WinBioEnrollBegin ，请使用通过调用 WinBioOpenSession 创建的会话句柄调用 函数。 函数将一直阻止，直到操作完成或遇到错误。
若要异步使用 WinBioEnrollBegin ，请使用通过调用 WinBioAsyncOpenSession 创建的会话句柄调用函数。 框架分配 WINBIO_ASYNC_RESULT 结构，并使用它返回有关操作成功或失败的信息。 如果操作成功，框架将在嵌套的 EnrollBegin 结构中返回WINBIO_BIOMETRIC_SUBTYPE信息。 如果操作不成功，框架将返回错误信息。 WINBIO_ASYNC_RESULT结构将返回到应用程序回调或应用程序消息队列，具体取决于在 WinBioAsyncOpenSession 函数的 NotificationMethod 参数中设置的值：
- 如果选择使用回调接收完成通知，则必须实现 PWINBIO_ASYNC_COMPLETION_CALLBACK 函数并将 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_CALLBACK。
- 如果选择使用应用程序消息队列接收完成通知，则必须将 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_MESSAGE。 框架返回指向窗口消息的 LPARAM 字段的WINBIO_ASYNC_RESULT指针。
示例
以下函数在系统池中注册生物识别模板。 它调用 WinBioEnrollBegin 来启动注册序列。 链接到 Winbio.lib 静态库并包含以下头文件：
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT EnrollSysPool(
BOOL discardEnrollment,
WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
HRESULT hr = S_OK;
WINBIO_IDENTITY identity = {0};
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
BOOLEAN isNewTemplate = TRUE;
// 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. ");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
// Locate a sensor.
wprintf_s(L"\n Swipe your finger on the sensor...\n");
hr = WinBioLocateSensor( sessionHandle, &unitId);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Begin the enrollment sequence.
wprintf_s(L"\n Starting enrollment sequence...\n");
hr = WinBioEnrollBegin(
sessionHandle, // Handle to open biometric session
subFactor, // Finger to create template for
unitId // Biometric unit ID
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnrollBegin failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Capture enrollment information by swiping the sensor with
// the finger identified by the subFactor argument in the
// WinBioEnrollBegin function.
for (int swipeCount = 1;; ++swipeCount)
{
wprintf_s(L"\n Swipe the sensor to capture %s sample.",
(swipeCount == 1)?L"the first":L"another");
hr = WinBioEnrollCapture(
sessionHandle, // Handle to open biometric session
&rejectDetail // [out] Failure information
);
wprintf_s(L"\n Sample %d captured from unit number %d.",
swipeCount,
unitId);
if (hr == WINBIO_I_MORE_DATA)
{
wprintf_s(L"\n More data required.\n");
continue;
}
if (FAILED(hr))
{
if (hr == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Error: Bad capture; reason: %d",
rejectDetail);
continue;
}
else
{
wprintf_s(L"\n WinBioEnrollCapture failed. hr = 0x%x", hr);
goto e_Exit;
}
}
else
{
wprintf_s(L"\n Template completed.\n");
break;
}
}
// Discard the enrollment if the appropriate flag is set.
// Commit the enrollment if it is not discarded.
if (discardEnrollment == TRUE)
{
wprintf_s(L"\n Discarding enrollment...\n\n");
hr = WinBioEnrollDiscard( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
}
goto e_Exit;
}
else
{
wprintf_s(L"\n Committing enrollment...\n");
hr = WinBioEnrollCommit(
sessionHandle, // Handle to open biometric session
&identity, // WINBIO_IDENTITY object for the user
&isNewTemplate); // Is this a new template
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnrollCommit failed. hr = 0x%x\n", hr);
goto e_Exit;
}
}
e_Exit:
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L" Press any key to continue...");
_getch();
return hr;
}
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 7 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 R2 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | winbio.h (包括 Winbio.h) |
| Library | Winbio.lib |
| DLL | Winbio.dll |