WritePrivateProfileStringA 函数 （winbase.h）
将字符串复制到初始化文件的指定节。
语法
BOOL WritePrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
参数
[in] lpAppName
将字符串复制到的节的名称。 如果该节不存在，则会创建它。 节的名称与大小写无关;字符串可以是大写字母和小写字母的任意组合。
[in] lpKeyName
要与字符串关联的键的名称。 如果指定节中不存在该键，则会创建它。 如果此参数 NULL，则会删除整个节（包括节中的所有条目）。
[in] lpString
要写入文件的 null终止字符串。 如果此参数 NULL，则删除 lpKeyName 参数指向的键。
[in] lpFileName
初始化文件的名称。
如果文件是使用 Unicode 字符创建的，该函数会将 Unicode 字符写入文件。 否则，该函数将写入 ANSI 字符。
返回值
如果函数成功将字符串复制到初始化文件，则返回值为非零。
如果函数失败，或者它刷新最近访问的初始化文件的缓存版本，则返回值为零。 若要获取扩展的错误信息，请调用 GetLastError。
言论
初始化文件中的节必须采用以下形式：
[section]
key=string
.
.
.
如果 lpFileName 参数不包含文件的完整路径和文件名，WritePrivateProfileString 搜索文件的 Windows 目录。 如果该文件不存在，此函数将在 Windows 目录中创建该文件。
如果 lpFileName 包含完整路径和文件名，并且该文件不存在，WritePrivateProfileString 创建该文件。 指定的目录必须已存在。
系统保留最新注册表文件映射的缓存版本，以提高性能。 如果所有参数都 NULL，则该函数将刷新缓存。 当系统正在编辑文件的缓存版本时，编辑文件本身的进程将使用原始文件，直到清除缓存为止。
系统使用以下注册表项下定义的映射，将大多数 .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，前缀后的文本相对于该键。
- 确保系统上不存在指定名称的 .ini 文件。
- 确保注册表中有一个指定 .ini 文件的键项。 此条目应位于路径 HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping。
- 指定指定节 .ini 文件键项的值。 也就是说，应用程序必须指定节名称，因为它将显示在 .ini 文件或注册表项中。 下面是一个示例：[我的分区]。
- 对于系统文件，请指定 SYS 作为附加值。
- 对于应用程序文件，请在增加值中指定 USR。 下面是一个示例：“My Section： USR： App Name\Section”。 而且，由于 USR 指示 HKEY_CURRENT_USER下的映射，因此应用程序还应在 HKEY_CURRENT_USER 下创建一个键，以指定附加值中列出的应用程序名称。 对于刚刚给出的示例，即“应用名称”。
- 执行上述步骤后，应用程序安装程序应调用 WritePrivateProfileString，前三个参数设置为 NULL，第四个参数设置为 INI 文件名。 例如：
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" ); - 此类调用会导致 .ini 文件到注册表的映射在下一次系统重新启动之前生效。 系统将映射信息重新读取到共享内存中。 安装应用程序后，用户无需重新启动其计算机，以便将来调用应用程序，即可看到 .ini 文件的映射到注册表。
例子
以下示例代码说明了上述准则，并基于以下几个假设：
- 有一个名为“应用名称”的应用程序。
- 该应用程序使用名为 AppName.ini的 .ini 文件。
- .ini 文件中有一个部分，我们希望如下所示：
[Section1] FirstKey = It all worked out okay. SecondKey = By golly, it works. ThirdKey = Another test. - 用户无需重新启动系统，以便将来调用应用程序，即可看到 .ini 文件到注册表的映射。
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
int main()
{
TCHAR inBuf[80];
HKEY hKey1, hKey2;
DWORD dwDisposition;
LONG lRetCode;
TCHAR szData[] = TEXT("USR:App Name\\Section1");
// Create the .ini file key.
lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE,
TEXT("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\IniFileMapping\\appname.ini"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey1,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating appname.ini key (%d).\n", lRetCode);
return (0) ;
}
// Set a section value
lRetCode = RegSetValueEx ( hKey1,
TEXT("Section1"),
0,
REG_SZ,
(BYTE *)szData,
sizeof(szData));
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in setting Section1 value\n");
// Close the key
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Create an App Name key
lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER,
TEXT("App Name"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey2,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating App Name key (%d).\n", lRetCode);
// Close the key
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Force the system to read the mapping into shared memory
// so that future invocations of the application will see it
// without the user having to reboot the system
WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" );
// Write some added values
WritePrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("It all worked out OK."),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("SecondKey"),
TEXT("By golly, it works!"),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("ThirdKey"),
TEXT("Another test..."),
TEXT("appname.ini"));
// Test
GetPrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("Error: GPPS failed"),
inBuf,
80,
TEXT("appname.ini"));
_tprintf (TEXT("Key: %s\n"), inBuf);
// Close the keys
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
return(1);
}
注意
winbase.h 标头将 WritePrivateProfileString 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
| 支持的最低服务器 | Windows 2000 Server [仅限桌面应用] |
| 目标平台 | 窗户 |
| 标头 | winbase.h （包括 Windows.h） |
| 库 | Kernel32.lib |
| DLL | Kernel32.dll |