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

[アーティクル]
08/08/2023

DpWmiQueryDataBlock ルーチンは、1 つのインスタンスまたはデータブロックのすべてのインスタンスを返します。このルーチンは必須です。

構文

WMI_QUERY_DATABLOCK_CALLBACK WmiQueryDatablockCallback;

NTSTATUS WmiQueryDatablockCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG InstanceCount,
  [in, out] PULONG InstanceLengthArray,
  [in]      ULONG BufferAvail,
  [out]     PUCHAR Buffer
)
{...}

パラメーター

[in] DeviceObject

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

[in] Irp

IRP へのポインター。

[in] GuidIndex

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

[in] InstanceIndex

IRP_MN_QUERY_SINGLE_INSTANCE要求に応答して DpWmiQueryDataBlock が呼び出された場合、InstanceIndex は、クエリ対象の指定されたデータブロックのインスタンスを示す 0 から始まるインデックスを指定します。 IRP_MN_QUERY_ALL_DATA要求に応答して DpWmiQueryDataBlock が呼び出された場合、 InstanceIndex は 0 になります。

[in] InstanceCount

IRP_MN_QUERY_SINGLE_INSTANCE要求に応答して DpWmiQueryDataBlock が呼び出された場合、InstanceCount は 1 です。 IRP_MN_QUERY_ALL_DATA要求に応答して DpWmiQueryDataBlock が呼び出された場合、InstanceCount は返されるインスタンスの数です。

[in, out] InstanceLengthArray

呼び出し元が指定した 、ULONG 要素の InstanceCount サイズの配列へのポインター。ドライバーは、返された各インスタンスの長さを示すために、各配列要素を入力します。 BufferAvail が 0 の場合、InstanceLengthArray は NULL です。

[in] BufferAvail

Buffer でバッファー内のデータを受信できる最大バイト数を指定 します。この値が 0 の場合、呼び出し元は WmiCompleteRequest の呼び出しでドライバーに必要なバッファーサイズを指定するよう要求しています。詳細については、次の「解説」を参照してください。

[out] Buffer

インスタンスデータを受信するバッファーへのポインター。バッファーがすべてのデータを受け取るのに十分な大きさの場合、ドライバーは、各インスタンスが 8 バイト境界に配置された状態でインスタンスデータをバッファーに書き込みます。バッファーが小さすぎてすべてのデータを受信できない場合、ドライバーは必要なサイズに BufferUsed を設定して WmiCompleteRequest を呼び出します。

戻り値

DpWmiQueryDataBlock は 、STATUS_SUCCESSまたは次のようなエラー状態を返します。

ドライバーが要求をすぐに完了できない場合は、STATUS_PENDINGを返すことができます。

注釈

WMI は、ドライバーがIRP_MN_QUERY_SINGLE_INSTANCEまたは IRP_MN_QUERY_ALL_DATA要求に応答して WmiSystemControl を呼び出した後、ドライバーの DpWmiQueryDataBlock ルーチンを呼び出します。ドライバーは、その DpWmiQueryDataBlock ルーチンのアドレスを WmiSystemControl に渡すWMILIB_CONTEXT構造体に配置する必要があります。

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

WMILIB_CONTEXT構造体のGuidCount メンバーに基づいて、GuidIndex 値が 0 から GuidCount-1 の間にあることを確認します。
ドライバーが、指定されたデータブロックに削除のフラグが設定されていないことを確認します。ドライバーが、WMILIB_CONTEXT構造体に含まれている WMIGUIDREGINFO 構造体に WMIREG_FLAG_REMOVE_GUID フラグを最近指定した場合、削除が発生する前にクエリが到着する可能性があります。
InstanceIndex と InstanceCount の値が共に、データブロックのドライバーでサポートされている範囲内にあるデータブロックインスタンスの数を指定することを確認します。 InstanceIndex が 0 以外の場合、InstanceCount は 1 である必要があります。 InstanceIndex が 0 の場合、InstanceCount はサポートされているインスタンスの数を超えてはなりません。
Buffer と BufferAvail で記述されているバッファーが、データブロックのすべての要求されたインスタンスを保持するのに十分な大きさであることを確認します。各インスタンスは 8 バイト境界で開始する必要があり、各インスタンス内のデータ項目間に追加のパディングが存在する可能性があります。

バッファーにインスタンスデータを書き込む後、ドライバーは WmiCompleteRequest を呼び出して要求を完了します。 Buffer と BufferAvail で記述されたバッファーが 0 であるか、要求されたすべてのデータを受信するには小さすぎる場合、WmiCompleteRequest の呼び出しで Status パラメーターにSTATUS_BUFFER_TOO_SMALLを指定し、BufferUsed パラメーターに必要なバッファーサイズを指定する必要があります。

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

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