getProfileStringA 函数 (winbase.h)

  • 项目

检索与 Win.ini 文件的指定节中的键关联的字符串。

注意 提供此函数只是为了与基于 16 位 Windows 的应用程序兼容，因此不应从服务器代码调用此函数。 应用程序应在注册表中存储初始化信息。
 

语法

DWORD GetProfileStringA(
  [in]  LPCSTR lpAppName,
  [in]  LPCSTR lpKeyName,
  [in]  LPCSTR lpDefault,
  [out] LPSTR  lpReturnedString,
  [in]  DWORD  nSize
);

参数

[in] lpAppName

包含密钥的节的名称。 如果此参数为 NULL，则该函数会将文件中的所有节名称复制到提供的缓冲区。

[in] lpKeyName

要检索其关联字符串的键的名称。 如果此参数为 NULL，则该函数会将给定节中的所有键复制到提供的缓冲区。 每个字符串后跟一个 null 字符，最后一个字符串后跟第二个 null 字符。

[in] lpDefault

默认字符串。 如果在初始化文件中找不到 lpKeyName 键， GetProfileString 会将默认字符串复制到 lpReturnedString 缓冲区。 如果此参数为 NULL，则默认值为空字符串“”。

避免指定带有尾随空白字符的默认字符串。 函数在 lpReturnedString 缓冲区中插入一个 null 字符，以去除任何尾随空白。

[out] lpReturnedString

指向接收字符串的缓冲区的指针。

[in] nSize

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

返回值

返回值是复制到缓冲区的字符数，不包括 null 终止字符。

如果 lpAppName 和 lpKeyName 都不为 NULL ，并且提供的目标缓冲区太小而无法容纳请求的字符串，则会截断字符串并后跟 一个 null 字符，并且返回值等于 nSize 减 1。

如果 lpAppName 或 lpKeyName 为 NULL ，并且提供的目标缓冲区太小，无法容纳所有字符串，则最后一个字符串将被截断，后跟两个 null 字符。 在本例中，返回值等于 nSize 减 2。

注解

如果与 lpKeyName 参数关联的字符串用单引号或双引号引起来，则 当 GetProfileString 函数返回字符串时，这些标记将被丢弃。

GetProfileString 函数不区分大小写;字符串可以包含大写字母和小写字母的组合。

Win.ini 文件中的节必须具有以下形式：

[section]
key=string
      .
      .
      .

应用程序可以使用 GetPrivateProfileString 函数从指定的初始化文件中检索字符串。

lpDefault 参数必须指向有效的字符串，即使字符串为空 (即，即使其第一个字符是 null 字符) 。

Windows Server 2003 和 Windows XP/2000： 对配置文件函数的调用可以映射到注册表，而不是初始化文件。 在注册表中的以下项下指定初始化文件和节时，会发生此映射：

\ HKEY_LOCAL_MACHINE软件\微软\\ Windows NT CurrentVersion\IniFileMapping

映射操作后， GetProfileString 函数从注册表检索信息，而不是从初始化文件中检索信息;存储位置中的更改不会影响函数的行为。

配置文件函数使用以下步骤来查找初始化信息：

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

要求

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

另请参阅

GetPrivateProfileString

WriteProfileString