GetProfileString

2.x

int GetProfileString(lpszSection, lpszEntry, lpszDefault, lpszReturnBuffer, cbReturnBuffer)
LPCSTR lpszSection;	/* address of section	*/
LPCSTR lpszEntry;	/* address of entry	*/
LPCSTR lpszDefault;	/* address of default string	*/
LPSTR lpszReturnBuffer;	/* address of destination buffer	*/
int cbReturnBuffer;	/* 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 this value is NULL, all entries in the section specified by the lpszSection parameter are copied to the buffer specified by the lpszReturnBuffer parameter. For more information, see the following Comments section.

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.

cbReturnBuffer

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

Return Value

The return value is the number of bytes copied to the buffer, not including the terminating zero, if the function is successful.

Comments

If the lpszEntry parameter 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 terminating with two null characters. If the supplied destination buffer is too small to hold all the strings, the last string will be truncated and followed by two terminating null characters.

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

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

A string entry in the WIN.INI file must have the following form:

[section]
entry=string
.
.
.

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 zero).

Example

The following example uses the GetProfileString function to list all the entries and strings in the [windows] section of the WIN.INI file:

int c, cc;
PSTR pszBuf, pszKey;
char szMsg[80], szVal[80];

/* Allocate a buffer for the entries. */

pszBuf = (PSTR) LocalAlloc(LMEM_FIXED, 1024);

/* Retrieve all the entries in the [windows] section. */

GetProfileString("windows", NULL, "", pszBuf, 1024);

 /*
  *  Retrieve the string for each entry, until
  *  reaching the double null character.
  */

for (pszKey = pszBuf, c = 0;
        *pszKey != '\0'; pszKey += strlen(pszKey) + 1) {

    /* Retrieve the value for each entry in the buffer. */

    GetProfileString("windows", pszKey, "not found",
        szVal, sizeof(szVal));

    cc = sprintf(szMsg, "%s = %s", pszKey, szVal);
    TextOut(hdc, 10, 15 * c++, szMsg, cc);
}

LocalFree((HANDLE) pszBuf);