GetPrivateProfileString

DWORD GetPrivateProfileString(lpszSection, lpszEntry, lpszDefault, lpszReturnBuffer, cchReturnBuffer, lpszFile)
LPCTSTR lpszSection;	/* address of the section name	*/
LPCTSTR lpszEntry;	/* address of the entry name	*/
LPCTSTR lpszDefault;	/* address of the default string	*/
LPTSTR lpszReturnBuffer;	/* address of the destination buffer	*/
DWORD cchReturnBuffer;	/* size of the destination buffer	*/
LPCTSTR lpszFile;	/* address of initialization file name	*/

The GetPrivateProfileString function retrieves a character string from the specified section in the specified initialization file.

Parameters

lpszSection

Points to a null-terminated string that specifies the section containing the key name.

lpszEntry

Points to the null-terminated string containing the entry name whose associated string is to be retrieved. If this value is NULL, all entry names in the section specified by the lpszSection parameter are copied to the buffer specified by the lpszDest parameter.

lpszDefault

Points to a null-terminated string that specifies the default value for the given key if the key cannot be found in the initialization file. This parameter must never be NULL.

lpszReturnBuffer

Points to the buffer that receives the character string.

cchReturnBuffer

Specifies the size (in characters) of the buffer at lpszDest.

lpszFile

Points to a null-terminated string that names the initialization file. If lpszFile does not contain a full path, Windows searches for the file in the Windows directory.

Return Value

If the function is successful, the return value is the number of characters copied to the buffer, not including the terminating null.

If lpszEntry is not NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and null terminated, and the return value is equal to cchReturnBuffer – 1.

If lpszEntry is NULL and the supplied destination buffer is too small to hold all the strings, the last string will be truncated and followed with two null-termination characters. In this case, the return value will be equal to cchReturnBuffer – 2.

Comments

This function searches the file for a key that matches the name specified by the lpszEntry parameter under the section heading specified by the lpszSection parameter. If the key is found, the corresponding string is copied to the buffer. If the key does not exist, the default character string specified by the lpszDefault parameter is copied. A string entry in the initialization file must have the following form:

[section name]

keyname=string

If the lpszEntry parameter is NULL, the GetPrivateProfileString function copies all keynames in the specified section to the supplied buffer. Each string is null terminated, and the final string ends with two null-termination characters. If the supplied destination buffer is too small to hold all the strings, the last string will be truncated and followed with two zero-termination characters.

If the string associated with lpszEntry is enclosed in single or double quotes, the quotes are discarded when the GetPrivateProfileString function returns the string.

The GetPrivateProfileString function is not case dependent, so the strings in lpszSection and lpszEntry may be in any combination of uppercase and lowercase letters.

A program can use the GetProfileString function to retrieve a string from the WIN.INI file.

The lpszDefault parameter must point to a valid string, even if the string is empty (its first character is zero). If lpszDefault is NULL, Windows generates a Fatal Exit.