Export (0) Print
Expand All
Expand Minimize

SHGetFolderLocation function

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

Syntax


HRESULT SHGetFolderLocation(
  _In_        HWND hwndOwner,
  _In_        int nFolder,
  _In_        HANDLE hToken,
  _Reserved_  DWORD dwReserved,
  _Out_       PIDLIST_ABSOLUTE *ppidl
);

Parameters

hwndOwner [in]

Type: HWND

Reserved.

nFolder [in]

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.

hToken [in]

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.

dwReserved [in]

Type: DWORD

ppidl [out]

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 codeDescription
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

Minimum supported client

Windows 2000 Professional, Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Shlobj.h

Library

Shell32.lib

DLL

Shell32.dll (version 5.0 or later)

See also

IKnownFolder::GetIDList

 

 

Community Additions

ADD
Show:
© 2014 Microsoft