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

[アーティクル]
02/07/2025

DpWmiQueryReginfo ルーチンは、ドライバーによって登録されるデータブロックとイベントブロックに関する情報を提供します。このルーチンは必須です。

構文

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

パラメーター

[in] DeviceObject

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

[out] RegFlags

このパラメーターは、登録されているすべてのブロックの共通特性を示します。 RegFlags で設定されたフラグは、すべてのブロックに適用されます。ドライバーは、ブロックの WMIGUIDREGINFO 構造体に フラグ 設定することで、特定のブロックの RegFlags 補足できます。たとえば、ドライバーは regFlags でWMIREG_FLAG_EXPENSIVEをクリアが、特定のブロックを収集コストとして登録するように Flags に設定します。

ドライバーは、RegFlagsで次のいずれかのフラグを設定します。

WMIREG_FLAG_INSTANCE_BASENAME

InstanceNameでドライバーによって提供される基本名から静的インスタンス名を生成するように WMI に要求します。 WMI では、ベース名にカウンターを追加することでインスタンス名が生成されます。

WMIREG_FLAG_INSTANCE_PDO

PDO のデバイスインスタンス ID から静的インスタンス名を生成するように WMI に要求します。ドライバーがこのフラグを設定する場合は、ドライバーの AddDevice ルーチンに渡される PDO Pdo も設定する必要があります。 WMI は、PDO のデバイスインスタンスパスからインスタンス名を生成します。静的インスタンス名のベースとしてデバイスインスタンスパスを使用すると、このような名前が一意であることが保証されるため、効率的です。 WMI は、データコンシューマーが照会できるデータブロック内の項目として、インスタンスの "フレンドリ" 名を自動的に指定します。

ドライバーは、regFlags で次のフラグの 1 つ以上を設定することもできますが、通常は、ブロックの WMIGUIDREGINFO 構造体の フラグ で設定します。

WMIREG_FLAG_EVENT_ONLY_GUID

ブロックはイベントとしてのみ有効または無効にすることができ、クエリや設定はできません。このフラグがクリアされている場合は、ブロックを照会または設定することもできます。

WMIREG_FLAG_EXPENSIVE

データコンシューマーがデータブロックを初めて開いたときに IRP_MN_ENABLE_COLLECTION 要求を送信するように WMI に要求し、最後のデータコンシューマーがデータブロックを閉じたときに IRP_MN_DISABLE_COLLECTION 要求を要求します。このようなデータの収集がパフォーマンスに影響を与える場合は、データコンシューマーがブロックを開いて明示的に要求するまで、ドライバーがデータを収集する必要がないため、この方法をお勧めします。

WMIREG_FLAG_REMOVE_GUID

ブロックのサポートを削除するように WMI に要求します。このフラグは、登録情報を更新する要求 (Parameters.WMI.DataPath WMIUPDATE に設定されたIRP_MN_REGINFO または IRP_MN_REGINFO_EX) への応答でのみ有効です。

[out] InstanceName

ドライバーによって登録されるすべてのブロックのすべてのインスタンスのベース名として機能する、カウントされた単一の Unicode 文字列へのポインター。 WMI は、ExFreePoolを使用して文字列を解放します。 WMIREG_FLAG_INSTANCE_BASENAMEがクリアされている場合、InstanceName は無視されます。

[out] RegistryPath

ドライバーの DriverEntry ルーチンに渡されるレジストリパスを指定する、カウントされた Unicode 文字列へのポインターへのポインター。

[out] MofResourceName

ドライバーのバイナリイメージファイルにアタッチされている MOF リソースの名前を示す、カウントされた 1 つの Unicode 文字列へのポインター。通常、この文字列はドライバーによって定義された静的文字列になります。 WMI は、ドライバーがこのルーチンから戻った後、この文字列のコピーを作成します。この文字列は、ドライバーによって動的に割り当てられます。割り当てられた文字列の場合、WmiSystemControl が返された後に実行する必要がある文字列を解放ドライバーが担当します。ドライバーに MOF リソースがアタッチされていない場合は、MofResourceName 変更せずに残。

[out] Pdo

ドライバーの AddDevice ルーチンに渡される物理デバイスオブジェクト (PDO) へのポインター。 WMIREG_FLAG_INSTANCE_PDOが設定されている場合、WMI はこの PDO のデバイスインスタンスパスを静的インスタンス名の生成元のベースとして使用します。 WMIREG_FLAG_INSTANCE_PDOが明確な場合、WMI は Pdo 無視します。

戻り値

DpWmiQueryReginfo は常にSTATUS_SUCCESSを返します。

備考

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

WMI は、ドライバーがWMIREG_ACTION_REGISTER、WMIREG_ACTION_REREGISTER、またはWMIREG_ACTION_UPDATE IoWMIRegistrationControl を呼び出した後に IRP を送信します。 WMI は、ドライバーの代わりに IRP_MN_REGINFO と IRP_MN_REGINFO_EX の違いを透過的に処理します。

WMI は、ドライバーからそれ以上の情報を必要としないため、ドライバーが WMIREG_ACTION_DEREGISTER で IoWMIRegistrationControl 呼び出した後、IRP_MN_REGINFO または IRP_MN_REGINFO_EX 要求を送信しません。ドライバーは通常、IRP_MN_REMOVE_DEVICE 要求に応答してブロックの登録を解除します。

ドライバーは、個々のブロックに関する新規または更新された登録情報を提供するか、削除するブロックを示します。これは、WmiSystemControl に渡WMILIB_CONTEXT 構造体内にあります。ドライバーのレジストリパスと MOF リソース名を確立する最初の呼び出しの後、ドライバーの DpWmiQueryReginfo ルーチンは、ドライバーのすべてのブロックに共通するフラグを変更したり、インスタンス名の生成に使用する別のベース名文字列を指定したり、インスタンス名の基準を文字列から PDO のデバイスインスタンスパスに変更したりできます。

ドライバーは、STATUS_PENDINGを返したり、要求をブロックしたりしてはなりません。ドライバーは、DpWmiQueryReginfo ルーチンから WmiCompleteRequest 呼び出すか、WmiSystemControl が返された後に IoCompleteRequest 呼び出して、要求 完了してはなりません。

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

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

必要条件

要件	価値
ターゲットプラットフォームの	デスクトップ
ヘッダー	wmilib.h (Wmilib.h を含む)
IRQL	PASSIVE_LEVELで呼び出されます。

次の方法で共有