Функция ScsiPortWmiSetInstanceName (scsiwmi.h)

Статья
08/07/2023

Подпрограмма ScsiPortWmiSetInstanceName обновляет структуру WNODE_ALL_DATA в контексте запроса, чтобы указать позицию и длину имени экземпляра.

Примечание Модели драйверов портов SCSI и драйверов мини-портов SCSI могут быть изменены или недоступны в будущем. Вместо этого рекомендуется использовать модели драйверов Storport и драйверов для мини-портов Storport .

Синтаксис

PWCHAR ScsiPortWmiSetInstanceName(
  [in]      PSCSIWMI_REQUEST_CONTEXT RequestContext,
  [in]      ULONG                    InstanceIndex,
  [in]      ULONG                    InstanceNameLength,
  [out]     PULONG                   BufferAvail,
  [in, out] PULONG                   SizeNeeded
);

Параметры

[in] RequestContext

Указатель на структуру типа SCSIWMI_REQUEST_CONTEXT , содержащую контекст запроса для WMI SRB.

[in] InstanceIndex

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

[in] InstanceNameLength

Задает размер имени экземпляра в байтах.

[out] BufferAvail

Во входных данных должно содержаться количество байтов буферного пространства в структуре WNODE_ALL_DATA , которое можно использовать для описания имен экземпляров и данных. При возврате этот элемент содержит количество оставшихся байтов буферного пространства.

Существует три подпрограммы WMI портов SCSI, которые возвращают значение для доступного размера буфера в параметре BufferAvail :

ScsiPortWmiSetInstanceCount

ScsiPortWmiSetData

ScsiPortWmiSetInstanceName

Драйвер мини-порта должен сначала вызвать ScsiPortWmiSetInstanceCount , но после вызова ScsiPortWmiSetInstanceCount не имеет значения, в каком порядке мини-драйвер вызывает ScsiPortWmiSetData и ScsiPortWmiSetInstanceName. При вызове ScsiPortWmiSetData или ScsiPortWmiSetInstanceName значение, переданное подпрограмме в параметре BufferAvail , должно совпадать со значением, возвращенным в параметре BufferAvail последней подпрограммой WMI порта SCSI. Например, предположим, что мини-накопитель сначала вызывает ScsiPortWmiSetInstanceCount , и эта подпрограмма возвращает значение 1000 в параметре BufferAvail . Затем мини-диск вызывает ScsiPortWmiSetData , который возвращает значение 500 в параметре BufferAvail . Наконец, мини-диск вызывает ScsiPortWmiSetInstanceName , который возвращает значение 200 в параметре BufferAvail . Начальное значение 1000 должно быть передано в ScsiPortWmiSetData в BufferAvail, а значение 500 — в ScsiPortWmiSetInstanceName.

Если доступно недостаточно памяти для добавления имени экземпляра длины InstanceNameLength, в элементе BufferAvail будет возвращено ноль.

[in, out] SizeNeeded

Указывает при входе количество байтов, необходимых для описания WNODE перед добавлением описательных данных для экземпляра, указанного instanceIndex. При возврате этот элемент будет содержать размер всего WNODE, включая данные для нового экземпляра.

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

Подпрограмма ScsiPortWmiSetInstanceCount возвращает указатель на буфер, в котором вызывающий объект может хранить имя экземпляра, указанного в InstanceIndex. Если ScsiPortWmiSetInstanceCount не может выделить достаточно памяти для имени экземпляра или если WNODE, содержащийся в контексте запроса, не имеет типа WNODE_ALL_DATA, ScsiPortWmiSetData возвращает значение NULL.

Параметр RequestContext указывает на структуру контекста запроса SCSIWMI_REQUEST_CONTEXT, которая содержит сведения, связанные с блоком запросов SCSI инструментария управления Windows (WMI) (SRB). Структура контекста запроса, в свою очередь, содержит одну из структур WMI WNODE_XXX, используемых системой WMI для передачи данных между потребителями данных пользовательского режима и поставщиками данных в режиме ядра, такими как драйверы.

Подпрограмма ScsiPortWmiSetInstanceName требует, чтобы структура WNODE, определенная в контексте запроса, была типа WNODE_ALL_DATA. Это связано с тем, что ScsiPortWmiSetInstanceName может выделить область имени экземпляра для любого экземпляра, связанного с блоком данных WMI. В отличие от структуры WNODE_SINGLE_INSTANCE , содержащей сведения об одном экземпляре, структура WNODE_ALL_DATA содержит массив указателей на буферные области для разных экземпляров, а ScsiPortWmiSetInstanceCount инициализирует этот массив, чтобы каждый буфер данных экземпляра можно было получить по отдельности.

Память, выделенная для контекста запроса, должна оставаться действительной до тех пор, пока драйвер мини-порта не вызовет ScsiPortWmiPostProcess, а ScsiPortWmiPostProcess не вернет окончательное состояние SRB и размер буфера. Если SRB может выполняться, память для контекста запроса должна быть выделена из расширения SRB. Если SRB не удается выполнить, память может быть выделена из кадра стека, который не выходит из область.

Требования

Требование	Значение
Целевая платформа	Персональный компьютер
Верхняя часть	scsiwmi.h (включая Miniport.h, Scsi.h)

См. также раздел

SCSIWMI_REQUEST_CONTEXT

WNODE_ALL_DATA

WNODE_SINGLE_INSTANCE

Share via