Export (0) Print
Expand All
Expand Minimize

SHSetFolderPath function

Deprecated. Assigns a new path to a system folder identified by its CSIDL.

Syntax


HRESULT SHSetFolderPath(
  _In_        int csidl,
  _In_        HANDLE hToken,
  _Reserved_  DWORD dwFlags,
  _In_        LPCTSTR pszPath
);

Parameters

csidl [in]

Type: int

A CSIDL value that identifies the folder whose path is to be set. Only physical folders are valid. If a virtual folder is specified, this function fails.

Add the CSIDL_FLAG_DONT_UNEXPAND value to the CSIDL to ensure that the string is written to the registry exactly as provided. If the CSIDL_FLAG_DONT_UNEXPAND flag is not included, portions of the path may be replaced by environment strings, such as %USERPROFILE%.

hToken [in]

Type: HANDLE

An access token that can be 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.

dwFlags [in]

Type: DWORD

Reserved. Must be set to 0.

pszPath [in]

Type: LPCTSTR

A pointer to a null-terminated string of length MAX_PATH that contains the folder's new path. This value cannot be NULL, and the string cannot be of zero length.

Return value

Type: HRESULT

Returns standard HRESULT codes, including the following:

Return codeDescription
S_OK

The folder's path was successfully updated.

E_INVALIDARG

Several error conditions cause the return of this value, including the following:

  • The csidl value is not valid.
  • The csidl value does not refer to a virtual folder.
  • The csidl value does not refer to a system folder.
  • The csidl value refers to a folder that cannot be renamed or moved.
  • The dwFlags value is not 0 (zero).
  • The pszPath value is NULL.
  • The string pointed to by pszPath value is an empty string ("") of length zero.

 

Remarks

Note  As of Windows Vista, this function is merely a wrapper for SHSetKnownFolderPath. The CSIDL value is translated to its associated KNOWNFOLDERID and SHSetKnownFolderPath is called. New applications should use the known folder system rather than the older CSIDL system, which is supported only for backward compatibility.

SHSetFolderPath is not exported by name from Shell32.dll. To use the function, you must call GetProcAddress with ordinal 231 for SHSetFolderPathA (for ANSI strings) or ordinal 232 for SHSetFolderPathW (for Unicode strings) to obtain a function pointer.

It is recommended that the paths be expressed as Unicode strings because folder names might contain Unicode characters not expressible in ANSI.

Requirements

Minimum supported client

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)

Unicode and ANSI names

SHSetFolderPathW (Unicode) and SHSetFolderPathA (ANSI)

See also

IKnownFolder::SetPath

 

 

Community Additions

ADD
Show:
© 2014 Microsoft