WinBioControlUnitPrivileged 関数 (winbio.h)

  • [アーティクル]

呼び出し元が生体認証ユニットに対して特権ベンダー定義の制御操作を実行できるようにします。 Windows 10 ビルド 1607 以降では、この関数をモバイル イメージで使用できます。 クライアントは、この関数を呼び出して、昇格されたアクセス権を必要とする拡張ベンダー操作を実行する必要があります。 特権が必要ない場合、クライアントは WinBioControlUnit 関数を呼び出すことができます。

構文

HRESULT WinBioControlUnitPrivileged(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_UNIT_ID        UnitId,
  [in]            WINBIO_COMPONENT      Component,
  [in]            ULONG                 ControlCode,
                  PUCHAR                SendBuffer,
  [in]            SIZE_T                SendBufferSize,
                  PUCHAR                ReceiveBuffer,
  [in]            SIZE_T                ReceiveBufferSize,
                  SIZE_T                *ReceiveDataSize,
  [out, optional] ULONG                 *OperationStatus
);

パラメーター

[in] SessionHandle

開いている生体認証セッションを識別する WINBIO_SESSION_HANDLE 値。 WinBioOpenSession を呼び出して同期セッション ハンドルを開きます。 WinBioAsyncOpenSession を呼び出して非同期セッション ハンドルを開きます。

[in] UnitId

生体認証ユニットを識別する WINBIO_UNIT_ID 値。 この値は、 WinBioLockUnit 関数で以前に使用したユニット ID に対応している必要があります。

[in] Component

操作 を 実行する生体認証ユニット内のコンポーネントを指定するWINBIO_COMPONENT値。 これには、次のいずれかの値を指定できます。

値 意味
WINBIO_COMPONENT_SENSOR
 コマンドをセンサー アダプターに送信します。
WINBIO_COMPONENT_ENGINE
 コマンドをエンジン アダプターに送信します。
WINBIO_COMPONENT_STORAGE
 コマンドをストレージ アダプターに送信します。

[in] ControlCode

UnitId パラメーターで指定された生体認証ユニットと Component パラメーターで指定されたアダプターによって認識されるベンダー定義コード。

SendBuffer

Component パラメーターで指定されたアダプターに送信される制御情報を含むバッファーのアドレス。 バッファーの形式と内容はベンダー定義です。

[in] SendBufferSize

SendBuffer パラメーターで指定されたバッファーのサイズ (バイト単位)。

ReceiveBuffer

Component パラメーターで指定されたアダプターによって送信される情報を受信するバッファーのアドレス。 バッファーの形式と内容はベンダー定義です。

[in] ReceiveBufferSize

ReceiveBuffer パラメーターで指定されたバッファーのサイズ (バイト単位)。

ReceiveDataSize

ReceiveBufferパラメーターで指定されたバッファーに書き込まれたデータのサイズ (バイト単位) を含むSIZE_T値へのポインター。

[out, optional] OperationStatus

制御操作の結果を指定するベンダー定義の状態コードを含む整数へのポインター。

戻り値

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

リターン コード 説明
E_HANDLE
 セッション ハンドルが無効です。
E_INVALIDARG
 ControlCode パラメーターで指定された値が認識されません。
E_POINTER
 SendBuffer、ReceiveBuffer、ReceiveDataSize、OperationStatus パラメーターを NULL にすることはできません。
E_ACCESSDENIED
 呼び出し元に操作を実行するアクセス許可がないか、 WINBIO_FLAG_MAINTENANCEを使用してセッションが開かれていました。
E_INVALIDARG
 ControlCode パラメーターで指定された値が認識されません。
WINBIO_E_LOCK_VIOLATION
 UnitId パラメーターで指定された生体認証ユニットは、制御操作を実行する前にロックする必要があります。

注釈

プラグインを作成するベンダーは、特権を持つ拡張操作と、すべてのクライアントで使用できる拡張操作を決定する必要があります。 特権操作を実行するには、クライアント アプリケーションで WinBioControlUnitPrivileged 関数を呼び出す必要があります。 Windows 生体認証フレームワークでは、この関数を呼び出す適切なアクセス権を持つクライアントのみが許可されます。 特権を必要としない操作を実行するには、クライアントで WinBioControlUnit 関数を呼び出す必要があります。

WinBioControlUnitPrivileged を呼び出す前に、WinBioLockUnit を呼び出す必要があります。 WinBioLockUnit 関数は、ベンダー定義の操作を安全に実行できるロックされたリージョンを作成します。

この関数を正常に呼び出すには、 WINBIO_FLAG_MAINTENANCEを指定してセッション ハンドルが開かれている必要があります。 必要な特権を持つのは、管理者アカウントとローカル システム アカウントのみです。

WinBioControlUnitPrivileged を同期的に使用するには、WinBioOpenSession を呼び出して作成されたセッション ハンドルで 関数を呼び出します。 関数は、操作が完了するか、エラーが発生するまでブロックします。

WinBioControlUnitPrivileged を非同期で使用するには、WinBioAsyncOpenSession を呼び出して作成されたセッション ハンドルで 関数を呼び出します。 フレームワークは 、WINBIO_ASYNC_RESULT 構造体を割り当て、それを使用して操作の成功または失敗に関する情報を返します。 WINBIO_ASYNC_RESULT構造体は、WinBioAsyncOpenSession 関数の NotificationMethod パラメーターで設定した値に応じて、アプリケーション コールバックまたはアプリケーション メッセージ キューに返されます。

  • コールバックを使用して完了通知を受け取る場合は、 PWINBIO_ASYNC_COMPLETION_CALLBACK 関数を実装し、 NotificationMethod パラメーターを WINBIO_ASYNC_NOTIFY_CALLBACK に設定する必要があります。
  • アプリケーション メッセージ キューを使用して完了通知を受け取る場合は、 NotificationMethod パラメーターを WINBIO_ASYNC_NOTIFY_MESSAGE に設定する必要があります。 フレームワークは、ウィンドウ メッセージの LPARAM フィールドへのWINBIO_ASYNC_RESULT ポインターを返します。
メモリ リークを防ぐには、 WinBioFree を呼び出して 、WINBIO_ASYNC_RESULT 構造体の使用が完了した後で解放する必要があります。

要件

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

こちらもご覧ください

WinBioControlUnit

WinBioLockUnit