SHGetFolderPath Function--------------------------------------------------------------------------------Takes the CSIDL of a folder and returns the pathname.SyntaxHRESULT SHGetFolderPath( HWND hwndOwner, int nFolder, HANDLE hToken, DWORD dwFlags, LPTSTR pszPath ); ParametershwndOwner [in] Handle to an owner window. This parameter is typically set to NULL. If it is not NULL, and a dial-up connection needs to be made to access the folder, a user interface (UI) prompt will appear in this window. nFolder [in] A CSIDL value that identifies the folder whose path is to be retrieved. Only real folders are valid. If a virtual folder is specified, this function will fail. You can force creation of a folder with SHGetFolderPath by combining the folder's CSIDL with CSIDL_FLAG_CREATE. hToken [in] An access token that can be used to represent a particular user. For systems earlier than Microsoft® Windows® 2000, it should be set to NULL. For later systems, hToken is usually set to NULL. 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 My Documents. The caller 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.Assigning the hToken parameter a value of -1 indicates the Default User. This allows clients of SHGetFolderPath 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.dwFlags [in] Flags to specify which path is to be returned. It is used for cases where the folder associated with a CSIDL may be moved or renamed by the user. SHGFP_TYPE_CURRENT Return the folder's current path. SHGFP_TYPE_DEFAULT Return the folder's default path. pszPath [out] Pointer to a null-terminated string of length MAX_PATH which will receive the path. If an error occurs or S_FALSE is returned, this string will be empty. Return ValueReturns standard HRESULT codes, including the following:S_FALSE SHGetFolderPathA only. The CSIDL in nFolder is valid, but the folder does not exist. Note that the failure code is different for the ANSI and Unicode versions of this function. E_FAIL SHGetFolderPathW only. The CSIDL in nFolder is valid, but the folder does not exist. Note that the failure code is different for the ANSI and Unicode versions of this function. E_INVALIDARG The CSIDL in nFolder is not valid. ResThis function is a superset of SHGetSpecialFolderPath, included with earlier versions of the Shell. On systems preceeding those including Shell32.dll version 5.0 (Windows Millennium Edition (Windows Me) and Windows 2000), SHGetFolderPath was obtained through SHFolder.dll, distributed with Microsoft Internet Explorer 4.0 and later versions. SHFolder.dll always calls the current platform's version of this function. If that fails, it will try to simulate the appropriate behavior. SHFolder.dll continues to be included for backward compatibility, though the function is now implemented in Shell32.dll.Only some CSIDLs are supported, including: CSIDL_ADMINTOOLS CSIDL_COMMON_ADMINTOOLS CSIDL_APPDATA CSIDL_COMMON_APPDATA CSIDL_COMMON_DOCUMENTS CSIDL_COOKIES CSIDL_FLAG_CREATE CSIDL_HISTORY CSIDL_INTERNET_CACHE CSIDL_LOCAL_APPDATA CSIDL_MYPICTURES CSIDL_PERSONAL CSIDL_PROGRAM_FILES CSIDL_PROGRAM_FILES_COMMON CSIDL_SYSTEM CSIDL_WINDOWSExampleThe following code fragment uses SHGetFolderPath to find or create a folder and then creates a file in it.TCHAR szPath[MAX_PATH];if(SUCCEEDED(SHGetFolderPath(NULL, CSIDL_PERSONAL|CSIDL_FLAG_CREATE, NULL, 0, szPath))) { PathAppend(szPath, TEXT("New Doc.txt")); HANDLE hFile = CreateFile(szPath, ...); } Function InformationMinimum DLL Version shell32.dll version 5.0 or later Custom Implementation No Header shlobj.h Import library None Minimum operating systems Windows 95 with Internet Explorer 5.0, Windows 98 with Internet Explorer 5.0, Windows 98 Second Edition (SE), Windows NT 4.0 with Internet Explorer 5.0, Windows NT 4.0 with Service Pack 4 (SP4)
int nFolder,
HANDLE hToken,
DWORD dwFlags,
LPTSTR pszPath
);
ParametershwndOwner
[in] Handle to an owner window. This parameter is typically set to NULL. If it is not NULL, and a dial-up connection needs to be made to access the folder, a user interface (UI) prompt will appear in this window.
nFolder
[in] A CSIDL value that identifies the folder whose path is to be retrieved. Only real folders are valid. If a virtual folder is specified, this function will fail. You can force creation of a folder with SHGetFolderPath by combining the folder's CSIDL with CSIDL_FLAG_CREATE.
hToken
[in]
An access token that can be used to represent a particular user. For systems earlier than Microsoft® Windows® 2000, it should be set to NULL. For later systems, hToken is usually set to NULL. 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 My Documents. The caller 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.Assigning the hToken parameter a value of -1 indicates the Default User. This allows clients of SHGetFolderPath 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.dwFlags
[in] Flags to specify which path is to be returned. It is used for cases where the folder associated with a CSIDL may be moved or renamed by the user.
SHGFP_TYPE_CURRENT
Return the folder's current path.
SHGFP_TYPE_DEFAULT
Return the folder's default path.
pszPath
[out] Pointer to a null-terminated string of length MAX_PATH which will receive the path. If an error occurs or S_FALSE is returned, this string will be empty.
Return ValueReturns standard HRESULT codes, including the following:S_FALSE SHGetFolderPathA only. The CSIDL in nFolder is valid, but the folder does not exist. Note that the failure code is different for the ANSI and Unicode versions of this function.
E_FAIL SHGetFolderPathW only. The CSIDL in nFolder is valid, but the folder does not exist. Note that the failure code is different for the ANSI and Unicode versions of this function.
E_INVALIDARG The CSIDL in nFolder is not valid.
ResThis function is a superset of SHGetSpecialFolderPath, included with earlier versions of the Shell. On systems preceeding those including Shell32.dll version 5.0 (Windows Millennium Edition (Windows Me) and Windows 2000), SHGetFolderPath was obtained through SHFolder.dll, distributed with Microsoft Internet Explorer 4.0 and later versions. SHFolder.dll always calls the current platform's version of this function. If that fails, it will try to simulate the appropriate behavior. SHFolder.dll continues to be included for backward compatibility, though the function is now implemented in Shell32.dll.Only some CSIDLs are supported, including: CSIDL_ADMINTOOLS
CSIDL_COMMON_ADMINTOOLS
CSIDL_APPDATA
CSIDL_COMMON_APPDATA
CSIDL_COMMON_DOCUMENTS
CSIDL_COOKIES
CSIDL_FLAG_CREATE
CSIDL_HISTORY
CSIDL_INTERNET_CACHE
CSIDL_LOCAL_APPDATA
CSIDL_MYPICTURES
CSIDL_PERSONAL
CSIDL_PROGRAM_FILES
CSIDL_PROGRAM_FILES_COMMON
CSIDL_SYSTEM
CSIDL_WINDOWSExampleThe following code fragment uses SHGetFolderPath to find or create a folder and then creates a file in it.TCHAR szPath[MAX_PATH];if(SUCCEEDED(SHGetFolderPath(NULL,
CSIDL_PERSONAL|CSIDL_FLAG_CREATE,
NULL,
0,
szPath)))
{
PathAppend(szPath, TEXT("New Doc.txt"));
HANDLE hFile = CreateFile(szPath, ...);
}
Function InformationMinimum DLL Version shell32.dll version 5.0 or later
Custom Implementation No
Header shlobj.h
Import library None
Minimum operating systems Windows 95 with Internet Explorer 5.0, Windows 98 with Internet Explorer 5.0, Windows 98 Second Edition (SE), Windows NT 4.0 with Internet Explorer 5.0, Windows NT 4.0 with Service Pack 4 (SP4)