ScsiPortWmiSetInstanceName 函式 （scsiwmi.h）

ScsiPortWmiSetInstanceName 例程會更新要求內容內的 WNODE_ALL_DATA 結構，以指定實例名稱的位置和長度。

注意 SCSI 連接埠驅動程式和 SCSI 迷你埠驅動程式模型未來可能會改變或無法使用。 相反地，我們建議使用 Storport 驅動程式 和 Storport miniport 驅動程式模型。

 

語法

C++

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

參數

[in] RequestContext

包含 WMI SRB 要求內容之類型 SCSIWMI_REQUEST_CONTEXT 結構的指標。

[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 參數 中所傳回的值相同。 例如，假設 minidriver 先呼叫 ScsiPortWmiSetInstanceCount，而這個例程會傳回其 BufferAvail 參數中的值 1,000。 接下來，minidriver 會呼叫 ScsiPortWmiSetData，它會在其 BufferAvail 參數中傳回值 500。 最後，minidriver 會呼叫 ScsiPortWmiSetInstanceName，其傳回其 BufferAvail 參數中的值 200。 BufferAvail中，1,000 的初始值必須傳遞至 ScsiPortWmiSetData，且 500 的值必須傳遞至 ScsiPortWmiSetInstanceName。

如果記憶體不足，無法新增 InstanceNameLength的實例名稱，則會在 BufferAvail 成員中傳回零。

[in, out] SizeNeeded

表示輸入時，描述 WNODE 所需的位元元組數目，再 新增實例的描述性數據，InstanceIndex。 傳回時，此成員會包含整個 WNODE 的大小，包括新實例的數據。

傳回值

ScsiPortWmiSetInstanceCount 例程會傳回緩衝區的指標，呼叫者可以儲存實例在 InstanceIndex中指定的實例名稱。 如果 ScsiPortWmiSetInstanceCount 無法配置足夠的記憶體給實例名稱，或者如果要求內容中包含的 WNODE 不是類型 WNODE_ALL_DATA，ScsiPortWmiSetData 會傳回 NULL。

言論

minidriver 必須先呼叫 ScsiPortWmiSetInstanceCount，才能呼叫 ScsiPortWmiSetInstanceName。

參數 RequestContext 指向要求內容結構，SCSIWMI_REQUEST_CONTEXT，其中包含與 Windows Management Instrumentation （WMI） SCSI 要求區塊 （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