平台 SDK: Windows 系统信息

GetPrivateProfileString

GetPrivateProfileString函数从初始化文件的指定部分中检索字符串。

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

DWORD GetPrivateProfileString(
  LPCTSTR lpAppName,        // 节名称
  LPCTSTR lpKeyName,        // 键名称
  LPCTSTR lpDefault,        // 默认字符串
  LPTSTR lpReturnedString,  // 目标缓冲区
  DWORD nSize,              // 目标缓冲区的大小
  LPCTSTR lpFileName        // 初始化文件名
);

参数

  • lpAppName

  • [in] 指向以空字符结尾的字符串的指针,该字符串指定包含键名称的部分的名称。 如果此参数为NULL,则GetPrivateProfileString函数会将文件中的所有段名称复制到提供的缓冲区中。

  • lpKeyName

  • [in] 指向以空字符结尾的字符串的指针,指定要检索关联字符串的键的名称。 如果此参数为NULL,则由lpAppName参数指定的部分中的所有键名都将被复制到由lpReturnedString参数指定的缓冲区中。

  • lpDefault

  • [in] 指向以空字符结尾的默认字符串的指针。 如果在初始化文件中找不到lpKeyName键,则GetPrivateProfileString会将默认字符串复制到lpReturnedString缓冲区。 该参数不能为NULL。

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

    Windows 95/98/Me: 尽管lpDefault被声明为一个常量参数,但是系统在将它复制到lpReturnedString缓冲区之前,先将空字符插入到lpDefault字符串中,以消除任何尾随空白。

    Windows NT/2000/XP: 系统不会修改lpDefault字符串。 这意味着如果默认字符串包含尾随空白,则使用lstrcmp函数比较时,lpReturnedString和lpDefault字符串将不匹配。

  • lpReturnedString

  • [out] 指向接收检索字符串的缓冲区的指针。

    Windows 95/98/Me: 该字符串不能包含控制字符(小于32的字符代码)。 包含控制字符的字符串可能会被截断。

  • nSize

  • [in] 指定TCHAR中由lpReturnedString参数指向的缓冲区的大小。

  • lpFileName

  • [in] 指向以空字符结尾的字符串的指针,该字符串指定初始化文件的名称。 如果此参数不包含文件的完整路径,系统将在Windows目录中搜索文件。

返回值

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

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

如果lpAppName或lpKeyName为NULL并且提供的目标缓冲区太小而无法容纳所有字符串,则最后一个字符串会被截断,后面跟两个空字符。 在这种情况下,返回值等于nSize减2。

备注

GetPrivateProfileString函数在指定的初始化文件中搜索与由lpAppName参数指定的节标题下的lpKeyName参数指定的名称匹配的键。 如果找到该键,则该函数将相应的字符串复制到缓冲区。 如果该键不存在,则该函数将复制由lpDefault参数指定的默认字符串。 初始化文件中的部分必须具有以下形式:

[section]key=string
      .
      .
      .

如果lpAppName为NULL,则GetPrivateProfileString将指定文件中的所有节名复制到提供的缓冲区中。 如果lpKeyName为NULL,则该函数将指定节中的所有键名复制到提供的缓冲区中。 应用程序可以使用此方法枚举文件中的所有部分和键。 无论哪种情况,每个字符串后跟一个空字符,最后一个字符串后跟第二个空字符。 如果提供的目标缓冲区太小而无法容纳所有字符串,则最后一个字符串会被截断,后面会出现两个空字符。

如果与lpKeyName关联的字符串包含在单引号或双引号中,则在GetPrivateProfileString函数检索字符串时将丢弃这些标记。

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

要从Win.ini文件中检索字符串,请使用GetProfileString函数。

Windows NT/2000/XP: 调用个人配置文件函数可能会映射到注册表而不是指定的初始化文件。 当在注册表中指定了以下键时初始化文件和部分时,会发生此映射:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

如果应用程序修改了系统组件初始化文件(如Control.ini,System.ini和Winfile.ini),则此映射可能会发生。 在这些情况下,GetPrivateProfileString函数从注册表中检索信息,而不是从初始化文件中获取信息; 存储位置的变化对函数的行为没有影响。

配置文件功能使用以下步骤来定位初始化信息:

  1. 在注册表中查找初始化文件的名称,例如MyFile.ini,在IniFileMapping下:

    HKEY_LOCAL_MACHINE\Software\Microsoft\
            Windows NT\CurrentVersion\IniFileMapping\myfile.ini

  2. 查找由lpAppName指定的部分名称。 这将是myfile.ini下的命名值或myfile.ini的子键,或者不存在。

  3. 如果由lpAppName指定的节名称是myfile.ini下的命名值,那么该值指定注册表中的哪个位置可以找到该节的键。

  4. 如果lpAppName指定的段名是myfile.ini的子项,那么在该子项下的指定值将指定注册表中的哪个位置,您将找到该段的关键字。 如果您正在查找的键不作为命名值存在,则会有一个未命名的值(显示为<No Name>),指定注册表中可找到键的默认位置。

  5. 如果由lpAppName指定的节名不存在作为命名值或作为myfile.ini下的子键,则myfile.ini下将有一个未命名的值(显示为<No Name>),它指定了注册表中的默认位置 您将在那里找到该部分的关键字。

  6. 如果MyFile.ini没有子项,或者没有条目名称,则在磁盘上查找实际的MyFile.ini并阅读其内容。

查看注册表中指定其他注册表位置的值时,会有几个前缀更改.ini文件映射的行为:

  • ! - 此字符强制所有写入都转到注册表和磁盘上的.ini文件。

  • # - 当新用户在安装后首次登录时,此字符会导致将注册表值设置为Windows 3.1 .ini文件中的值。

  • @ - 如果在注册表中找不到所请求的数据,则此字符会阻止任何读取操作转到磁盘上的.ini文件。

  • USR: - 此前缀代表HKEY_CURRENT_USER,前缀后面的文本是相对于该密钥的。

  • SYS: - 此前缀代表HKEY_LOCAL_MACHINE \ SOFTWARE,并且前缀后面的文本与该密钥相关。

Windows 95/98/Me: GetPrivateProfileStringW由Microsoft层为Unicode支持。 要使用它,必须将某些文件添加到应用程序中,如Windows 95/98 / Me系统上的Microsoft Layer for Unicode所述。

要求

  Windows NT/2000/XP: 包含在Windows NT 3.1和更高版本中。

  Windows 95/98/Me: 包含在Windows 95和更高版本中。

  头文件: 声明于 Winbase.h; 包含于 Windows.h.
  库: 使用Kernel32.lib.

  Unicode: 在Windows NT/2000/XP上作为Unicode和ANSI版本实现。 Microsoft层还支持Unicode。