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 或 SID。
[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 值。
傳回碼 | Description |
---|---|
|
會話句柄無效。 |
|
UnitId、Identity、SubFactor 或 RejectDetail 參數指定的指標不能是 NULL。 |
|
無法擷取範例。 如需詳細資訊,請使用 RejectDetail 值。 |
|
無法完成作業,因為生物特徵辨識單位目前只用於註冊交易 (系統集區) 。 |
|
生物特徵辨識範例與資料庫中任何儲存的樣本不符。 |
備註
SubFactor 參數中傳回的值會指定與生物特徵辨識樣本相關聯的子因素。 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
若要以異步方式使用 WinBioIdentify ,請使用呼叫 WinBioAsyncOpenSession 所建立的會話句柄來呼叫函式。 架構會配置 WINBIO_ASYNC_RESULT 結構,並用它來傳回作業成功或失敗的相關信息。 如果作業成功,架構會傳回巢狀識別結構中的WINBIO_IDENTITY和WINBIO_BIOMETRIC_SUBTYPE資訊。 如果作業失敗,架構會傳回識別結構中的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: 您可以使用 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 |
標頭 | winbio.h (包含Winbio.h) |
程式庫 | Winbio.lib |
Dll | Winbio.dll |