WinBioGetProperty 函式 (winbio.h)

  • 發行項

擷取會話、單位或範本屬性。 從 Windows 10 組建 1607 開始，此函式可用於行動映射。

語法

HRESULT WinBioGetProperty(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_PROPERTY_TYPE     PropertyType,
  [in]            WINBIO_PROPERTY_ID       PropertyId,
  [in, optional]  WINBIO_UNIT_ID           UnitId,
  [in, optional]  WINBIO_IDENTITY          *Identity,
  [in, optional]  WINBIO_BIOMETRIC_SUBTYPE SubFactor,
                  PVOID                    *PropertyBuffer,
  [out, optional] SIZE_T                   *PropertyBufferSize
);

參數

[in] SessionHandle

識別開放式生物特徵辨識會話 的WINBIO_SESSION_HANDLE 值。 呼叫 WinBioOpenSession 來開啟同步會話句柄。 呼叫 WinBioAsyncOpenSession 來開啟異步會話句柄。

[in] PropertyType

指定屬性資訊來源 的WINBIO_PROPERTY_TYPE 值。 目前必須 WINBIO_PROPERTY_TYPE_UNIT 或 WINBIO_PROPERTY_TYPE_ACCOUNT。 如需屬性類型的詳細資訊，請參閱 WINBIO_PROPERTY_TYPE常數。

從 Windows 10 開始，支援WINBIO_PROPERTY_TYPE_ACCOUNT值。

[in] PropertyId

指定您要查詢之屬性 的WINBIO_PROPERTY_ID 值。 可以取得下列值。

值 意義
WINBIO_PROPERTY_SAMPLE_HINT
 估計完成註冊範本所需的良好生物特徵辨識樣本數目上限。 屬性查詢的結果會傳回至 PropertyBuffer 參數指向的緩衝區中，做為包含提示的 ULONG 值。
WINBIO_PROPERTY_EXTENDED_SENSOR_INFO
包含連接到特定生物特徵辨識單位之感測器元件之功能和屬性的擴充資訊。 屬性查詢的結果會傳回至 PropertyBuffer 參數指向的緩衝區中，做為 WINBIO_EXTENDED_SENSOR_INFO 結構。 從 Windows 10 開始支援此值。
WINBIO_PROPERTY_EXTENDED_ENGINE_INFO
包含連接到特定生物特徵辨識單位之引擎元件之功能和屬性的擴充資訊。 屬性查詢的結果會傳回至 PropertyBuffer 參數指向的緩衝區中，做為 WINBIO_EXTENDED_ENGINE_INFO 結構。 從 Windows 10 開始支援此值。
WINBIO_PROPERTY_EXTENDED_STORAGE_INFO
包含連接到特定生物特徵辨識單位之儲存元件之功能和屬性的擴充資訊。 屬性查詢的結果會傳回至 PropertyBuffer 參數點做為 WINBIO_EXTENDED_STORAGE_INFO 結構的緩衝區。 從 Windows 10 開始支援此值。
WINBIO_PROPERTY_EXTENDED_ENROLLMENT_STATUS
包含特定生物特徵辨識單位上進行中註冊狀態的擴充資訊。 屬性查詢的結果會傳回至 PropertyBuffer 參數指向的緩衝區中，做為 WINBIO_EXTENDED_ENROLLMENT_STATUS 結構。 如果生物特徵辨識單位上沒有任何註冊正在進行，則傳回結構的 TemplateStatus 成員的值為 WINBIO_E_INVALID_OPERATION。 從 Windows 10 開始支援此值。
WINBIO_PROPERTY_ANTI_SPOOF_POLICY
包含特定用戶帳戶的反詐騙原則值。 屬性作業會在 屬性Buffer 參數指向的緩衝區中傳回為 WINBIO_ANTI_SPOOF_POLICY 結構。 從 Windows 10 開始支援此值。
 

如需這些屬性的詳細資訊，請參閱 WINBIO_PROPERTY常數。

[in, optional] UnitId

識別生物特徵辨識單位 的WINBIO_UNIT_ID 值。 您可以呼叫 WinBioEnumBiometricUnits 或 WinBioLocateSensor 函式來尋找單位識別符。

如果您將 WINBIO_PROPERTY_ANTI_SPOOF_POLICY 指定為 PropertyId 參數的值，請為 UnitId 參數指定 0。 如果您使用 PropertyId 參數指定任何其他屬性，則無法為 UnitId 參數指定 0。

[in, optional] Identity

WINBIO_IDENTITY 結構，如果您指定WINBIO_PROPERTY_ANTI_SPOOF_POLICY做為 PropertyId 參數的值，則提供您想要取得反詐騙原則之帳戶的 SID。

如果您為 PropertyId 參數指定任何其他值， Identity 參數必須是 NULL。

[in, optional] SubFactor

保留的。 這必須 WINBIO_SUBTYPE_NO_INFORMATION。

PropertyBuffer

接收屬性值之緩衝區的指標位址。 如需不同屬性之此緩衝區內容的相關信息，請參閱 PropertyId 參數的屬性值描述。

[out, optional] PropertyBufferSize

接收 PropertyBuffer 參數所指向之緩衝區大小位元組之變數的指標。

傳回值

如果函式成功，它會傳回S_OK。 如果函式失敗，它會傳回 HRESULT 值，指出錯誤。 可能的值包括 (但不限於) 下表中的這些值。 如需常見錯誤碼的清單，請參閱 一般 HRESULT 值。

傳回碼 Description
E_HANDLE
 SessionHandle 參數指定的會話句柄無效。
E_POINTER
 Identity、PropertyBuffer 或 PropertyBufferSize 自變數不可以是 NULL。
E_INVALIDARG
 UnitId、Identity 或 SubFactor 自變數不正確。
WINBIO_E_INVALID_PROPERTY_TYPE
 PropertyType 自變數的值不正確。
WINBIO_E_INVALID_PROPERTY_ID
 PropertyId 自變數的值不正確。
WINBIO_E_LOCK_VIOLATION
 呼叫端嘗試查詢位於鎖定區域內的屬性。
WINBIO_E_UNSUPPORTED_PROPERTY
 正在查詢的物件不支援指定的屬性。
WINBIO_E_ENROLLMENT_IN_PROGRESS
 作業無法完成，因為指定的生物特徵辨識單位目前正在用於註冊交易 (系統集區) 。

備註

若要以同步方式使用 WinBioGetProperty ，請使用呼叫 WinBioOpenSession 所建立的會話句柄呼叫函式。 函式會封鎖直到作業完成或發生錯誤為止。 若要在同步使用 WinBioGetProperty 時防止記憶體流失，您必須呼叫 WinBioFree ，以在您使用緩衝區中包含的數據完成時，釋放 PropertyBuffer 參數所指向的記憶體。

若要以異步方式使用 WinBioGetProperty ，請使用呼叫 WinBioAsyncOpenSession 所建立的會話句柄呼叫函式。 架構會配置 WINBIO_ASYNC_RESULT 結構，並用它來傳回作業成功或失敗的相關信息。 如果作業成功，架構會傳回巢狀 GetProperty 結構中的資訊。 WINBIO_ASYNC_RESULT 結構會根據您在 WinBioAsyncOpenSession 函式的 NotificationMethod 參數中設定的值，傳回至應用程式回呼或應用程式訊息佇列：

  • 如果您選擇使用回呼接收完成通知，則必須實作 PWINBIO_ASYNC_COMPLETION_CALLBACK 函式，並將 NotificationMethod 參數設定為 WINBIO_ASYNC_NOTIFY_CALLBACK。
  • 如果您選擇使用應用程式消息佇列接收完成通知，您必須將 NotificationMethod 參數設定為 WINBIO_ASYNC_NOTIFY_MESSAGE。 架構會傳回視窗訊息之 LPARAM 欄位的WINBIO_ASYNC_RESULT指標。
若要避免在異步使用 WinBioGetProperty 時發生記憶體流失，您必須呼叫 WinBioFree ，以在完成使用之後釋放 WINBIO_ASYNC_RESULT 結構。 WINBIO_ASYNC_RESULT 結構和屬性緩衝區佔用單一記憶體區塊，因此您的應用程式只需要將WINBIO_ASYNC_RESULT結構的位址傳遞至 WinBioFree。 當您以這種方式呼叫 WinBioFree 時， WinBioFree 會自動釋放 WINBIO_ASYNC_RESULT 結構和屬性緩衝區。 如果您嘗試在此案例中個別釋放屬性緩衝區，應用程式會停止回應。

規格需求

需求 值
最低支援的用戶端 Windows 7 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 R2 [僅限傳統型應用程式]
目標平台 Windows
標頭 winbio.h (包含Winbio.h)
程式庫 Winbio.lib
Dll Winbio.dll

另請參閱

WinBioFree

WinBioSetProperty