SetupGetStringFieldA 函式（setupapi.h）

發行項
11/20/2024

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

SetupGetStringField 函式會從 INF 檔案中行的指定字段擷取字串。

語法

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

參數

[in] Context

INF 檔案中行內容的指標。

[in] FieldIndex

指定行內欄位的 1 型索引，應該從中擷取字串。如果存在，請使用 FieldIndex 0 來擷取字串索引鍵。

[in, out] ReturnBuffer

接收 null終止字串之緩衝區的選擇性指標。您應該確定目的地緩衝區的大小或大於來源緩衝區。此參數可以是 NULL。請參閱一節。

[in] ReturnBufferSize

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

[out] RequiredSize

變數的選擇性指標，該變數會以字元表示 ReturnBuffer 參數所指向的緩衝區大小。如果指定 ReturnBuffer，而且所需的實際大小大於 returnBufferSize 所指定的值，則函式會失敗，而且不會將字串儲存在緩衝區中。在此情況下，GetLastError 的呼叫會傳回ERROR_INSUFFICIENT_BUFFER。針對此函式的 Unicode 版本，所需的大小為字元。這包括 null 終止符。

傳回值

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

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

言論

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

您可以呼叫函式一次以取得所需的緩衝區大小、配置必要的記憶體，然後第二次呼叫函式來擷取數據。使用這項技術，您可以避免因為緩衝區大小不足而發生錯誤。

請注意，INF Strings 區段中指定之任何單一字串的最大長度為 512 個字元，包括終止 NULL。如果字串長度大於 512，則會截斷，而且不會傳回任何錯誤。從一或多個 %strkey% 標記建立的任何串連字串長度上限為 4096 個字元。

注意

setupapi.h 標頭會根據 UNICODE 預處理器常數的定義，將 SetupGetStringField 定義為自動選取此函式的 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 中引進）