共用方式為

GetProfileStringW 函式 （winbase.h）

  • 發行項

擷取與 Win.ini 檔案指定區段中索引鍵相關聯的字串。

注意 此函式僅供與 16 位 Windows 應用程式相容，因此不應從伺服器程式代碼呼叫此函式。 應用程式應該將初始化資訊儲存在登錄中。
 

語法

DWORD GetProfileStringW(
  [in]  LPCWSTR lpAppName,
  [in]  LPCWSTR lpKeyName,
  [in]  LPCWSTR lpDefault,
  [out] LPWSTR  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 或 lpKeyNameNULL，而且提供的目的地緩衝區太小而無法保存所有字元串，則會截斷最後一個字符串，後面接著兩個 null 字元。 在此情況下，傳回值等於 nSize 減 2。

言論

如果與 lpKeyName 參數相關聯的字串以單引號或雙引號括住，當 getProfileString 函式傳回字符串 時，會捨棄標記。

GetProfileString 函式不區分大小寫;字串可以包含大寫和小寫字母的組合。

Win.ini 檔案中的區段必須具有下列格式：

[section]
key=string
      .
      .
      .

應用程式可以使用 GetPrivateProfileString 函式，從指定的初始化檔案擷取字串。

lpDefault 參數必須指向有效的字串，即使字串是空字串（也就是說，即使其第一個字元是 null 字元）。

Windows Server 2003 和 Windows XP/2000：配置檔函式的呼叫可能會對應至登錄，而不是初始化檔案。 當登錄中指定下列機碼下的初始化檔案和 區段時，就會發生此對應：

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\iniFileMapping

當作業已對應時，GetProfileString 函式會從登錄擷取資訊，而不是從初始化檔案擷取資訊;儲存位置的變更不會影響函式的行為。

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

  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，而前置詞之後的文字則與該索引鍵相對。

注意

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

要求

要求 價值
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平臺 窗戶
標頭 winbase.h （包括 Windows.h）
連結庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

GetPrivateProfileString

WriteProfileString