BOOL WritePrivateProfileString(lpApplicationName,lpKeyName,lpString,lpFileName)
This function copies the character string pointed to by the lpString parameter into the specified initialization file. It searches the file for the key named by the lpKeyName parameter under the application heading specified by the lpApplicationName parameter. If there is no match, it adds to the user profile a new string entry containing the key name and the key value specified by the lpString parameter. If there is a matching key, the function replaces that key's value with lpString.
| Parameter | Type/Description |
| lpApplicationName | LPSTR Points to an application heading in the initialization file. | |
| lpKeyName | LPSTR Points to a key name that appears under the application heading in the initialization file. | |
| lpString | LPSTR Points to the string that contains the new key value. | |
| lpFileName | LPSTR Points to a null-terminated character string that names the initialization file. If lpFileName does not contain a fully qualified pathname for the file, this function searches the Windows directory for the file. If the file does not exist and lpFileName does not contain a fully qualified pathname, this function creates the file in the Windows directory. The WritePrivateProfileString does not create a file if lpFileName contains the fully qualified pathname of a file that does not exist. |
The return value specifies the result of the function. It is nonzero if the function is successful. Otherwise, it is zero.
An application should use a private (application-specific) initialization file to record information which affects only that application. This improves both the performance of the application and Windows itself by reducing the amount of information that Windows must read when it accesses the initialization file.
If there is no application field for lpApplicationName, this function creates a new application field and places an appropriate key-value line in that field of the initialization file.
A string entry in the initialization file has the following form:
[application name]
keyname = string
.
.
.
An application can also call WritePrivateProfileString to delete lines from its private initialization file. If lpString is NULL, the function deletes the entire line identified by the lpKeyName parameter. If lpString points to a null string, the function deletes only the value; the key name remains in the file. If lpKeyName is NULL, the function deletes the entire section identified by the lpApplicationName parameter; however, the function does not delete any lines beginning with the semicolon (;) comment character.