Функция WdfWmiInstanceCreate (wdfwmi.h)

Статья
08/08/2023

[Относится только к 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	Неправильный размер структуры WDF_WMI_INSTANCE_CONFIG , на которую указывает параметр InstanceConfig .
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.
STATUS_INTEGER_OVERFLOW	Драйвер задает для элемента UseContextForQuery структуры WDF_WMI_INSTANCE_CONFIGзначение TRUE, но указывает размер контекстного пространства, превышающий ULONG_MAX в структуре WDF_OBJECT_ATTRIBUTES параметра InstanceAttributes.

Список других возвращаемых значений, которые может возвращать метод WdfWmiInstanceCreate , см. в разделе Ошибки создания объектов платформы.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Если драйвер создает несколько экземпляров поставщика, драйвер должен вызвать WdfWmiProviderCreate , чтобы создать объект поставщика перед вызовом WdfWmiInstanceCreate. Драйвер передает дескриптор объекта поставщика в WdfWmiInstanceCreate , помещая дескриптор в структуру WDF_WMI_INSTANCE_CONFIG . (Если драйвер предоставляет дескриптор объекта поставщика, параметр Device не используется и может иметь значение NULL.)

Если драйвер создает один экземпляр поставщика, ему не нужно вызывать WdfWmiInstanceCreate перед вызовом WdfWmiInstanceCreate. В этом случае WdfWmiInstanceCreate также создает объект поставщика WMI. Поэтому структура WDF_WMI_INSTANCE_CONFIG драйвера должна содержать указатель на структуру WDF_WMI_PROVIDER_CONFIG , описывающую поставщик данных WMI.

Платформа предписывает WMI создать динамическое имя экземпляра, которое могут использовать приложения, из идентификатора экземпляра устройства физического объекта устройства (PDO) драйвера. (Платформа не поддерживает статические имена экземпляров, которые драйверы модели драйвера Windows (WDM) задаются в IRP_MN_REGINFO или IRP_MN_REGINFO_EX структуре.)

Родительский объект экземпляра WMI является объектом поставщика WMI. Драйвер не может изменить этот родительский элемент, а элемент ParentObject или структура WDF_OBJECT_ATTRIBUTES должны иметь значение NULL.

После того как драйвер вызывает WdfWmiInstanceCreate, он может вызвать WdfWmiInstanceGetProvider , чтобы получить дескриптор родительского объекта поставщика, и WdfWmiInstanceGetDevice , чтобы получить дескриптор устройства поставщика.

Дополнительные сведения о методе WdfWmiInstanceCreate см. в разделе Поддержка WMI в драйверах Framework-Based.

Если элемент Registerструктуры WDF_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)