WritePrivateProfileStringA 函式 (winbase.h)

發行項
03/03/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， 則會刪除 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 檔案的機碼專案。此專案應位於 \Microsoft\Windows NT\CurrentVersion\IniFileMappingHKEY_LOCAL_MACHINE\SOFTWARE 的路徑底下。
指定指定區段之 .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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

GetPrivateProfileString

WriteProfileString

WritePrivateProfileStringA 函式 (winbase.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

意見反應

其他資源