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

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

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 構造体で Flags を設定することで、特定のブロックの 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

ドライバーによって登録されるすべてのブロックのすべてのインスタンスのベース名として機能する、カウントされた 1 つの 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 ルーチンを呼び出します。ドライバーは、その DpWmiQueryReginfo ルーチンのアドレスを WmiSystemControl に渡すWMILIB_CONTEXT構造体に配置する必要があります。

ドライバーがWMIREG_ACTION_REGISTER、WMIREG_ACTION_REREGISTER、またはWMIREG_ACTION_UPDATEを使用して IoWMIRegistrationControl を呼び出した後、WMI は 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 を処理する」を参照してください。