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

Syntax

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

Parameters

hwndOwner

[in] Reserved.

nFolder

[in] 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] 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] Reserved. Must be set to 0.

ppidl

[out] 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

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

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.

Function Information

Minimum DLL Version	shell32.dll version 5.0 or later
Custom Implementation	No
Header	shlobj.h
Import library	shell32.lib
Minimum operating systems	Windows 2000, Windows Millennium Edition

See Also

IKnownFolder::GetIDList