SHSetFolderPathA function (shlobj_core.h)
Deprecated. Assigns a new path to a system folder identified by its CSIDL.
Syntax
HRESULT SHSetFolderPathA(
[in] int csidl,
[in] HANDLE hToken,
[in] DWORD dwFlags,
[in] LPCSTR pszPath
);
Parameters
[in] csidl
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%.
[in] hToken
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.
[in] dwFlags
Type: DWORD
Reserved. Must be set to 0.
[in] pszPath
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 code | Description |
---|---|
|
The folder's path was successfully updated. |
|
Several error conditions cause the return of this value, including the following:
|
Remarks
It is recommended that the paths be expressed as Unicode strings because folder names might contain Unicode characters not expressible in ANSI.
Note
The shlobj_core.h header defines SHSetFolderPath as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | shlobj_core.h (include Shlobj.h, Shlobj_core.h) |
Library | Shell32.lib |
DLL | Shell32.dll (version 5.0 or later) |