WdfWmiInstanceCreate 函数（wdfwmi.h）

[仅适用于 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

指向调用方初始化 WDF_WMI_INSTANCE_CONFIG 结构的指针，该结构包含 WMI 数据提供程序实例的配置信息。

[in, optional] InstanceAttributes

指向调用方分配 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构包含新 WMI 实例对象的驱动程序提供的对象属性。（结构 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，但指定了 InstanceAttributesWDF_OBJECT_ATTRIBUTES 结构中大于ULONG_MAX的上下文空间大小。

有关 WdfWmiInstanceCreate 方法可能返回的其他返回值的列表，请参阅 Framework 对象创建错误。

此方法还可以返回其他NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

言论

如果驱动程序正在创建提供程序的多个实例，驱动程序必须调用 WdfWmiProviderCreate 才能调用 WdfWmiInstanceCreate来创建提供程序对象。驱动程序通过将提供程序对象的句柄放置在 WDF_WMI_INSTANCE_CONFIG 结构中，将提供程序对象的句柄传递给 WdfWmiInstanceCreate。（如果驱动程序提供提供程序对象句柄，则不使用 Device 参数，并且可以 NULL。）

如果驱动程序正在创建提供程序的单个实例，则无需在调用 WdfWmiInstanceCreate之前调用 WdfWmiInstanceCreate。在这种情况下，WdfWmiInstanceCreate 也会创建 WMI 提供程序对象。因此，驱动程序WDF_WMI_INSTANCE_CONFIG结构必须包含指向描述 WMI 数据提供程序的 WDF_WMI_PROVIDER_CONFIG 结构的指针。

框架指示 WMI 从驱动程序的物理设备对象的设备实例 ID（PDO）创建一个动态实例名称，应用程序可以使用该名称。（框架不支持 Windows 驱动程序模型（WDM）驱动程序在 IRP_MN_REGINFO 或 IRP_MN_REGINFO_EX 结构中设置的静态实例名称。

WMI 实例对象的父对象是 WMI 提供程序对象。驱动程序无法更改此父级，并且 ParentObject 成员或 WDF_OBJECT_ATTRIBUTES 结构必须 NULL。

驱动程序调用 WdfWmiInstanceCreate后，它可以调用 WdfWmiInstanceGetProvider 以获取父提供程序对象的句柄，WdfWmiInstanceGetDevice 以获取提供程序设备的句柄。

有关 WdfWmiInstanceCreate 方法的详细信息，请参阅 Framework-Based Drivers中支持 WMI。

如果 RegisterWDF_WMI_INSTANCE_CONFIG 结构的成员 InstanceConfig 指向 TRUE，WdfWmiInstanceCreate 同步注册提供程序实例（即返回之前），如果此方法在 IRQL = PASSIVE_LEVEL调用，并在 IRQL > PASSIVE_LEVEL 调用此方法时异步注册。

例子

下面的代码示例来自 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
标头	wdfwmi.h （包括 Wdf.h）
库	Wdf01000.sys（请参阅框架库版本控制。
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）