getPrivateProfileSection 函式 (winbase.h)

擷取初始化檔案之指定區段的所有索引鍵和值。

注意此函式僅供與針對 Windows 撰寫的 16 位應用程式相容。應用程式應該將初始化資訊儲存在登錄中。

語法

DWORD GetPrivateProfileSection(
  [in]  LPCTSTR lpAppName,
  [out] LPTSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCTSTR lpFileName
);

[in] lpAppName

初始化檔案中區段的名稱。

[out] lpReturnedString

緩衝區的指標，接收與具名區段相關聯的索引鍵名稱和值組。緩衝區會填入一或多個以 Null 結尾的字串;最後一個字串後面接著第二個 Null 字元。

[in] nSize

lpReturnedString 參數所指向的緩衝區大小，以字元為單位。

配置檔區段大小上限為 32,767 個字元。

[in] lpFileName

初始化檔案的名稱。如果此參數不包含檔案的完整路徑，系統會搜尋 Windows 目錄中的檔案。

傳回值會指定複製到緩衝區的字元數，不包括終止的 Null 字元。如果緩衝區不夠大，無法包含與具名區段相關聯的所有索引鍵名稱和值組，則傳回值等於 nSize 減 2。

緩衝區中 由 lpReturnedString 參數所指向的數據是由一或多個以 Null 終止的字串所組成，後面接著最後的 Null 字元。每個字串都有下列格式：

關鍵=字串

GetPrivateProfileSection 函式不區分大小寫;lpAppName 參數所指向的字串可以是大寫和小寫字母的組合。

此作業是不可部分完成的;當區段的索引鍵名稱和值組複製到 lpReturnedString 參數所指向的緩衝區時，不允許更新指定的初始化檔案。

系統會使用下列登錄機碼下定義的對應，將大部分 .ini 檔案參考對應至登錄：HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\IniFileMapping

如果應用程式修改系統元件初始化檔案，例如 Control.ini、System.ini 和 Winfile.ini，則可能是這種對應。在這些情況下，函式會從登錄擷取資訊，而不是從初始化檔案擷取資訊;儲存位置中的變更不會影響函式的行為。

設定檔案函式會使用下列步驟來尋找初始化資訊：

在登錄中尋找 IniFileMapping 機碼下的初始化檔名。
尋找 lpAppName 所指定的區段名稱。這會是索引鍵底下的具名值，其名稱為初始化檔案的名稱，或是具有此名稱的子機碼，或名稱不會以值或子機碼的形式存在。
如果 lpAppName 所指定的區段名稱是具名值，該值會指定登錄中您會找到區段索引鍵的位置。
如果 lpAppName 指定的區段名稱是子機碼，則該子機碼底下的具名值會指定在登錄中，您會找到區段的機碼。如果您要尋找的機碼不存在為具名值，則會有未命名的值， (顯示為 <[無名稱> ]) ，指定您在登錄中找到密鑰的預設位置。
如果 lpAppName 指定的區段名稱不存在為具名值或子機碼，則 (未命名的值 (顯示為 <[無名稱> ]) ，指定您可以在登錄中找到區段索引鍵的預設位置。
如果區段名稱沒有子機碼或專案，請在磁碟上尋找實際的初始化檔案，並讀取其內容。

在登錄中查看指定其他登錄位置的值時，有數個前置詞會變更 .ini 檔案對應的行為：

批注 (以分號開頭的任何行) 會移除，而不會在 lpReturnedString 緩衝區中傳回。

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll