WMI_EXECUTE_METHOD_CALLBACK コールバック関数 (wmilib.h)

[アーティクル]
02/27/2024

DpWmiExecuteMethod ルーチンは、データブロックに関連付けられたメソッドを実行します。このルーチンは省略可能です。

構文

WMI_EXECUTE_METHOD_CALLBACK WmiExecuteMethodCallback;

NTSTATUS WmiExecuteMethodCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG MethodId,
  [in]      ULONG InBufferSize,
  [in]      ULONG OutBufferSize,
  [in, out] PUCHAR Buffer
)
{...}

パラメーター

[in] DeviceObject

ドライバーの WDM DEVICE_OBJECT 構造体へのポインター。

[in] Irp

IRP へのポインター。

[in] GuidIndex

WmiSystemControl に渡されたWMILIB_CONTEXT構造でドライバーが提供する GUID の一覧に 0 から始まるインデックスを指定して、データブロックを指定します。

[in] InstanceIndex

GuidIndex で指定されたブロックに複数のインスタンスがある場合、InstanceIndex はインスタンスを識別する 0 から始まるインデックス値を指定します。

[in] MethodId

実行するメソッドの ID を指定します。ドライバーは、データブロック内の項目としてメソッド ID を定義します。

[in] InBufferSize

入力データのサイズをバイト単位で示します。入力データがない場合、 InBufferSize は 0 です。

[in] OutBufferSize

出力データのバッファーで使用できるバイト数を示します。

[in, out] Buffer

入力データ (存在する場合) を保持し、メソッドの出力データ (存在する場合) を受け取るバッファーへのポインター。バッファーが小さすぎてすべての出力データを受信できない場合、ドライバーは STATUS_BUFFER_TOO_SMALLを返し、必要なサイズで WmiCompleteRequest を呼び出します。

戻り値

DpWmiExecuteMethod は、STATUS_SUCCESSまたは次のような適切なエラーコードを返します。

注釈

WMI は、ドライバーがIRP_MN_EXECUTE_METHOD要求に応答して WmiSystemControl を呼び出した後、ドライバーの DpWmiExecuteMethod ルーチンを呼び出します。

ドライバーが DpWmiExecuteMethod ルーチンを実装する場合、ドライバーは WmiSystemControl に渡すWMILIB_CONTEXT構造体の ExecuteWmiMethod メンバーにルーチンのアドレスを配置する必要があります。ドライバーが DpWmiExecuteMethod ルーチンを実装していない場合は、 ExecuteWmiMethod を NULL に設定する必要があります。後者の場合、WMI は、IRP_MN_EXECUTE_METHOD要求に応答して呼び出し元に STATUS_INVALID_DEVICE_REQUEST を返します。

ドライバーは、すべての入力引数を検証する必要があります。具体的には、ドライバーは次の操作を行う必要があります。

GuidIndex の値が、WMILIB_CONTEXT構造体の GuidCount メンバーに基づいて、0 から GuidCount-1 の間にあることを確認します。
ドライバーで、指定されたデータブロックに削除のフラグが設定されていないことを確認します。ドライバーが、WMILIB_CONTEXT構造体に含まれている WMIGUIDREGINFO 構造体でWMIREG_FLAG_REMOVE_GUID フラグを最近指定した場合、削除が行われる前に追加の要求が到着する可能性があります。
InstanceIndex 値が、データブロックのドライバーでサポートされているインスタンスインデックスの範囲内にあることを確認します。
MethodId によって提供されるメソッド識別子が、指定したデータブロックの有効な識別子であり、呼び出し元がメソッドの実行を許可されていることを確認します。
Buffer と InBufferSize が、必要に応じて埋め込みを含め、指定したメソッドの入力パラメーターを格納するのに十分な大きさのバッファーを記述し、入力パラメーターが有効であることを確認します。
Buffer と OutBufferSize が、必要に応じて埋め込みを含め、指定されたメソッドの出力データを受信するのに十分な大きさのバッファーを記述していることを確認します。

スレッドコンテキストが開始ユーザーモードアプリケーションのコンテキストであると想定しないでください。上位レベルのドライバーによって変更された可能性があります。

指定したメソッドが、一連のカウンターの内容のフェッチやリセットなど、データ損失を引き起こす操作を実行する場合、ドライバーは操作を実行する前に出力バッファーサイズを検証する必要があります。これにより、ドライバーはSTATUS_BUFFER_TOO_SMALLを返し、カウンターを途中でリセットすることなく、より大きなバッファーを使用して要求を再送信できます。

メソッドを実行し、バッファーに出力データを書き込む後、ドライバーは WmiCompleteRequest を呼び出して要求を完了します。

このルーチンはページング可能です。

このルーチンの実装の詳細については、「 WmiSystemControl を呼び出して WMI IRP を処理する」を参照してください。