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 函式來尋找單位識別符。
傳回值
如果函式成功，它會傳回S_OK。 如果函式失敗，它會傳回 HRESULT 值，指出錯誤。 可能的值包括 (但不限於) 下表中的這些值。 如需常見錯誤碼的清單，請參閱 一般 HRESULT 值。
| 傳回碼 | Description |
|---|---|
|
呼叫端沒有註冊的許可權。 |
|
會話句柄無效。 |
|
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) |
| 程式庫 | Winbio.lib |
| Dll | Winbio.dll |