IRP_MN_QUERY_SINGLE_INSTANCE

Статья
06/15/2023

Все драйверы, поддерживающие WMI, должны обрабатывать этот IRP. Драйвер может обрабатывать WMI IRP путем вызова WmiSystemControl или обработки самого IRP, как описано в разделе Обработка запросов WMI.

Если драйвер вызывает WmiSystemControl для обработки запроса IRP_MN_QUERY_SINGLE_INSTANCE , WMI, в свою очередь, вызывает подпрограмму DpWmiQueryDataBlock этого драйвера.

Основной код

IRP_MJ_SYSTEM_CONTROL

При отправке

WMI отправляет этот IRP для запроса одного экземпляра заданного блока данных.

WMI отправляет IRP_MN_QUERY_SINGLE_INSTANCE перед отправкой IRP_MN_EXECUTE_METHOD. Если драйвер поддерживает IRP_MN_EXECUTE_METHOD, он должен иметь обработчик IRP_MN_QUERY_SINGLE_INSTANCE для того же блока данных, метод которого выполняется.

WMI отправляет этот IRP в IRQL = PASSIVE_LEVEL в произвольном контексте потока.

Входные параметры

Parameters.WMI.ProviderId указывает на объект устройства драйвера, который должен отвечать на запрос. Этот указатель находится в расположении стека ввода-вывода драйвера в IRP.

Parameters.WMI.DataPath указывает на GUID, который идентифицирует блок данных для запроса.

Parameters.WMI.BufferSize указывает максимальный размер непагрегированного буфера в параметре Parameters.WMI.Buffer, который указывает на WNODE_SINGLE_INSTANCE структуру, определяющую экземпляр для запроса.

Выходные параметры

Если драйвер обрабатывает WMI IRP путем вызова WmiSystemControl, WMI заполняет структуру WNODE_SINGLE_INSTANCE данными, предоставляемыми подпрограммой DpWmiQueryDataBlock драйвера.

В противном случае драйвер заполняет структуру WNODE_SINGLE_INSTANCEв Parameters.WMI.Buffer следующим образом:

Обновления WnodeHeader.BufferSize размером в байтах выходной структуры WNODE_SINGLE_INSTANCE, включая данные экземпляра. Это значение должно включать длину имени экземпляра (с заполнением таким образом, чтобы данные экземпляра начинались с границы четырех слов), даже если запрашиваемый класс зарегистрировал имена статических экземпляров, а модуль записи драйвера явно не предоставляет имя при обслуживании этого IRP.
Задает sizeDataBlock для размера (в байтах) данных экземпляра. Если используются статические имена экземпляров, это значение не должно включать размер имени экземпляра.
Записывает данные экземпляра в Parameters.WMI.Buffer , начиная с DataBlockOffset. Драйвер не должен изменять входное значение DataBlockOffset.

Если буфер в Parameters.WMI.Buffer слишком мал для получения всех данных, драйвер заполняет необходимый размер в WNODE_TOO_SMALL структуре в Parameters.WMI.Buffer. Если буфер меньше sizeof(WNODE_TOO_SMALL), драйвер завершает ошибку IRP и возвращает STATUS_BUFFER_TOO_SMALL.

Блок состояния ввода-вывода

Если драйвер обрабатывает IRP путем вызова WmiSystemControl, WMI задает Irp-IoStatus.Status и Irp-IoStatus.Information в блоке состояния ввода-вывода>>.

В противном случае драйвер задает Irp-IoStatus.Status> значение STATUS_SUCCESS или соответствующее состояние ошибки, например следующее:

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

При успешном выполнении драйвер присваивает Irp-IoStatus.Information> значение, введенное в WnodeHeader.BufferSize. Это значение включает длину имени статического экземпляра.

Операция

Драйвер может обрабатывать WMI IRP путем вызова WmiSystemControl или обработки самого IRP, как описано в разделе Обработка запросов WMI.

Если драйвер обрабатывает WMI IRP путем вызова WmiSystemControl, WmiSystemControl вызывает подпрограмму DpWmiQueryDataBlock драйвера.

Если драйвер сам обрабатывает запрос IRP_MN_QUERY_SINGLE_INSTANCE , он должен делать это только в том случае, если Parameters.WMI.ProviderId указывает на тот же объект устройства, что и указатель, переданный драйвером в вызове IoWMIRegistrationControl. В противном случае драйвер должен перенаправить запрос следующему драйверу нижнего уровня в стеке устройств.

Перед обработкой запроса драйвер должен определить, указывает ли Parameters.WMI.DataPath на GUID, поддерживаемый драйвером. В противном случае драйвер должен завершиться ошибкой IRP и вернуть STATUS_WMI_GUID_NOT_FOUND.

Драйвер отвечает за проверку всех входных значений. В частности, драйвер должен выполнить следующие действия, если он обрабатывает сам запрос IRP:

Для статических имен убедитесь, что элемент InstanceIndex структуры WNODE_SINGLE_INSTANCE находится в диапазоне индексов экземпляров, поддерживаемых драйвером для блока данных.
Для динамических имен убедитесь, что строка имени экземпляра определяет экземпляр блока данных, поддерживаемый драйвером.
Убедитесь, что Parameters.WMI.BufferSize указывает буфер, который достаточно велик для получения всех данных, возвращаемых драйвером.

Если драйвер поддерживает блок данных, он проверяет имя экземпляра на входные WNODE_SINGLE_INSTANCEParameters.WMI.Buffer следующим образом:

Если WNODE_FLAG_STATIC_INSTANCE_NAMES задано в WnodeHeader.Flags, драйвер использует InstanceIndex в качестве индекса в списке статических имен экземпляров драйвера для этого блока. WMI получает индекс из регистрационных данных, предоставленных драйвером при регистрации блока.
Если WNODE_FLAG_STATIC_INSTANCE_NAMES в WnodeHeader.Flags не WNODE_FLAG_STATIC_INSTANCE_NAMES, драйвер использует смещение в OffsetInstanceName , чтобы найти строку имени экземпляра во входном WNODE_SINGLE_INSTANCE. OffsetInstanceName — это смещение (в байтах) от начала структуры до USHORT, которое представляет собой длину строки имени экземпляра в байтах (не символах), включая завершающее значение NULL (если оно имеется), за которым следует строка имени экземпляра в Юникоде.

Если драйверу не удается найти указанный экземпляр, он должен завершить ошибку IRP и вернуть STATUS_WMI_INSTANCE_NOT_FOUND. Для экземпляра с динамическим именем экземпляра это состояние указывает, что драйвер не поддерживает экземпляр. Таким образом, WMI может продолжать запрашивать другие поставщики данных и возвращать соответствующую ошибку потребителю данных, если другой поставщик находит экземпляр, но не может обработать запрос по какой-либо другой причине.

Если драйвер находит экземпляр и может обработать запрос, он заполняет структуру WNODE_SINGLE_INSTANCEв Parameters.WMI.Buffer данными для экземпляра.

Если экземпляр действителен, но драйвер не может обработать запрос, он может вернуть любое соответствующее состояние ошибки.