SHGetKnownFolderIDList function

Retrieves the path of a known folder as an ITEMIDLIST structure.

Syntax

HRESULT SHGetKnownFolderIDList(
  REFKNOWNFOLDERID rfid,
  DWORD            dwFlags,
  HANDLE           hToken,
  PIDLIST_ABSOLUTE *ppidl
);

Parameters

rfid

Type: REFKNOWNFOLDERID

A reference to the KNOWNFOLDERID that identifies the folder. The folders associated with the known folder IDs might not exist on a particular system.

dwFlags

Type: DWORD

Flags that specify special retrieval options. This value can be 0; otherwise, it is one or more of the KNOWN_FOLDER_FLAG values.

hToken

Type: HANDLE

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 SHGetKnownFolderIDList 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.

ppidl

Type: PIDLIST_ABSOLUTE*

When this method returns, contains a pointer to the PIDL of the folder. This parameter is passed uninitialized. The caller is responsible for freeing the returned PIDL when it is no longer needed by calling ILFree.

Return Value

Type: HRESULT

Returns S_OK if successful, or an error value otherwise, including the following:

Return code Description
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 SHGetFolderLocation. That older function is now simply a wrapper for SHGetKnownFolderIDList.

Callers using this function must have at least User privileges.

Some known folders, for example, the Documents folder, are per-user. Each user has a different path for the Documents folder. If hToken is NULL, the API tries to access the current user's instance of the folder. If hToken is a valid user token, the API tries to impersonate the user using this token, and attempts to access that user's instance of the folder.

Requirements

   
Windows version Windows Vista [desktop apps only] Windows Server 2008 [desktop apps only]
Target Platform Windows
Header shlobj_core.h (include Shlobj.h)
Library Shell32.lib
DLL Shell32.dll (version 6.0.6000 or later)

See Also

IKnownFolder::GetPath

Known Folders Sample

SHGetKnownFolderPath

SHSetKnownFolderPath