GetPrivateProfileSectionA 函数 (winbase.h)

检索初始化文件指定节的所有键和值。

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

语法

DWORD GetPrivateProfileSectionA(
  [in]  LPCSTR lpAppName,
  [out] LPSTR  lpReturnedString,
  [in]  DWORD  nSize,
  [in]  LPCSTR lpFileName
);

参数

[in] lpAppName

初始化文件中节的名称。

[out] lpReturnedString

指向接收与命名节关联的键名称和值对的缓冲区的指针。 缓冲区用一个或多个以 null 结尾的字符串填充;最后一个字符串后跟第二个 null 字符。

[in] nSize

lpReturnedString 参数指向的缓冲区的大小(以字符为单位)。

最大配置文件节大小为 32,767 个字符。

[in] lpFileName

初始化文件的名称。 如果此参数不包含文件的完整路径,则系统将在 Windows 目录中搜索该文件。

返回值

返回值指定复制到缓冲区的字符数,不包括终止 null 字符。 如果缓冲区不够大,无法包含与命名节关联的所有键名称和值对,则返回值等于 nSize 减 2。

言论

lpReturnedString 参数指向的缓冲区中的数据由一个或多个以 null 结尾的字符串组成,后跟最终的 null 字符。 每个字符串具有以下格式:

=字符串

GetPrivateProfileSection 函数不区分大小写;lpAppName 参数指向的字符串可以是大写字母和小写字母的组合。

此操作是原子操作;当节的键名称和值对复制到 lpReturnedString 参数指向的缓冲区时,不允许更新指定的初始化文件。

系统使用以下注册表项定义的映射将大多数 .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,前缀后的文本相对于该键。
注释(以分号开头的任何行)将被剥离,并且不会在 lpReturnedString 缓冲区中返回。

注意

winbase.h 标头将 GetPrivateProfileSection 定义为一个别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息,请参阅函数原型的 约定。

要求

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

另请参阅

GetPrivateProfileSectionNames

GetProfileSection

WritePrivateProfileSection