Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
SHGetFolderPathAndSubDir
Collapse the table of content
Expand the table of content

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.

SHGFP_TYPE_CURRENT

Return the folder's current path.

SHGFP_TYPE_DEFAULT

Return the folder's default path.

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

Shlobj.h

Library

Shell32.lib

DLL

Shell32.dll (version 5.60 or later)

Unicode and ANSI names

SHGetFolderPathAndSubDirW (Unicode) and SHGetFolderPathAndSubDirA (ANSI)

See also

SHGetFolderPath

 

 

Community Additions

ADD
Show:
© 2015 Microsoft