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

Статья
08/08/2023

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

Синтаксис

WMI_QUERY_DATABLOCK_CALLBACK WmiQueryDatablockCallback;

NTSTATUS WmiQueryDatablockCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG InstanceCount,
  [in, out] PULONG InstanceLengthArray,
  [in]      ULONG BufferAvail,
  [out]     PUCHAR Buffer
)
{...}

Параметры

[in] DeviceObject

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

[in] Irp

Указатель на IRP.

[in] GuidIndex

Задает блок данных путем предоставления отсчитываемого от нуля индекса в список идентификаторов GUID, предоставленных драйвером в WMILIB_CONTEXT структуре, переданной в WmiSystemControl.

[in] InstanceIndex

Если DpWmiQueryDataBlock вызывается в ответ на запрос IRP_MN_QUERY_SINGLE_INSTANCE , InstanceIndex задает индекс с отсчитываемым от нуля, который указывает экземпляр указанного блока данных, к которому будет выполняться запрос. Если dpWmiQueryDataBlock вызывается в ответ на запрос IRP_MN_QUERY_ALL_DATA , instanceIndex равен нулю.

[in] InstanceCount

Если DpWmiQueryDataBlock вызывается в ответ на запрос IRP_MN_QUERY_SINGLE_INSTANCE , instanceCount имеет значение 1. Если DpWmiQueryDataBlock вызывается в ответ на запрос IRP_MN_QUERY_ALL_DATA , InstanceCount — это количество возвращаемых экземпляров.

[in, out] InstanceLengthArray

Указатель на предоставленный вызывающим массивом элементов ULONG размера InstanceCount. Драйвер заполняет каждый элемент массива, чтобы указать длину каждого возвращенного экземпляра. Если bufferAvail равно нулю, InstanceLengthArray имеет значение NULL.

[in] BufferAvail

Указывает максимальное количество байтов, доступных для получения данных в буфере в буфере. Если это значение равно нулю, вызывающий объект запрашивает, чтобы драйвер указал требуемый размер буфера в вызове WmiCompleteRequest. Дополнительные сведения см. в разделе "Примечания".

[out] Buffer

Указатель на буфер для получения данных экземпляра. Если буфер достаточно велик для получения всех данных, драйвер записывает данные экземпляра в буфер, при этом каждый экземпляр выравнивается по 8-байтовой границе. Если буфер слишком мал для получения всех данных, драйвер вызывает WmiCompleteRequest с параметром BufferUsed , равным требуемому размеру.

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

DpWmiQueryDataBlock возвращает STATUS_SUCCESS или состояние ошибки, например следующее:

Если драйвер не может выполнить запрос немедленно, он может вернуть STATUS_PENDING.

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

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

Убедитесь, что значение GuidIndex находится в диапазоне от нуля до GuidCount-1 на основе элемента GuidCountструктуры WMILIB_CONTEXT .
Убедитесь, что драйвер не помечает указанный блок данных для удаления. Если драйвер недавно указал флаг WMIREG_FLAG_REMOVE_GUID в структуре WMIGUIDREGINFO , содержащейся в структуре WMILIB_CONTEXT , запрос может быть получен до удаления.
Убедитесь, что значения InstanceIndex и InstanceCount вместе указывают количество экземпляров блоков данных, находящихся в диапазоне, поддерживаемом драйвером блока данных. Если параметр InstanceIndex не равен нулю, параметр InstanceCount должен иметь значение 1. Если instanceIndex имеет значение 0, значение InstanceCount не должно превышать число поддерживаемых экземпляров.
Убедитесь, что буфер, описанный в разделах Buffer и BufferAvail , достаточно велик для хранения всех запрошенных экземпляров блока данных. Каждый экземпляр должен начинаться с 8-байтовой границы, и между элементами данных в каждом экземпляре может существовать дополнительное заполнение.

После записи данных экземпляра в буфер драйвер вызывает WmiCompleteRequest для выполнения запроса. Если буфер, описанный в buffer и BufferAvail , равен нулю или слишком мал для получения всех запрошенных данных, вызов WmiCompleteRequest должен указать STATUS_BUFFER_TOO_SMALL для параметра Status и требуемый размер буфера для параметра BufferUsed .

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

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

Требования

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