SetupGetMultiSzFieldA 函式（setupapi.h）

發行項
11/20/2024

[此函式可用於需求一節所指出的作業系統。後續版本可能會變更或無法使用。安裝程式API 不應該再用於安裝應用程式。請改用 Windows Installer 來開發應用程式安裝程式。 SetupAPI 會繼續用於安裝設備驅動器。]

SetupGetMultiSzField 函式會從指定的欄位到行尾擷取儲存在 INF 檔案行中的多個字串。

語法

WINSETUPAPI BOOL SetupGetMultiSzFieldA(
  [in]      PINFCONTEXT Context,
  [in]      DWORD       FieldIndex,
  [in, out] PSTR        ReturnBuffer,
  [in]      DWORD       ReturnBufferSize,
  [in]      LPDWORD     RequiredSize
);

參數

[in] Context

INF 檔案中行內容的指標。

[in] FieldIndex

起始欄位的 1 起始索引，指定行內應該從中擷取字串。字串清單是從此時開始到行尾的每個欄位所建置。 FieldIndex 對這個函式無效。

[in, out] ReturnBuffer

接收字串之字元緩衝區的選擇性指標。每個字串都會 null終止，字串清單結尾有額外的 null。 null終止字串不應超過目的地緩衝區的大小。您可以呼叫函式一次以取得所需的緩衝區大小、配置必要的記憶體，然後第二次呼叫函式來擷取數據。使用這項技術，您可以避免因為緩衝區大小不足而發生錯誤。請參閱一節。此參數可以是 NULL。

[in] ReturnBufferSize

以字元表示 ReturnBuffer所指向的緩衝區大小。這包括 null 終止符。

[in] RequiredSize

變數的選擇性指標，該變數會以字元表示 ReturnBuffer所指向之緩衝區所需的大小。這包括 null 終止符。如果所需的大小大於 returnBufferSize 所指定的值，則函式會失敗，而且傳回 GetLastError 的呼叫會傳回ERROR_INSUFFICIENT_BUFFER。

傳回值

如果函式成功，則傳回值是非零值。

如果函式失敗，傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

如果使用 NULL 的 ReturnBuffer 和零的 ReturnBufferSize 呼叫，則函式會將所需的緩衝區大小放入 RequiredSizeRequiredSize 所指向的變數中。如果函式成功，則傳回值是非零值。否則，傳回值為零，而且可以呼叫 getLastError取得擴充錯誤資訊。

SetupGetMultiSzField 不應該用來逐一查看 INF 行上的字串值。您應該改用 SetupGetStringField。 SetupGetMultiSzField 會以 REG_MULTI_SZ 格式傳回值。這是以額外 null 字元終止的 null字串陣列。此格式不允許長度為零的字串。如果字串清單包含任何長度為零的字串，SetupGetMultiSzField 遇到第一個空白字串值時會過早傳回。

注意

setupapi.h 標頭會根據 UNICODE 預處理器常數的定義，將 SetupGetMultiSzField 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	setupapi.h
連結庫	Setupapi.lib
DLL	Setupapi.dll
API 集	ext-ms-win-setupapi-inf-l1-1-1 （在 Windows 10 版本 10.0.14393 中引進）