SHGetKnownFolderPath

SHGetKnownFolderPath is a Windows Shell API function that retrieves the full path of a known folder identified by a KNOWNFOLDERID GUID. It is part of the Known Folder API, introduced to provide stable, user- and system-permission aware locations for common data and settings. This API is commonly used as an improvement over earlier folder-path retrieval functions and is supported on Windows Vista and newer.

The function signature is HRESULT SHGetKnownFolderPath(REFKNOWNFOLDERID rfid, DWORD dwFlags, HANDLE hToken, PWSTR ppszPath). The rfid parameter specifies the known folder by GUID (for example, Documents, Desktop, Downloads, AppData, or other well-known folders). The dwFlags parameter controls behavior such as path creation or verification. The hToken parameter can be NULL to use the current user context or can specify a user token to retrieve a path for a different user. The ppszPath parameter receives a pointer to a newly allocated Unicode string containing the folder path. The caller is responsible for freeing this memory using CoTaskMemFree.

On success, the function returns S_OK and ppszPath points to the path string. On failure, an HRESULT error code is returned and ppszPath is not set. The returned string must be freed with CoTaskMemFree when it is no longer needed.

Usage typically requires including ShlObj.h and linking against Shell32.lib. Known folder IDs are defined as GUIDs, allowing applications to request paths for folders such as Documents, Desktop, Downloads, and AppData in a consistent, user-appropriate manner across Windows versions and user profiles.