GetPrivateProfileStringW 函数 （winbase.h）
从初始化文件中的指定节中检索字符串。
语法
DWORD GetPrivateProfileStringW(
[in] LPCWSTR lpAppName,
[in] LPCWSTR lpKeyName,
[in] LPCWSTR lpDefault,
[out] LPWSTR lpReturnedString,
[in] DWORD nSize,
[in] LPCWSTR lpFileName
);
参数
[in] lpAppName
包含密钥名称的节的名称。 如果此参数 NULL，则 GetPrivateProfileString 函数会将文件中的所有节名称复制到提供的缓冲区。
[in] lpKeyName
要检索其关联字符串的密钥的名称。 如果此参数 NULL，则 lpAppName 参数指定的节中的所有键名称将复制到由 lpReturnedString 参数指定的缓冲区。
[in] lpDefault
默认字符串。 如果在初始化文件中找不到 lpKeyName 密钥，GetPrivateProfileString 会将默认字符串复制到 lpReturnedString 缓冲区。
如果此参数 NULL，则默认值为空字符串“”。
避免使用尾随空白字符指定默认字符串。 该函数在 lpReturnedString 缓冲区中插入 null 字符，以去除任何尾随空白。
[out] lpReturnedString
指向接收已检索字符串的缓冲区的指针。
[in] nSize
lpReturnedString 参数指向的缓冲区的大小（以字符为单位）。
[in] lpFileName
初始化文件的名称。 如果此参数不包含文件的完整路径，则系统将在 Windows 目录中搜索该文件。
返回值
返回值是复制到缓冲区的字符数，不包括终止 null 字符。
如果 lpAppName 也没有 lpKeyNameNULL 并且提供的目标缓冲区太小而无法容纳请求的字符串，则字符串将被截断，后跟 null 字符，并且返回值等于 nSize 减 1。
如果 lpAppName 或 lpKeyName为 NULL，并且提供的目标缓冲区太小，无法容纳所有字符串，则最后一个字符串将被截断，后跟两个 null 字符。 在这种情况下，返回值等于 nSize 减 2。
如果未找到由 lpFileName 指定的初始化文件，或包含无效值，此函数将设置 errorno 值“0x2”（找不到文件）。 若要检索扩展的错误信息，请调用 GetLastError。
言论
GetPrivateProfileString 函数在指定的初始化文件中搜索与 lpAppName 参数指定的节标题下 lpKeyName 参数所指定名称匹配的键。 如果找到密钥，该函数会将相应的字符串复制到缓冲区。 如果该键不存在，该函数将复制由 lpDefault 参数指定的默认字符串。 初始化文件中的节必须采用以下形式：
[section]
key=string
.
.
.
如果 lpAppNameNULL，GetPrivateProfileString 将指定文件中的所有节名称复制到提供的缓冲区。 如果 lpKeyNameNULL，则该函数会将指定节中的所有密钥名称复制到提供的缓冲区。 应用程序可以使用此方法枚举文件中的所有节和键。 在任一情况下，每个字符串后跟 null 字符，最后一个字符串后跟第二个 null 字符。 如果提供的目标缓冲区太小而无法容纳所有字符串，则最后一个字符串将被截断，后跟两个 null 字符。
如果与 lpKeyName 关联的字符串括在单引号或双引号中，则当 GetPrivateProfileString 函数检索字符串时，将放弃标记。
GetPrivateProfileString 函数不区分大小写;字符串可以是大写字母和小写字母的组合。
若要从 Win.ini 文件中检索字符串，请使用 GetProfileString 函数。
系统使用以下注册表项定义的映射将大多数 .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，前缀后的文本相对于该键。
例
以下示例演示如何使用 GetPrivateProfileString。
// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
"Preference",
"Preferred Line",
gszNULL,
szBuffer,
MAXBUFSIZE,
gszINIfilename
);
// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
dwPreferredPLID = (DWORD) atoi( szBuffer );
}
else
{
dwPreferredPLID = (DWORD) -1;
}
注意
winbase.h 标头将 GetPrivateProfileString 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
| 支持的最低服务器 | Windows 2000 Server [仅限桌面应用] |
| 目标平台 | 窗户 |
| 标头 | winbase.h （包括 Windows.h） |
| 库 | Kernel32.lib |
| DLL | Kernel32.dll |