winBioEnrollCapture 函式 (winbio.h)
擷取生物特徵辨識範例，並將其新增至範本。 從 Windows 10 組建 1607 開始，此函式可用來搭配行動映射使用。
語法
HRESULT WinBioEnrollCapture(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[out, optional] WINBIO_REJECT_DETAIL *RejectDetail
);
參數
[in] SessionHandle
識別開放式生物特徵辨識會話 的WINBIO_SESSION_HANDLE 值。 呼叫 WinBioOpenSession 以開啟同步會話句柄。 呼叫 WinBioAsyncOpenSession 來開啟異步會話句柄。
[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 值。
| 傳回碼 | Description |
|---|---|
|
不允許呼叫帳戶執行註冊。 |
|
會話句柄無效。 |
|
RejectDetail 參數指定的指標不可以是 NULL。 |
|
無法擷取範例。 如需詳細資訊，請使用 RejectDetail 值。 |
|
生物特徵辨識單位正在使用中且已鎖定。 |
|
比對引擎需要一或多個額外的範例，才能產生可靠的範本。 您應該更新指示給使用者以提交更多範例，並再次呼叫 WinBioEnrollCapture 。 |
備註
在系統集區中使用生物特徵辨識單位註冊的任何應用程式，在呼叫 WinBioEnrollBegin 時，都必須有窗口焦點。 如果沒有，則呼叫會封鎖，直到應用程式取得窗口焦點，且使用者已提供生物特徵辨識範例為止。 因此，建議您在取得焦點之前，您的應用程式不會呼叫 WinBioEnrollBegin 。 取得焦點的方式取決於您正在撰寫的應用程式類型。 例如，如果您要建立 GUI 應用程式，您可以實作擷取WM_ACTIVATE、WM_SETFOCUS或其他適當訊息的訊息處理程式。 如果您要撰寫 CUI 應用程式，請呼叫 GetConsoleWindow 以擷取控制台視窗的句柄，並將該句柄傳遞給 SetForegroundWindow 函式，以強制控制台窗口進入前景並指派焦點。 如果您的應用程式是在中斷鏈接的進程中執行，而且沒有視窗或 Windows 服務，請使用 WinBioAcquireFocus 和 WinBioReleaseFocus 手動控制焦點。
若要同步使用 WinBioEnrollCapture ，請使用呼叫 WinBioOpenSession 所建立的會話句柄呼叫 函式。 函式會封鎖作業完成或發生錯誤為止。
若要以異步方式使用 WinBioEnrollCapture ，請使用呼叫 WinBioAsyncOpenSession 所建立的會話句柄來呼叫 函式。 架構會配置 WINBIO_ASYNC_RESULT 結構，並用它來傳回作業成功或失敗的相關信息。 如果作業失敗，架構會 傳回巢 狀 EnrollCapture 結構中WINBIO_REJECT_DETAIL資訊。 WINBIO_ASYNC_RESULT結構會根據您在 WinBioAsyncOpenSession 函式的 NotificationMethod 參數中設定的值，傳回至應用程式回呼或應用程式訊息佇列：
- 如果您選擇使用回呼接收完成通知，則必須實作 PWINBIO_ASYNC_COMPLETION_CALLBACK 函式，並將 NotificationMethod 參數設定為 WINBIO_ASYNC_NOTIFY_CALLBACK。
- 如果您選擇使用應用程式消息佇列接收完成通知，則必須將 NotificationMethod 參數設定為 WINBIO_ASYNC_NOTIFY_MESSAGE。 架構會傳回視窗訊息之 LPARAM 欄位的WINBIO_ASYNC_RESULT指標。
Windows 7： 您可以使用 WinBioEnrollCaptureWithCallback 函式，以異步方式執行這項作業。 函式會驗證輸入自變數並立即傳回。 如果輸入自變數無效，函式會傳回錯誤碼。 否則，架構會在另一個線程上啟動作業。 當異步操作完成或發生錯誤時，架構會將結果傳送至應用程式所實作 的 PWINBIO_ENROLL_CAPTURE_CALLBACK 函式。
範例
下列函式會呼叫 WinBioEnrollCapture，在系統集區中註冊生物特徵辨識範本。 連結至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 |