wdfwmiInstanceCreate 函数 (wdfwmi.h)

项目
02/29/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

指向调用方初始化 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 方法可能返回的其他返回值的列表，请参阅框架对象创建错误。

此方法还可能返回其他 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 (请参阅框架库版本控制.)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)