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定数」を参照してください。

WINBIO_PROPERTY_TYPE_ACCOUNT値は、Windows 10 以降でサポートされています。

[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
特定のユーザー アカウントのスパム対策ポリシーの値を格納します。 プロパティ操作は、 PropertyBuffer パラメーターが WINBIO_ANTI_SPOOF_POLICY 構造体として指すバッファーで返されます。 この値は、Windows 10 以降でサポートされています。
 

これらのプロパティの詳細については、「 WINBIO_PROPERTY定数」を参照してください。

[in, optional] UnitId

生体認証ユニットを識別する WINBIO_UNIT_ID 値。 単位識別子を見つけるには、 WinBioEnumBiometricUnits または WinBioLocateSensor 関数を 呼び出します。

PropertyId パラメーターの値として WINBIO_PROPERTY_ANTI_SPOOF_POLICY を指定する場合は、UnitId パラメーターに 0 を指定します。 PropertyId パラメーターで他のプロパティを指定した場合、UnitId パラメーターに 0 を指定することはできません。

[in, optional] Identity

PropertyId パラメーターの値として WINBIO_PROPERTY_ANTI_SPOOF_POLICY を指定した場合に、アンチスポフティング ポリシーを取得するアカウントの SID を提供するWINBIO_IDENTITY構造体。

PropertyId パラメーターに他の値を指定する場合、Identity パラメーターは NULL である必要があります。

[in, optional] SubFactor

予約済み。 これは WINBIO_SUBTYPE_NO_INFORMATIONする必要があります。

PropertyBuffer

プロパティ値を受け取るバッファーへのポインターのアドレス。 さまざまなプロパティのこのバッファーの内容については、 PropertyId パラメーターのプロパティ値の説明を参照してください。

[out, optional] PropertyBufferSize

PropertyBuffer パラメーターが指すバッファーのサイズをバイト単位で受け取る変数へのポインター。

戻り値

関数が成功した場合は、S_OK を返します。 関数が失敗した場合は、エラーを示す HRESULT 値を返します。 有効な値を次の表に示しますが、これ以外にもあります。 一般的なエラー コードの一覧については、「 共通の HRESULT 値」を参照してください。

リターン コード 説明
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 を同期的に使用するときにメモリ リークを防ぐには、バッファーに含まれるデータの使用が完了したときに PropertyBuffer パラメーターが指すメモリを解放するために WinBioFree を呼び出す必要があります。

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構造体とプロパティ バッファーは 1 つのメモリ ブロックを占有するため、アプリケーションは WINBIO_ASYNC_RESULT 構造体のアドレスのみを WinBioFree に渡す必要があります。 この方法 で WinBioFree を呼び出すと、 WinBioFree は WINBIO_ASYNC_RESULT 構造体とプロパティ バッファーの両方を自動的に解放します。 この場合、プロパティ バッファーを個別に解放しようとすると、アプリケーションは応答を停止します。

要件

要件 値
サポートされている最小のクライアント Windows 7 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 R2 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winbio.h (Winbio.h を含む)
Library Winbio.lib
[DLL] Winbio.dll

こちらもご覧ください

WinBioFree

WinBioSetProperty