WritePrivateProfileStructW 函数 (winbase.h)
将数据复制到初始化文件的指定节中的键中。 在复制数据时,函数计算校验和并将其追加到数据末尾。 GetPrivateProfileStruct 函数使用校验和来确保数据的完整性。
语法
BOOL WritePrivateProfileStructW(
[in] LPCWSTR lpszSection,
[in] LPCWSTR lpszKey,
[in] LPVOID lpStruct,
[in] UINT uSizeStruct,
[in] LPCWSTR szFile
);
参数
[in] lpszSection
结构数据将复制到的节的名称。 如果节不存在,则会创建一个。 节的名称不区分大小写。
[in] lpszKey
要与结构关联的键的名称。 如果指定节中不存在该键,则会创建它。 如果此参数为 NULL,则会删除整个节,包括 节中的所有键和条目。
[in] lpStruct
要复制的数据。 如果此参数为 NULL,则删除密钥。
[in] uSizeStruct
lpStruct 参数指向的缓冲区大小(以字节为单位)。
[in] szFile
初始化文件的名称。 如果此参数为 NULL,则会将信息复制到 Win.ini 文件中。
如果文件是使用 Unicode 字符创建的,则 函数会将 Unicode 字符写入文件。 否则,函数将写入 ANSI 字符。
返回值
如果函数成功将结构复制到初始化文件,则返回值为非零值。
如果函数失败,或者刷新最近访问的初始化文件的缓存版本,则返回值为零。 要获得更多的错误信息,请调用 GetLastError。
注解
初始化文件中的节必须具有以下形式:
[section]
key=struct
.
.
.
如果 szFile 参数不包含文件的完整路径和文件名, WritePrivateProfileString 会在 Windows 目录中搜索该文件。 如果文件不存在,此函数会在 Windows 目录中创建该文件。
如果 szFile 包含完整路径和文件名,并且该文件不存在, 则 WriteProfileString 将创建该文件。 指定的目录必须已存在。
系统保留最新注册表文件映射的缓存版本,以提高性能。 如果所有参数均为 NULL,则该函数将刷新缓存。 当系统编辑文件的缓存版本时,编辑文件本身的进程将使用原始文件,直到清除缓存。
系统使用以下注册表项下定义的映射,将大多数 .ini 文件引用映射到注册表:
HKEY_LOCAL_MACHINE SOFTWARE Microsoft Windows NT CurrentVersion IniFileMapping
如果应用程序修改 Control.ini、System.ini 和 Winfile.ini 等系统组件初始化文件,则此映射很可能。 在这种情况下,函数会将信息写入注册表,而不是初始化文件;存储位置中的更改不会影响函数的行为。
配置文件函数使用以下步骤来查找初始化信息:
- 在注册表中查找 IniFileMapping 键下的初始化文件的名称。
- 查找 lpAppName 指定的节名称。 这将是具有初始化文件名称的键下的命名值,或者具有此名称的子项,或者名称将不作为值或子项存在。
- 如果 lpAppName 指定的节名称是命名值,则该值指定在注册表中查找该节的键的位置。
- 如果 lpAppName 指定的节名称是一个子项,则该子项下的命名值将指定在注册表中查找该节的键的位置。 如果要查找的项不存在为命名值,则 (未命名的值显示为 <“无名称>) ”,指定在注册表中查找密钥的默认位置。
- 如果 lpAppName 指定的节名称不是作为命名值或子项存在的,则存在一个未命名的值 (显示为 <“无名称> ”) ,指定注册表中的默认位置,可在其中找到分区的键。
- 如果节名称没有子项或条目,请在磁盘上查找实际的初始化文件并读取其内容。
- ! - 此字符强制所有写入操作同时转到注册表和磁盘上的 .ini 文件。
- # - 当新用户在安装后首次登录时,此字符会导致注册表值设置为 Windows 3.1 .ini 文件中的值。
- @ - 如果注册表中找不到请求的数据,此字符将阻止任何读取操作转到磁盘上的 .ini 文件。
- USR: - 此前缀代表 HKEY_CURRENT_USER,前缀后面的文本相对于该键。
- SYS: - 此前缀代表 HKEY_LOCAL_MACHINE\SOFTWARE,前缀后面的文本相对于该键。
注意
winbase.h 标头将 WritePrivateProfileStruct 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配,从而导致编译或运行时错误。 有关详细信息,请参阅 函数原型的约定。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
目标平台 | Windows |
标头 | winbase.h (包括 Windows.h) |
Library | Kernel32.lib |
DLL | Kernel32.dll |
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈