getProfileSectionA 函数 (winbase.h)
检索 Win.ini 文件的指定节的所有键和值。
语法
DWORD GetProfileSectionA(
[in] LPCSTR lpAppName,
[out] LPSTR lpReturnedString,
[in] DWORD nSize
);
参数
[in] lpAppName
Win.ini 文件中节的名称。
[out] lpReturnedString
指向接收与命名节关联的键和值的缓冲区的指针。 缓冲区中填充了一个或多个以 null 结尾的字符串;最后一个字符串后跟第二个 null 字符。
[in] nSize
lpReturnedString 参数指向的缓冲区的大小(以字符为单位)。
配置文件节的最大大小为 32,767 个字符。
返回值
返回值指定复制到指定缓冲区的字符数,不包括终止 null 字符。 如果缓冲区不够大,无法包含与命名节关联的所有键和值,则返回值等于 nSize 减去 2 指定的大小。
注解
返回的键和值的格式是一个或多个以 null 结尾的字符串,后跟一个最终的 null 字符。 每个字符串具有以下形式: 键=字符串
GetProfileSection 函数不区分大小写;字符串可以是大写字母和小写字母的组合。
此操作是原子操作;将 节的键和值复制到缓冲区时,不允许对 Win.ini 文件进行更新。
Windows Server 2003 和 Windows XP/2000: 对配置文件函数的调用可以映射到注册表而不是初始化文件。 在注册表中使用以下项指定初始化文件和 节时,会发生此映射: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping。
映射操作后, GetProfileSection 函数将从注册表中检索信息,而不是从初始化文件中检索信息;存储位置的更改不会影响函数的行为。
配置文件函数使用以下步骤查找初始化信息:
- 在注册表中查找 IniFileMapping 项下的初始化文件的名称。
- 查找 由 lpAppName 指定的节名称。 这是具有初始化文件名称的键下的命名值,或者是具有此名称的子项,或者名称不会作为值或子项存在。
- 如果 由 lpAppName 指定的节名称是一个命名值,则该值指定在注册表中查找该节的键的位置。
- 如果 lpAppName 指定的节名称是子项,则该子项下的命名值指定在注册表中查找该节的项的位置。 如果要查找的项没有作为命名值存在,则 (<显示为“无名称> ”) ,该值指定在注册表中查找项的默认位置。
- 如果 lpAppName 指定的节名称不是作为命名值或子项存在的,则会有一个未命名的值 (显示为 <“无名称>) ,该名称指定注册表中可在其中找到该节的键的默认位置。
- 如果节名称没有子项或条目,请在磁盘上查找实际的初始化文件并读取其内容。
- ! - 此字符强制所有写入操作同时转到注册表和磁盘上的 .ini 文件。
- # - 当新用户在安装后首次登录时,此字符会导致注册表值设置为 Windows 3.1 .ini 文件中的值。
- @ - 如果注册表中找不到请求的数据,此字符可防止任何读取操作转到磁盘上的 .ini 文件。
- USR: - 此前缀代表 HKEY_CURRENT_USER,前缀后面的文本相对于该键。
- SYS: - 此前缀代表 HKEY_LOCAL_MACHINE\SOFTWARE,前缀后面的文本相对于该键。
注意
winbase.h 标头将 GetProfileSection 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配,从而导致编译或运行时错误。 有关详细信息,请参阅 函数原型的约定。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
目标平台 | Windows |
标头 | winbase.h (包括 Windows.h) |
Library | Kernel32.lib |
DLL | Kernel32.dll |