функция обратного вызова WMI_QUERY_REGINFO_CALLBACK (wmilib.h)

Статья
08/08/2023

Подпрограмма DpWmiQueryReginfo предоставляет сведения о блоках данных и блоках событий, которые должны быть зарегистрированы драйвером. Эта подпрограмма является обязательной.

Синтаксис

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

Параметры

[in] DeviceObject

Указатель на структуру WDM драйвера DEVICE_OBJECT .

[out] RegFlags

Этот параметр указывает общие характеристики всех регистремых блоков. Любой флаг, установленный в RegFlags , применяется ко всем блокам. Драйвер может дополнить RegFlags для заданного блока, установив флаги в структуре WMIGUIDREGINFO блока. Например, драйвер может очистить WMIREG_FLAG_EXPENSIVE в RegFlags, но задать его в разделе Флаги , чтобы зарегистрировать данный блок как дорогостоящий для сбора.

Драйвер устанавливает один из следующих флагов в RegFlags:

WMIREG_FLAG_INSTANCE_BASENAME

Запрашивает WMI для создания статических имен экземпляров из базового имени, предоставленного драйвером в имени экземпляра. WMI создает имена экземпляров путем добавления счетчика к базовому имени.

WMIREG_FLAG_INSTANCE_PDO

Запрашивает WMI для создания статических имен экземпляров из идентификатора экземпляра устройства для PDO. Если драйвер устанавливает этот флаг, он также должен задать Pdo в качестве PDO , переданного в подпрограмму AddDevice драйвера. WMI создает имена экземпляров из пути экземпляра устройства PDO. Использование пути экземпляра устройства в качестве основы для статических имен экземпляров является эффективным, так как такие имена гарантированно будут уникальными. WMI автоматически предоставляет "понятное" имя экземпляра в качестве элемента в блоке данных, который может запрашиваться потребителями данных.

Драйвер также может задать один или несколько следующих флагов в RegFlags, но чаще всего они задаются в разделе Флаги структуры WMIGUIDREGINFO блока:

WMIREG_FLAG_EVENT_ONLY_GUID

Блоки могут быть включены или отключены только как события, а также не могут быть запрошены или заданы. Если этот флаг не задан, блоки также можно запрашивать или задавать.

WMIREG_FLAG_EXPENSIVE

Запрашивает WMI для отправки IRP_MN_ENABLE_COLLECTION запроса при первом открытии потребителем данных блока данных и запросе IRP_MN_DISABLE_COLLECTION , когда последний потребитель данных закрывает блок данных. Это рекомендуется, если сбор таких данных влияет на производительность, так как драйверу не нужно собирать данные, пока потребитель данных явно не запросит их, открыв блок.

WMIREG_FLAG_REMOVE_GUID

Запрашивает WMI для удаления поддержки блоков. Этот флаг действителен только в ответ на запрос на обновление сведений о регистрации (IRP_MN_REGINFO или IRP_MN_REGINFO_EX с параметром Parameters.WMI.DataPath с WMIUPDATE).

[out] InstanceName

Указатель на одну подсчитываемую строку Юникода, которая служит базовым именем для всех экземпляров всех блоков, которые должны быть зарегистрированы драйвером. WMI освобождает строку с помощью ExFreePool. Если WMIREG_FLAG_INSTANCE_BASENAME не WMIREG_FLAG_INSTANCE_BASENAME, имя_экземпляра игнорируется.

[out] RegistryPath

Указатель на подсчитываемую строку Юникода, которая указывает путь реестра, передаваемый в подпрограмму DriverEntry драйвера.

[out] MofResourceName

Указатель на одну подсчитываемую строку Юникода, которая указывает имя ресурса MOF, присоединенного к двоичному файлу образа драйвера. Обычно эта строка является статической, определенной драйвером. WMI создает копию этой строки после того, как драйвер возвращается из этой подпрограммы. Эта строка может динамически выделяться драйвером. В случае выделенной строки драйвер отвечает за освобождение строки, что должно быть сделано после возврата WmiSystemControl . Если к драйверу не подключен ресурс MOF, он может оставить MofResourceName без изменений.

[out] Pdo

Указатель на объект физического устройства (PDO), переданный в подпрограмму AddDevice драйвера. Если задано WMIREG_FLAG_INSTANCE_PDO, инструментарий WMI использует путь к экземпляру устройства этого PDO в качестве базы для создания имен статических экземпляров. Если WMIREG_FLAG_INSTANCE_PDO не WMIREG_FLAG_INSTANCE_PDO, WMI игнорирует PDO.

Возвращаемое значение

DpWmiQueryReginfo всегда возвращает STATUS_SUCCESS.

WMI вызывает подпрограмму DpWmiQueryReginfo драйвера после того, как драйвер вызывает WmiSystemControl в ответ на запрос IRP_MN_REGINFO или IRP_MN_REGINFO_EX . Драйвер должен поместить адрес своей подпрограммы DpWmiQueryReginfo в структуру WMILIB_CONTEXT , которая передается в WmiSystemControl.

WMI отправляет IRP после того, как драйвер вызывает IoWMIRegistrationControl с WMIREG_ACTION_REGISTER, WMIREG_ACTION_REREGISTER или WMIREG_ACTION_UPDATE. WMI прозрачно обрабатывает различия между IRP_MN_REGINFO и IRP_MN_REGINFO_EX от имени драйвера.

WMI не отправляет запрос IRP_MN_REGINFO или IRP_MN_REGINFO_EX после того, как драйвер вызывает IoWMIRegistrationControl с WMIREG_ACTION_DEREGISTER, так как WMI не требует дополнительных сведений от драйвера. Драйвер обычно отменяет регистрацию блоков в ответ на запрос IRP_MN_REMOVE_DEVICE .

Драйвер предоставляет новые или обновленные сведения о регистрации отдельных блоков или указывает блоки для удаления в WMILIB_CONTEXT структуре, которую он передает в WmiSystemControl. После первоначального вызова, который устанавливает путь к реестру драйвера и имя ресурса MOF, подпрограмма DpWmiQueryReginfo драйвера может изменить флаги, общие для всех блоков драйвера, предоставить другую строку базового имени, используемую для создания имен экземпляров, или изменить основу для имен экземпляров со строки на путь экземпляра устройства PDO.

Драйвер не должен возвращать STATUS_PENDING или блокировать запрос. Драйвер не должен выполнять запрос, вызывая WmiCompleteRequest из своей подпрограммы DpWmiQueryReginfo или вызывая IoCompleteRequest после возврата WmiSystemControl .

Эта подпрограмма может быть страничной.

Дополнительные сведения о реализации этой процедуры см. в разделе Вызов WmiSystemControl для обработки ИРП WMI.

Требования

Требование	Значение
Целевая платформа	Персональный компьютер
Верхняя часть	wmilib.h (включая Wmilib.h)
IRQL	Звонил на PASSIVE_LEVEL.