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 文件或注册表项中。下面是一个示例：[My Section]。
对于系统文件，请指定 SYS 作为附加值。
对于应用程序文件，请在附加值中指定 USR。下面是一个示例：“My Section： USR： App Name\Section”。而且，由于 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 标头将 WritePrivateProfileString 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winbase.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

另请参阅

GetPrivateProfileString

WriteProfileString

WritePrivateProfileStringA 函数 (winbase.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

反馈

其他资源