SetupGetLineTextA 函式 (setupapi.h)

發行項
03/05/2024

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

SetupGetLineText 函式會以精簡格式傳回 INF 檔案中行的內容。要擷取的行可由從 SetupFindLineXXX 函式傳回的 INFCONTEXT 結構指定，或是明確地傳入所需行的 INF 句柄、區段和索引鍵。

語法

WINSETUPAPI BOOL SetupGetLineTextA(
  [in]      PINFCONTEXT Context,
  [in]      HINF        InfHandle,
  [in]      PCSTR       Section,
  [in]      PCSTR       Key,
  [in, out] PSTR        ReturnBuffer,
  [in]      DWORD       ReturnBufferSize,
  [in, out] PDWORD      RequiredSize
);

參數

[in] Context

INF 檔案中要擷取其文字之行的內容。此參數可以是 Null。如果 Context 為 NULL， 則必須指定 InfHandle、 Section 和 Key 。

[in] InfHandle

要查詢的 INF 檔案句柄。此參數可以是 Null。只有當 Context 為 NULL 時，才會使用此參數。如果 Context 為 NULL， 則必須指定 InfHandle、 Section 和 Key 。

[in] Section

Null 終止字串的指標，指定包含要擷取文字之行索引鍵名稱的區段。此參數可以是 Null。只有當 Context 為 NULL 時，才會使用此參數。如果 Context 是 NULL，則必須指定 InfHandle、 Section 和 Key 。

[in] Key

Null 終止字串的指標，其中包含要擷取其相關聯字串的索引鍵名稱。此參數可以是 Null。只有當 Context 為 NULL 時，才會使用此參數。如果 Context 是 NULL，則必須指定 InfHandle、 Section 和 Key 。

[in, out] ReturnBuffer

如果不是 NULL，ReturnBuffer 會指向緩衝區，在此緩衝區中，此函式會傳回行的內容。 以 Null 終止的字串不能超過目的地緩衝區的大小。您可以呼叫函式一次，以取得所需的緩衝區大小、配置必要的記憶體，然後再次呼叫函式以擷取數據。使用這項技術，您可以避免因為緩衝區大小不足而發生錯誤。請參閱＜備註＞一節。此參數可以是 Null。

[in] ReturnBufferSize

ReturnBuffer 參數所指向的緩衝區大小，以字元為單位。這包括 Null 終止符。

[in, out] RequiredSize

如果不是 NULL，則指向變數，在此變數中，此函式會以字元為單位傳回 ReturnBuffer 參數所指向之緩衝區的必要大小。這包括 Null 終止符。如果指定 ReturnBuffer 且所需的大小大於 ReturnBufferSize 參數中指定的值，則函式會失敗，而且不會將數據儲存在緩衝區中。

傳回值

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

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

備註

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

此函式會以精簡格式傳回一行的內容。拿掉所有多餘的空格符，並將多行值轉換成單一連續字串。例如，這一行：

HKLM, , PointerClass0, 1 \
; This is a comment
01, 02, 03

會傳回為：

HKLM,,PointerClass0,1,01,02,03

注意

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

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	setupapi.h
程式庫	Setupapi.lib
Dll	Setupapi.dll
API 集合	ext-ms-win-setupapi-inf-l1-1-0 (於 Windows 8)