GetPrivateProfileString

GetPrivateProfileString is a Windows API function used to retrieve a string value from an initialization (INI) file. It reads the value associated with a specified key within a given section and copies that value into a caller-provided buffer. The function exists in ANSI and Unicode variants (GetPrivateProfileStringA and GetPrivateProfileStringW), with GetPrivateProfileString typically resolving to the appropriate version based on the character set in use.

The function signature includes six parameters: lpszSection, lpszKey, lpszDefault, lpszReturnedString, cchReturnBuffer, and lpszFileName. lpszSection specifies the section name in the INI file, lpszKey the key name within that section, lpszDefault the string to copy if the key is not found, lpszReturnedString is the buffer that receives the result, cchReturnBuffer is the size of that buffer in characters, and lpszFileName is the path to the INI file.

Behavior and return value: If the specified key exists, its value is copied into the output buffer. If the key is not found, the function copies the default string to the buffer if a default is provided; otherwise the output is empty. The function returns the number of characters copied to the buffer, not including the terminating null character. If the data would not fit, the result is truncated to cchReturnBuffer-1 characters, and the function returns cchReturnBuffer-1. A return value of zero generally indicates either that the key was not found without a default and no data could be copied, or that an error occurred.

Overview: GetPrivateProfileString is part of legacy INI-file handling in Windows. While INI files are still supported, modern applications often use other configuration formats or storage methods. See also related functions such as GetPrivateProfileInt and WritePrivateProfileString.