WdfWmiInstanceCreate 関数 (wdfwmi.h)

[アーティクル]
03/05/2024

[KMDF にのみ適用]

WdfWmiInstanceCreate メソッドは、WMI データプロバイダーのインスタンスを表す WMI インスタンスオブジェクトを作成します。

構文

NTSTATUS WdfWmiInstanceCreate(
  [in]            WDFDEVICE                Device,
  [in]            PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES   InstanceAttributes,
  [out, optional] WDFWMIINSTANCE           *Instance
);

パラメーター

[in] Device

インスタンスが作成されるデバイスを表すフレームワークデバイスオブジェクトへのハンドル。デバイスオブジェクトをコントロールデバイスオブジェクトにすることはできません。

[in] InstanceConfig

WMI データプロバイダーのインスタンスの構成情報を含む、呼び出し元で初期化された WDF_WMI_INSTANCE_CONFIG 構造体へのポインター。

[in, optional] InstanceAttributes

新しい WMI インスタンスオブジェクトのドライバー指定のオブジェクト属性を含む呼び出し元によって割り当てられた WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 (構造体の ParentObject メンバーは NULL である必要があります)。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[out, optional] Instance

新しい WMI インスタンスオブジェクトへのハンドルを受け取る場所へのポインター。このパラメーターは省略可能であり、 NULL にすることができます。

戻り値

操作が成功した場合、WdfWmiInstanceCreate はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INFO_LENGTH_MISMATCH	InstanceConfig パラメーターが指すWDF_WMI_INSTANCE_CONFIG構造体のサイズが正しくありません。
STATUS_INSUFFICIENT_RESOURCES	メモリが不足していました。
STATUS_INTEGER_OVERFLOW	ドライバーは、WDF_WMI_INSTANCE_CONFIG構造体の UseContextForQuery メンバーを TRUE に設定しますが、InstanceAttributes パラメーターのWDF_OBJECT_ATTRIBUTES構造体でULONG_MAXよりも大きいコンテキスト空間サイズを指定しました。

WdfWmiInstanceCreate メソッドが返す可能性があるその他の戻り値の一覧については、「フレームワークオブジェクト作成エラー」を参照してください。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

注釈

ドライバーがプロバイダーの複数のインスタンスを作成している場合、ドライバーは WdfWmiProviderCreate を呼び出して、 WdfWmiInstanceCreate を呼び出す前にプロバイダーオブジェクトを作成する必要があります。ドライバーは、WDF_WMI_INSTANCE_CONFIG構造体にハンドルを配置することによって、プロバイダーオブジェクトのハンドルを WdfWmiInstanceCreate に渡します。 (ドライバーがプロバイダーオブジェクトハンドルを提供する場合、 Device パラメーターは使用されず、 NULL にすることができます)。

ドライバーがプロバイダーの 1 つのインスタンスを作成している場合、 WdfWmiInstanceCreate を呼び出す前に WdfWmiInstanceCreate を呼び出す必要はありません。この場合、 WdfWmiInstanceCreate は WMI プロバイダーオブジェクトも作成します。そのため、ドライバーのWDF_WMI_INSTANCE_CONFIG構造体には、WMI データプロバイダーを記述する WDF_WMI_PROVIDER_CONFIG 構造体へのポインターを含める必要があります。

フレームワークは、ドライバーの物理デバイスオブジェクト (PDO) のデバイスインスタンス ID から、アプリケーションで使用できる動的インスタンス名を作成するように WMI に指示します。 (フレームワークは、Windows ドライバーモデル (WDM) ドライバーが IRP_MN_REGINFO または IRP_MN_REGINFO_EX 構造で設定する静的インスタンス名をサポートしていません。

WMI インスタンスオブジェクトの親は WMI プロバイダーオブジェクトです。ドライバーはこの親を変更できません。 ParentObject メンバーまたは WDF_OBJECT_ATTRIBUTES 構造体は NULL である必要があります。

ドライバーは WdfWmiInstanceCreate を呼び出した後、 WdfWmiInstanceGetProvider を呼び出して親プロバイダーオブジェクトへのハンドルを取得し、WdfWmiInstanceGetDevice を呼び出してプロバイダーのデバイスへのハンドルを取得できます。

WdfWmiInstanceCreate メソッドの詳細については、「Framework-Based ドライバーでの WMI のサポート」を参照してください。

InstanceConfig が指すWDF_WMI_INSTANCE_CONFIG構造体の Register メンバーが TRUE の場合、このメソッドが IRQL = PASSIVE_LEVEL で呼び出され、IRQL > PASSIVE_LEVELで呼び出された場合は非同期的に、WdfWmiInstanceCreate はプロバイダーインスタンスを同期的に登録します (つまり、戻る前)。

例

PCIDRV サンプルドライバーのコード例を次に示します。この例では、デバイスの MOF リソース名を登録し、WDF_WMI_PROVIDER_CONFIG構造体とWDF_WMI_INSTANCE_CONFIG構造体を初期化し、 WdfWmiInstanceCreate を呼び出します。

NTSTATUS
PciDrvWmiRegistration(
    WDFDEVICE  Device
    )
{
    WDF_WMI_PROVIDER_CONFIG  providerConfig;
    WDF_WMI_INSTANCE_CONFIG  instanceConfig;
    NTSTATUS  status;
    DECLARE_CONST_UNICODE_STRING(mofRsrcName, MOFRESOURCENAME);

    status = WdfDeviceAssignMofResourceName(
                                            Device,
                                            &mofRsrcName
                                            );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    WDF_WMI_PROVIDER_CONFIG_INIT(
                                 &providerConfig,
                                 &PCIDRV_WMI_STD_DATA_GUID
                                 );
    providerConfig.MinInstanceBufferSize = sizeof(PCIDRV_WMI_STD_DATA);

    WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG(
                                                 &instanceConfig,
                                                 &providerConfig
                                                 );
    instanceConfig.Register = TRUE;
    instanceConfig.EvtWmiInstanceQueryInstance = EvtWmiDeviceInfoQueryInstance;
    instanceConfig.EvtWmiInstanceSetInstance = EvtWmiDeviceInfoSetInstance;

    status = WdfWmiInstanceCreate(
                                  Device,
                                  &instanceConfig,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  WDF_NO_HANDLE
                                  );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return status;
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfwmi.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)