WritePrivateProfileSectionA 函数 (winbase.h)

  • 项目

替换初始化文件中指定节的键和值。

注意 此函数仅用于与 16 位版本的 Windows 兼容。 应用程序应在注册表中存储初始化信息。
 

语法

BOOL WritePrivateProfileSectionA(
  [in] LPCSTR lpAppName,
  [in] LPCSTR lpString,
  [in] LPCSTR 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 标头将 WritePrivateProfileSection 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

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

另请参阅

GetPrivateProfileSection

RegCreateKeyEx

RegSetValueEx

WriteProfileSection