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,但在 InstanceAttributes 参数的WDF_OBJECT_ATTRIBUTES结构中指定了大于 ULONG_MAX 上下文空间大小。
 

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

此方法还可能返回其他 NTSTATUS 值

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

注解

如果驱动程序正在创建提供程序的多个实例,则驱动程序必须在调用 WdfWmiInstanceCreate 之前调用 WdfWmiProviderCreate 来创建提供程序对象。 驱动程序通过将句柄放置在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 驱动程序中的 WMI

如果 InstanceConfig 指向的 WDF_WMI_INSTANCE_CONFIG 结构的 Register 成员为 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)
Library Wdf01000.sys (请参阅框架库 Versioning.)
IRQL <=DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf) KmdfIrql (kmdf) KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

IRP_MN_REGINFO

WDF_OBJECT_ATTRIBUTES

WDF_WMI_INSTANCE_CONFIG

WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG

WDF_WMI_PROVIDER_CONFIG

WDF_WMI_PROVIDER_CONFIG_INIT

WdfDeviceAssignMofResourceName

WdfWmiInstanceGetDevice

WdfWmiInstanceGetProvider

WdfWmiProviderCreate