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 code | Description |
|---|---|
|
The CSIDL in nFolder is valid but the folder does not exist. |
|
The CSIDL in nFolder is not valid. |
Remarks
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 |
|
|
Library |
|
|
DLL |
|
See also