Функция ScsiPortWmiSetInstanceName (scsiwmi.h)
Подпрограмма ScsiPortWmiSetInstanceName обновляет структуру WNODE_ALL_DATA в контексте запроса, чтобы указать позицию и длину имени экземпляра.
Синтаксис
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 :
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.
Комментарии
Перед вызовом ScsiPortWmiSetInstanceCount мини-driver должен вызвать ScsiPortWmiSetInstanceName.
Параметр 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) |