SHGetKnownFolderPath Function
--------------------------------------------------------------------------------
Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID.
Syntax
HRESULT SHGetKnownFolderPath( REFKNOWNFOLDERID rfid,
DWORD dwFlags,
HANDLE hToken,
PWSTR *ppszPath
);
Parameters
rfid
[in] A reference to the KNOWNFOLDERID that identifies the folder.
dwFlags
[in] The KF_FLAG flags that specify special retrieval options. This value can be 0; otherwise, one or more of the KF_FLAG values.
hToken
[in] An
access token used to represent a particular user. This parameter is usually set to NULL, in which case the function tries to
access the current user's instance of the folder. However, you may need to assign a value to hToken for those folders that can have multiple users but are treated as belonging to a single user. The most commonly used folder of this type is Documents.
The calling application is responsible for correct impersonation when hToken is non-null. It must have appropriate security privileges for the particular user, including TOKEN_QUERY and TOKEN_IMPERSONATE, and the user's registry hive must be currently mounted. See
Access Control for further discussion of
access control issues.
Assigning the hToken parameter a value of -1 indicates the Default User. This allows clients of SHGetKnownFolderPath to find folder locations (such as the Desktop folder) for the Default User. The Default User user profile is duplicated when any new user account is created, and includes special folders such as Documents and Desktop. Any items added to the Default User folder also appear in any new user account. Note that
access to the Default User folders requires administrator privileges.
ppszPath
[out] When this method returns, contains the address of a pointer to a null-terminated
Unicode string that specifies the path of the known folder. The calling process is responsible for freeing this resource once it is no longer needed by calling CoTaskMemFree.
Return Value
Returns S_OK if successful, or an error value otherwise, including the following:
E_INVALIDARG Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID that is not present on the system. Not all KNOWNFOLDERID values are present on all systems. Use IKnownFolderManager::GetFolderIds to retrieve the set of KNOWNFOLDERID values for the current system.
Remarks
This function replaces SHGetFolderPath. That older function is now simply a wrapper for SHGetKnownFolderPath.
Function Information
Minimum
DLL Version shell32.dll version 6.0.6000 or later
Custom Implementation No
Header shlobj.h
Import library None
Minimum operating systems Windows Vista