Edit

Share via

SHGetFolderLocation function (shlobj_core.h)

  • Article

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

Syntax

SHSTDAPI SHGetFolderLocation(
  [in]  HWND             hwnd,
  [in]  int              csidl,
  [in]  HANDLE           hToken,
  [in]  DWORD            dwFlags,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parameters

[in] hwnd

Type: HWND

Reserved.

[in] csidl

Type: int

A CSIDL value that identifies the folder to be located. The folders associated with the CSIDLs might not exist on a particular system.

[in] hToken

Type: HANDLE

An access token that can be used to represent a particular user. It is usually set to NULL, but it may be needed when there are multiple users for those folders that are treated as belonging to a single user. The most commonly used folder of this type is My Documents. The calling application is responsible for correct impersonation when hToken is non-NULL. It must have appropriate security privileges for the particular user, 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 SHGetFolderLocation 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 My Documents and Desktop. Any items added to the Default User folder also appear in any new user account.

[in] dwFlags

Type: DWORD

[out] ppidl

Type: PIDLIST_ABSOLUTE*

The address of a pointer to an item identifier list structure that specifies the folder's location relative to the root of the namespace (the desktop). The ppidl parameter is set to NULL on failure. The calling application is responsible for freeing this resource by calling ILFree.

Return value

Type: HRESULT

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

Return code Description
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
 The CSIDL in nFolder is valid but the folder does not exist.
E_INVALIDARG
 The CSIDL in nFolder is not valid.

Remarks

Note  As of Windows Vista, this function is merely a wrapper for SHGetKnownFolderIDList. The CSIDL value is translated to its associated KNOWNFOLDERID and SHGetKnownFolderIDList is called. New applications should use the known folder system rather than the older CSIDL system, which is supported only for backward compatibility.
 
The SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation, and SHGetSpecialFolderPath functions are the preferred ways to obtain handles to folders on systems earlier than Windows Vista. Functions such as ExpandEnvironmentStrings that use the environment variable names directly, in the form %VariableName%, may not be reliable.

This function is a superset of SHGetSpecialFolderLocation, included with earlier versions of the Shell.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header shlobj_core.h (include Shlobj.h)
Library Shell32.lib
DLL Shell32.dll (version 5.0 or later)

See also

IKnownFolder::GetIDList