GetProfileString

DWORD GetProfileString(lpszSection, lpszEntry, lpszDefault, lpszReturnBuffer, cchReturnBuffer)
LPCTSTR lpszSection;	/* address of section	*/
LPCTSTR lpszEntry;	/* address of entry	*/
LPCTSTR lpszDefault;	/* address of default string	*/
LPTSTR lpszReturnBuffer;	/* address of destination buffer	*/
DWORD cchReturnBuffer;	/* size of destination buffer	*/

The GetProfileString function retrieves the string associated with an entry within the specified section in the WIN.INI initialization file.

Parameters

lpszSection

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

lpszEntry

Points to the null-terminated string containing the entry whose associated string is to be retrieved.

If lpszEntry is NULL, the GetProfileString function copies all entries in the specified section to the supplied buffer. Each string will be null-terminated, with the final string ending with two null-termination characters.

lpszDefault

Points to the default value for the given entry if the entry cannot be found in the initialization file. This parameter must never be NULL.

lpszReturnBuffer

Points to the buffer that will receive the character string.

cchReturnBuffer

Specifies the size, in characters, of the buffer pointed to by the lpszReturnBuffer parameter.

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

The GetProfileString 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).

If the string associated with lpszEntry is enclosed in single or double quotation marks, the marks are discarded when the GetProfileString function returns the string.

The GetProfileString function is not case dependent, so the strings in lpszSection and lpszEntry may contain a combination of uppercase and lowercase letters.

Sections in the WIN.INI initialization file have the following form:

[section]

entry=value

An application can use the GetPrivateProfileString function to retrieve a string from a specified file.

The lpszDefault parameter must point to a valid string, even if the string is empty (its first character is a null character).