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

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

DpWmiFunctionControl ルーチンは、イベントの通知を有効または無効にし、ドライバーが収集コストの高いとして登録されているデータブロックのデータ収集を有効または無効にします。このルーチンは省略可能です。

構文

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

パラメーター

[in] DeviceObject

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

[in] Irp

IRP へのポインター。

[in] GuidIndex

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

[in] Function

有効または無効にする内容を指定します。 WmiEventControl はイベントを示し、WmiDataBlockControl は収集コストの高いブロック (つまり、ドライバーがブロックの登録に使用される WMIGUIDREGINFO 構造体のフラグにWMIREG_FLAG_EXPENSIVEするブロック) のデータ収集を示します。

[in] Enable

イベントまたはデータ収集を有効にする 場合は TRUE 、無効にするには FALSE を 指定します。

戻り値

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

注釈

WMI は、ドライバーが次のいずれかの要求に応答して WmiSystemControl を呼び出した後、ドライバーの DpWmiFunctionControl ルーチンを呼び出します。

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

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

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

WMILIB_CONTEXT構造体のGuidCount メンバーに基づいて、GuidIndex 値が 0 から GuidCount-1 の間にあることを確認します。
ドライバーが、指定されたデータブロックに削除のフラグが設定されていないことを確認します。ドライバーが、WMILIB_CONTEXT構造体に含まれている WMIGUIDREGINFO 構造体に WMIREG_FLAG_REMOVE_GUID フラグを最近指定した場合、削除が発生する前に追加の要求が到着する可能性があります。

最初のデータコンシューマーがブロックを有効にしたときに WMI が単一の有効化要求を送信し、最後のデータコンシューマーがブロックを無効にしたときに単一の無効化要求を送信するため、ドライバーがブロックに対してイベントまたはデータ収集が既に有効になっているかどうかをチェックする必要があります。 WMI は DpWmiFunctionControl を呼び出してブロックを無効にする呼び出しなしでブロックを有効にしません。

ブロックのイベントまたはデータ収集を有効または無効にすると、ドライバーは WmiCompleteRequest を呼び出して要求を完了します。

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

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