| BOOL WritePrivateProfileString(lpszSection, lpszEntry, lpszString, lpszFile) | |||||
| LPCTSTR lpszSection; | /* address of section name | */ | |||
| LPCTSTR lpszEntry; | /* address of entry name | */ | |||
| LPCTSTR lpszString; | /* address of string to add | */ | |||
| LPCTSTR lpszFile; | /* address of initialization filename | */ | |||
The WritePrivateProfileString function copies a character string into the specified section of the specified initialization file.
lpszSection
Points to a null-terminated string that specifies the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string may be any combination of uppercase and lowercase letters.
lpszEntry
Points to the null-terminated string containing the entry to be associated with the string. If the entry does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all entries within the section, is deleted.
lpszString
Points to the null-terminated string to be written to the file. If this parameter is NULL, the entry specified by the lpszEntry parameter is deleted.
lpszFile
Points to a null-terminated string that names the initialization file.
The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.
To improve performance, Windows keeps a cached version of the most-recently accessed initialization file. If that filename is specified and the other three parameters are NULL, Windows flushes the cache.
Sections in the initialization file have the following form:
[section]
entry=string
.
.
.
If lpszFile does not contain a fully qualified path and filename for the file, WritePrivateProfileString searches the Windows directory for the file. If the file does not exist, this function creates the file in the Windows directory.
If lpszFile contains a fully qualified path and filename and the file does not exist, this function creates the file. The specified directory must already exist.
An application should use a private (application-specific) initialization file to record information that affects only that application. This improves the performance of both the application and Windows itself by reducing the amount of information that Windows must read when it accesses the initialization file. The exception to this is that device drivers should use the SYSTEM.INI file, to reduce the number of initialization files Windows must open and read during the startup process.
An application can use the WriteProfileString function to add a string to the WIN.INI file.
The WritePrivateProfileString function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).
WriteProfileString