WritePrivateProfileSectionW 函式 (winbase.h)

  • 發行項

取代初始化檔案中指定區段的索引鍵和值。

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

語法

BOOL WritePrivateProfileSectionW(
  [in] LPCWSTR lpAppName,
  [in] LPCWSTR lpString,
  [in] LPCWSTR lpFileName
);

參數

[in] lpAppName

寫入資料之區段的名稱。 此區段名稱通常是呼叫應用程式的名稱。

[in] lpString

要寫入具名區段的新索引鍵名稱和相關聯的值。 此字串限制為65,535個字節。

[in] lpFileName

初始化檔的名稱。 如果此參數不包含檔案的完整路徑，函式會搜尋 Windows 目錄中的檔案。 如果檔案不存在， 且 lpFileName 不包含完整路徑，則函式會在 Windows 目錄中建立檔案。

如果檔案存在且使用 Unicode 字元建立，函式會將 Unicode 字元寫入檔案。 否則，函式會使用 ANSI 字元建立檔案。

傳回值

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

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

備註

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

關鍵=字串

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

如果沒有區段名稱符合 lpAppName 參數所指向的字串， WritePrivateProfileSection 會在指定的初始化檔結尾建立區段，並使用指定的索引鍵名稱和值組初始化新區段。

WritePrivateProfileSection 會刪除具名區段的現有索引鍵和值，並將索引鍵名稱和值插入 lpString 參數所指向的緩衝區中。 函式不會嘗試相互關聯舊索引鍵名稱和新索引鍵名稱;如果新名稱的順序與舊名稱不同，則與初始化檔案中預先存在索引鍵和值相關聯的任何批注，可能會與不正確的索引鍵和值產生關聯。

此作業不可部分完成;寫入資訊時，不允許讀取或寫入指定初始化檔案的作業。

系統會保留最新登錄檔對應的快取版本，以改善效能。 如果所有參數都是 NULL，則函式會排清快取。 當系統正在編輯快取的檔案版本時，編輯檔案本身的進程將會使用源檔，直到清除快取為止。

系統會使用下列登錄機碼下定義的對應，將大部分 .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，而前置詞之後的文字則相對於該索引鍵。

注意

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

規格需求

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

另請參閱

GetPrivateProfileSection

RegCreateKeyEx

RegSetValueEx

WriteProfileSection