WritePrivateProfileStringA 函式（winbase.h）

發行項
11/20/2024

將字串複製到初始化檔案的指定區段。

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

語法

BOOL WritePrivateProfileStringA(
  [in] LPCSTR lpAppName,
  [in] LPCSTR lpKeyName,
  [in] LPCSTR lpString,
  [in] LPCSTR lpFileName
);

參數

[in] lpAppName

將複製字串的區段名稱。如果區段不存在，則會建立該區段。區段的名稱與大小寫無關;字串可以是大寫和小寫字母的任何組合。

[in] lpKeyName

要與字串相關聯的索引鍵名稱。如果索引鍵不存在於指定的區段中，則會建立它。如果此參數 NULL，則會刪除整個區段，包括區段內的所有專案。

[in] lpString

要寫入檔案的 null null終止字串。如果此參數 NULL，則會刪除 lpKeyName 參數所指向的索引鍵。

[in] lpFileName

初始化檔的名稱。

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

傳回值

如果函式成功將字串複製到初始化檔案，則傳回值為非零值。

如果函式失敗，或它會排清最近存取之初始化檔案的快取版本，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

初始化檔案中的區段必須具有下列格式：

[section]
key=string
      .
      .
      .

如果 lpFileName 參數未包含檔案的完整路徑和檔名，WritePrivateProfileString 搜尋 Windows 目錄的檔案。如果檔案不存在，此函式會在 Windows 目錄中建立檔案。

如果 lpFileName 包含完整路徑和檔名，且檔案不存在，WritePrivateProfileString 建立檔案。指定的目錄必須已經存在。

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

系統會使用下列登錄機碼下定義的對應，將大部分 .ini 檔案參考對應至登錄：

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               IniFileMapping

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

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

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

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

! - 此字元會強制所有寫入到登錄和磁碟上的 .ini 檔案。
# - 此字元會在安裝後第一次登入時，將登錄值設定為 Windows 3.1 .ini 檔案中的值。
@ - 如果登錄中找不到要求的數據，此字元可防止任何讀取到磁碟上的 .ini 檔案。
USR：- 此前置詞代表 HKEY_CURRENT_USER，而前置詞之後的文字則與該索引鍵相對。
SYS：- 此前置詞代表 HKEY_LOCAL_MACHINE\SOFTWARE，而前置詞之後的文字則與該索引鍵相對。

使用 WritePrivateProfileString 函式將 .ini 檔案資訊輸入登錄的應用程式，應遵循下列指導方針：

確定系統上沒有指定名稱的 .ini 檔案。
請確定登錄中有指定 .ini 檔案的機碼專案。此項目應位於路徑下方 HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping。
指定指定區段之 .ini 檔案索引鍵專案的值。也就是說，應用程式必須指定區段名稱，因為它會出現在 .ini 檔案或登錄專案中。以下是範例：[我的區段]。
針對系統檔案，指定SS作為加值。
針對應用程式檔，請在加值內指定USR。以下是範例：「我的區段：USR：應用程式名稱\區段」。而且，由於 USR 表示 HKEY_CURRENT_USER下的對應，因此應用程式也應該在 HKEY_CURRENT_USER 下建立索引鍵，以指定加值中列出的應用程式名稱。就剛才指定的範例而言，這會是「應用程式名稱」。
遵循上述步驟之後，應用程式安裝程序應該呼叫 WritePrivateProfileString，並將前三個參數設定為 NULL，並將第四個參數設定為 INI 檔名。例如：
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" );
這類呼叫會導致 .ini 檔案與登錄的對應在下一次系統重新啟動之前生效。系統會將對應資訊重新讀取到共用記憶體中。安裝應用程式之後，使用者不需要重新啟動其計算機，才能讓應用程式的未來調用看到 .ini 檔案與登錄的對應。

例子

下列範例程式代碼說明上述指導方針，並基於數個假設：

有一個名為應用程式名稱的應用程式。
該應用程式會使用名為 AppName.ini.ini 檔案。

.ini 檔案中有一個區段，我們想要看起來像這樣：

[Section1] 
  FirstKey = It all worked out okay. 
  SecondKey = By golly, it works. 
  ThirdKey = Another test.

使用者不需要重新啟動系統，才能有應用程式的未來調用，請參閱 .ini 檔案與登錄的對應。

#include <windows.h> 
#include <tchar.h>
#include <stdio.h> 
 
int main() 
{ 
   TCHAR   inBuf[80]; 
   HKEY   hKey1, hKey2; 
   DWORD  dwDisposition; 
   LONG   lRetCode; 
   TCHAR   szData[] = TEXT("USR:App Name\\Section1");
 
   // Create the .ini file key. 
   lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE, 
       TEXT("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\IniFileMapping\\appname.ini"), 
       0, 
       NULL, 
       REG_OPTION_NON_VOLATILE, 
       KEY_WRITE, 
       NULL, 
       &hKey1, 
       &dwDisposition); 
 
   if (lRetCode != ERROR_SUCCESS)
   { 
      printf ("Error in creating appname.ini key (%d).\n", lRetCode); 
      return (0) ; 
   } 
 
   // Set a section value 
   lRetCode = RegSetValueEx ( hKey1, 
                              TEXT("Section1"), 
                              0, 
                              REG_SZ, 
                              (BYTE *)szData, 
                              sizeof(szData)); 
 
   if (lRetCode != ERROR_SUCCESS) 
   { 
      printf ("Error in setting Section1 value\n"); 
      // Close the key
      lRetCode = RegCloseKey( hKey1 );
      if( lRetCode != ERROR_SUCCESS )
      {
         printf("Error in RegCloseKey (%d).\n", lRetCode);
         return (0) ; 
      }
   } 
 
   // Create an App Name key 
   lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER, 
                               TEXT("App Name"), 
                               0, 
                               NULL, 
                               REG_OPTION_NON_VOLATILE,
                               KEY_WRITE, 
                               NULL, 
                               &hKey2, 
                               &dwDisposition); 
 
   if (lRetCode != ERROR_SUCCESS) 
   { 
      printf ("Error in creating App Name key (%d).\n", lRetCode); 

      // Close the key
      lRetCode = RegCloseKey( hKey2 );
      if( lRetCode != ERROR_SUCCESS )
      {
         printf("Error in RegCloseKey (%d).\n", lRetCode);
         return (0) ; 
      }
   } 
 
   // Force the system to read the mapping into shared memory 
   // so that future invocations of the application will see it 
   // without the user having to reboot the system 
   WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" ); 
 
   // Write some added values 
   WritePrivateProfileString (TEXT("Section1"), 
                              TEXT("FirstKey"), 
                              TEXT("It all worked out OK."), 
                              TEXT("appname.ini")); 
   WritePrivateProfileString (TEXT("Section1"), 
                              TEXT("SecondKey"), 
                              TEXT("By golly, it works!"), 
                              TEXT("appname.ini")); 
   WritePrivateProfileString (TEXT("Section1"), 
                              TEXT("ThirdKey"), 
                              TEXT("Another test..."), 
                              TEXT("appname.ini")); 

   // Test 
   GetPrivateProfileString (TEXT("Section1"), 
                            TEXT("FirstKey"), 
                            TEXT("Error: GPPS failed"), 
                            inBuf, 
                            80, 
                            TEXT("appname.ini")); 
   _tprintf (TEXT("Key: %s\n"), inBuf); 
 
   // Close the keys
   lRetCode = RegCloseKey( hKey1 );
   if( lRetCode != ERROR_SUCCESS )
   {
      printf("Error in RegCloseKey (%d).\n", lRetCode);
      return(0);
   }

   lRetCode = RegCloseKey( hKey2 );
   if( lRetCode != ERROR_SUCCESS )
   {
      printf("Error in RegCloseKey (%d).\n", lRetCode);
      return(0);
   }
   
   return(1); 
}

注意

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

要求

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

另請參閱

GetPrivateProfileString

WriteProfileString

共用方式為

WritePrivateProfileStringA 函式（winbase.h）

語法

參數

傳回值

言論

例子

要求

另請參閱

意見反應

其他資源

共用方式為

WritePrivateProfileStringA 函式 （winbase.h）

語法

參數

傳回值

言論

例子

要求

另請參閱

意見反應

其他資源

WritePrivateProfileStringA 函式（winbase.h）