ScsiPortWmiSetInstanceName 函数 (scsiwmi.h)

项目
02/29/2024

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 结构中可用于描述实例名称和数据的缓冲区空间字节数。返回时，此成员包含剩余的缓冲区空间的字节数。

有三个 SCSI 端口 WMI 例程在其 BufferAvail 参数中返回可用缓冲区大小的值：

ScsiPortWmiSetInstanceCount

ScsiPortWmiSetData

ScsiPortWmiSetInstanceName

微型端口驱动程序必须先调用 ScsiPortWmiSetInstanceCount ，但在调用 ScsiPortWmiSetInstanceCount 之后，微型驱动程序调用 ScsiPortWmiSetData 和 ScsiPortWmiSetInstanceName 的顺序并不重要。调用 ScsiPortWmiSetData 或 ScsiPortWmiSetInstanceName 时，传递给其 BufferAvail 参数中的例程的值必须与最近调用的 SCSI 端口 WMI 例程在 BufferAvail 参数中返回的值相同。例如，假设微型驱动程序首先调用 ScsiPortWmiSetInstanceCount ，并且此例程在其 BufferAvail 参数中返回值 1,000。接下来，微型驱动程序调用 ScsiPortWmiSetData ，该数据在其 BufferAvail 参数中返回值 500。最后，微型驱动程序调用 ScsiPortWmiSetInstanceName ，该名称在其 BufferAvail 参数中返回值 200。初始值 1,000 必须传递到 BufferAvail 中的 ScsiPortWmiSetData，并且值 500 必须传递给 ScsiPortWmiSetInstanceName。

如果没有足够的内存可用于添加长度为 InstanceNameLength 的实例名称， BufferAvail 成员中将返回零。

[in, out] SizeNeeded

指示输入时，在为 InstanceIndex 指定的实例添加描述性数据之前描述 WNODE 所需的字节数。返回时，此成员将包含整个 WNODE 的大小，包括新实例的数据。

返回值

ScsiPortWmiSetInstanceCount 例程返回指向缓冲区的指针，调用方可在其中存储 InstanceIndex 中指定的实例的名称。如果 ScsiPortWmiSetInstanceCount 无法为实例名称分配足够的内存，或者请求上下文中包含的 WNODE 类型不是 WNODE_ALL_DATA， 则 ScsiPortWmiSetData 返回NULL。

注解

微型驱动程序必须先调用 ScsiPortWmiSetInstanceCount，然后才能调用 ScsiPortWmiSetInstanceName。

参数 RequestContext 指向请求上下文结构（SCSIWMI_REQUEST_CONTEXT），该结构包含与 Windows Management Instrumentation (WMI) SCSI 请求块 (SRB) 关联的信息。请求上下文结构又包含 WMI 系统用来在用户模式数据使用者和内核模式数据提供程序（如驱动程序）之间传递数据的 WMI WNODE_XXX结构之一。

ScsiPortWmiSetInstanceName 例程要求请求上下文中定义的 WNODE 结构的类型为 WNODE_ALL_DATA。这是因为 ScsiPortWmiSetInstanceName 可以为与 WMI 数据块关联的任何实例留出实例名称区域。与包含单个实例相关信息的 WNODE_SINGLE_INSTANCE 结构不同，WNODE_ALL_DATA 结构包含指向不同实例缓冲区区域的指针数组， ScsiPortWmiSetInstanceCount 初始化此数组，以便可以单独访问实例数据的每个缓冲区。

在微型端口驱动程序调用 ScsiPortWmiPostProcess 且 ScsiPortWmiPostProcess 返回最终 SRB 状态和缓冲区大小之前，为请求上下文分配的内存必须保持有效。如果 SRB 可以笔，则应从 SRB 扩展分配请求上下文的内存。如果 SRB 无法绘制，则可以从不超出范围的堆栈帧分配内存。