| int GetPrivateProfileString(lpszSection, lpszEntry, lpszDefault, lpszReturnBuffer, cbReturnBuffer, lpszFilename) | |||||
| 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 | */ | |||
| LPCSTR lpszFilename; | /* address of initialization filename | */ | |||
The GetPrivateProfileString function retrieves a character string from the specified section in the specified initialization file.
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 a null-terminated string that specifies 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 receives the character string.
cbReturnBuffer
Specifies the size, in bytes, of the buffer pointed to by the lpszReturnBuffer parameter.
lpszFilename
Points to a null-terminated string that names the initialization file. If this parameter does not contain a full path, Windows searches for the file in the Windows directory.
The return value specifies the number of bytes copied to the specified buffer, not including the terminating null character.
The function searches the file for an entry that matches the name specified by the lpszEntry parameter under the section heading specified by the lpszSection parameter. If the entry is found, its corresponding string is copied to the buffer. If the entry 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]
entry=string
.
.
.
If lpszEntry is NULL, the GetPrivateProfileString 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 zero-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 quotation marks, the marks are discarded when GetPrivateProfileString returns the string.
GetPrivateProfileString is not case-dependent, so the strings in lpszSection and lpszEntry may contain a combination of uppercase and lowercase letters.
An application 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).
The following example uses the GetPrivateProfileString function to determine the last file saved by the [MyApp] application by reading the LastFile entry in TESTCODE.INI:
char szMsg[144], szBuf[80];
GetPrivateProfileString("MyApp", "LastFile",
"", szBuf, sizeof(szBuf), "testcode.ini");
sprintf(szMsg, "last file was %s", szBuf);
MessageBox(hwnd, szMsg, "GetPrivateProfileString", MB_OK);