SHGetFolderPathAndSubDir function
Gets the path of a folder and appends a user-provided subfolder path.
Syntax
HRESULT SHGetFolderPathAndSubDir(
_In_ HWND hwnd,
_In_ int csidl,
_In_ HANDLE hToken,
_In_ DWORD dwFlags,
_In_ LPCTSTR pszSubDir,
_Out_ LPTSTR pszPath
);
Parameters
- hwnd [in]
-
Type: HWND
Reserved.
- csidl [in]
-
Type: int
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 fails. You can force creation of a folder with SHGetFolderPathAndSubDir by combining the folder's CSIDL with CSIDL_FLAG_CREATE.
- hToken [in]
-
Type: HANDLE
An access token that represents a particular user. For systems earlier than Windows 2000, set this value to NULL. For later systems, hToken is usually, but not always, set to NULL. You might 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.
- dwFlags [in]
-
Type: DWORD
Specifies whether the path to be returned is the actual path of the folder or the default path. This value is used in cases where the folder associated with a CSIDL value may be moved or renamed by the user.
- pszSubDir [in]
-
Type: LPCTSTR
A pointer to the subpath to be appended to the folder's path. This is a null-terminated string of length MAX_PATH. If you are not creating a new directory, this must be an existing subdirectory or the function returns an error. This value can be NULL if no subpath is to be appended.
- pszPath [out]
-
Type: LPTSTR
When this function returns, this value points to the directory path and appended subpath. This is a null-terminated string of length MAX_PATH. This string is empty when the function returns an error code.
Return value
Type: HRESULT
If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Examples
The following example shows how to use SHGetFolderPathAndSubDir to locate the System32 subdirectory and then create a file within it.
HRESULT hr; TCHAR szPath[MAX_PATH]; // ... if (SUCCEEDED (hr = SHGetFolderPathAndSubDir(NULL, // hWnd CSIDL_WINDOWS, // csidl NULL, // hToken SHGFP_TYPE_CURRENT, // dwFlags TEXT("system32"), // pszSubDir szPath)) // pszPath { PathAppend(szPath, TEXT("New Doc.txt")); HANDLE hFile = CreateFile(szPath, ...); }
Requirements
|
Minimum supported client |
Windows XP [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows Server 2003 [desktop apps only] |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names |
SHGetFolderPathAndSubDirW (Unicode) and SHGetFolderPathAndSubDirA (ANSI) |
See also