getProfileStringA 函式 (winbase.h)
擷取與 Win.ini 檔案之指定區段中索引鍵相關聯的字串。
語法
DWORD GetProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpDefault,
[out] LPSTR lpReturnedString,
[in] DWORD nSize
);
參數
[in] lpAppName
包含索引鍵的區段名稱。 如果此參數為 NULL，函式會將檔案中的所有區段名稱複製到提供的緩衝區。
[in] lpKeyName
要擷取其相關聯字串的索引鍵名稱。 如果此參數為 NULL，函式會將指定區段中的所有索引鍵複製到提供的緩衝區。 每個字串後面接著 Null 字元，最後一個字串後面接著第二個 Null 字元。
[in] lpDefault
默認字串。 如果在初始化檔案中找不到 lpKeyName 機碼， GetProfileString 會將預設字串複製到 lpReturnedString 緩衝區。 如果此參數為 NULL，則預設值為空字串 “ ” ”
請避免使用尾端空白字元指定預設字串。 函式會在 lpReturnedString 緩衝區中插入 Null 字元，以去除任何尾端空白。
[out] lpReturnedString
接收字元字串之緩衝區的指標。
[in] nSize
lpReturnedString 參數所指向的緩衝區大小，以字元為單位。
傳回值
傳回值是複製到緩衝區的字元數，不包括 Null 終止字元。
如果 lpAppName 和 lpKeyName 都不是 NULL ，而且提供的目的地緩衝區太小而無法保存要求的字串，則會截斷字串，後面接著 Null 字元，且傳回值等於 nSize 減一。
如果 lpAppName 或 lpKeyName 為 NULL ，且提供的目的地緩衝區太小而無法保存所有字串，則會截斷最後一個字串，後面接著兩 個 Null 字元。 在此情況下，傳回值等於 nSize 減 2。
備註
如果與 lpKeyName 參數相關聯的字串以單引號或雙引弧括住， 當 GetProfileString 函式傳回字串時，會捨棄標記。
GetProfileString 函式不區分大小寫;字串可以包含大寫和小寫字母的組合。
Win.ini 檔案中的區段必須具有下列格式：
[section]
key=string
.
.
.
應用程式可以使用 GetPrivateProfileString 函式，從指定的初始化檔案擷取字串。
lpDefault 參數必須指向有效的字串，即使字串是空的 (亦然，即使其第一個字元是 null 字元) 也一樣。
Windows Server 2003 和 Windows XP/2000： 對配置檔函式的呼叫可能會對應至登錄，而不是對應至初始化檔案。 當登錄中指定了下列機碼下的初始化檔案和區段時，就會發生此對應：
\ HKEY_LOCAL_MACHINE軟體\微軟\\Windows NT CurrentVersion\IniFileMapping
當作業已對應時， GetProfileString 函式會從登錄擷取資訊，而不是從初始化檔案擷取資訊;儲存位置中的變更不會影響函式的行為。
設定檔案函式會使用下列步驟來尋找初始化資訊：
- 在登錄中尋找 IniFileMapping 機碼下的初始化檔名。
- 尋找 lpAppName 所指定的區段名稱。 這會是索引鍵底下的具名值，其名稱為初始化檔案的名稱，或是具有此名稱的子機碼，或名稱不會以值或子機碼的形式存在。
- 如果 lpAppName 所指定的區段名稱是具名值，該值會指定登錄中您會找到區段索引鍵的位置。
- 如果 lpAppName 指定的區段名稱是子機碼，則該子機碼底下的具名值會指定在登錄中，您會找到區段的機碼。 如果您要尋找的機碼不存在為具名值，則會有未命名的值， (顯示為 <[無名稱> ]) ，指定您在登錄中找到密鑰的預設位置。
- 如果 lpAppName 指定的區段名稱不存在為具名值或子機碼，則 (未命名的值 (顯示為 <[無名稱> ]) ，指定您可以在登錄中找到區段索引鍵的預設位置。
- 如果區段名稱沒有子機碼或專案，請在磁碟上尋找實際的初始化檔案，並讀取其內容。
- ! - 此字元會強制所有寫入至登錄和磁碟上 .ini 檔案。
- # - 當新使用者第一次在安裝之後登入時，此字元會使登錄值設定為 Windows 3.1 .ini 檔案中的值。
- @ - 如果登錄中找不到要求的數據，此字元可防止任何讀取移至磁碟上的 .ini 檔案。
- USR：此前置詞代表 HKEY_CURRENT_USER，而前置詞之後的文字則代表該索引鍵的相對。
- SYS：- 此前置詞代表 HKEY_LOCAL_MACHINE\SOFTWARE，而前置詞之後的文字會相對於該索引鍵。
注意
winbase.h 標頭會將 GetProfileString 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | winbase.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |