getPrivateProfileString 函式 (winbase.h)

從初始化檔案中指定的區段擷取字串。

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

語法

DWORD GetPrivateProfileString(
  [in]  LPCTSTR lpAppName,
  [in]  LPCTSTR lpKeyName,
  [in]  LPCTSTR lpDefault,
  [out] LPTSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCTSTR lpFileName
);

參數

[in] lpAppName

包含金鑰名稱的區段名稱。 如果此參數為 NULL,GetPrivateProfileString 函式會將檔案中的所有區段名稱複製到提供的緩衝區。

[in] lpKeyName

要擷取其相關聯字串的索引鍵名稱。 如果此參數為 NULL則 lpAppName 參數所指定區段中的所有索引鍵名稱都會複製到 lpReturnedString 參數所指定的緩衝區。

[in] lpDefault

默認字串。 如果在初始化檔案中找不到 lpKeyName 機碼, GetPrivateProfileString 會將預設字串複製到 lpReturnedString 緩衝區。

如果此參數為 NULL,則預設值為空字串 “ ” ”

請避免使用尾端空白字元指定預設字串。 函式會在 lpReturnedString 緩衝區中插入 Null 字元,以去除任何尾端空白。

[out] lpReturnedString

接收所擷取字串之緩衝區的指標。

[in] nSize

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

[in] lpFileName

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

傳回值

傳回值是複製到緩衝區的字元數,不包括終止 的 Null 字元。

如果 lpAppNamelpKeyName 都不是 NULL ,而且提供的目的地緩衝區太小而無法保存要求的字串,則會截斷字串,後面接著 Null 字元,且傳回值等於 nSize 減一。

如果 lpAppNamelpKeyNameNULL ,且提供的目的地緩衝區太小而無法保存所有字串,則會截斷最後一個字串,後面接著兩 個 Null 字元。 在此情況下,傳回值等於 nSize 減 2。

如果找不到 lpFileName 所指定的初始化檔案,或包含無效的值,呼叫 GetLastError 會傳回 '0x2' (找不到檔案) 。 若要擷取擴充的錯誤資訊,請呼叫 GetLastError

備註

GetPrivateProfileString 函式會在指定的初始化檔案中搜尋符合 lpAppName 參數所指定區段標題下 lpKeyName 參數所指定名稱的索引鍵。 如果找到索引鍵,函式會將對應的字串複製到緩衝區。 如果索引鍵不存在,函式會複製 lpDefault 參數所指定的預設字元字串。 初始化檔案中的區段必須具有下列格式:

[section]
key=string
      .
      .
      .

如果 lpAppNameNULL,GetPrivateProfileString 會將指定檔案中的所有區段名稱複製到提供的緩衝區。 如果 lpKeyNameNULL,函式會將指定區段中的所有密鑰名稱複製到提供的緩衝區。 應用程式可以使用這個方法來列舉檔案中的所有區段和索引鍵。 不論是哪一種情況,每個字串後面都會加上 Null 字元,而最後一個字串後面接著第二個 Null 字元。 如果提供的目的地緩衝區太小而無法保存所有字串,則會截斷最後一個字元串,後面接著兩 個 Null 字元。

如果與 lpKeyName 相關聯的字串以單引號或雙引號括住,當 GetPrivateProfileString 函式擷取字元串時,會捨棄標記。

GetPrivateProfileString 函式不區分大小寫;字串可以是大寫和小寫字母的組合。

若要從 Win.ini 檔案擷取字串,請使用 GetProfileString 函式。

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

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

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

  1. 在登錄中尋找 IniFileMapping 機碼下的初始化檔名。
  2. 尋找 lpAppName 所指定的區段名稱。 這會是索引鍵底下的具名值,其名稱為初始化檔案的名稱,或是具有此名稱的子機碼,或名稱不會以值或子機碼的形式存在。
  3. 如果 lpAppName 所指定的區段名稱是具名值,該值會指定登錄中您會找到區段索引鍵的位置。
  4. 如果 lpAppName 指定的區段名稱是子機碼,則該子機碼底下的具名值會指定在登錄中,您會找到區段的機碼。 如果您要尋找的機碼不存在為具名值,則會有未命名的值, (顯示為 <[無名稱> ]) ,指定您在登錄中找到密鑰的預設位置。
  5. 如果 lpAppName 指定的區段名稱不存在為具名值或子機碼,則 (未命名的值 (顯示為 <[無名稱> ]) ,指定您可以在登錄中找到區段索引鍵的預設位置。
  6. 如果區段名稱沒有子機碼或專案,請在磁碟上尋找實際的初始化檔案,並讀取其內容。
在登錄中查看指定其他登錄位置的值時,有數個前置詞會變更 .ini 檔案對應的行為:
  • ! - 此字元會強制所有寫入至登錄和磁碟上 .ini 檔案。
  • # - 當新使用者第一次在安裝之後登入時,此字元會使登錄值設定為 Windows 3.1 .ini 檔案中的值。
  • @ - 如果登錄中找不到要求的數據,此字元可防止任何讀取移至磁碟上的 .ini 檔案。
  • USR:此前置詞代表 HKEY_CURRENT_USER,而前置詞之後的文字則代表該索引鍵的相對。
  • SYS:- 此前置詞代表 HKEY_LOCAL_MACHINE\SOFTWARE,而前置詞之後的文字會相對於該索引鍵。

範例

下列範例示範 如何使用 GetPrivateProfileString

// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
      "Preference",
      "Preferred Line",
      gszNULL, 
      szBuffer,
      MAXBUFSIZE,
      gszINIfilename
);

// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
      dwPreferredPLID = (DWORD) atoi( szBuffer );	
}
else	
{
      dwPreferredPLID = (DWORD) -1;
}

規格需求

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

另請參閱

GetProfileString

WritePrivateProfileString