Export (0) Print
Expand All
Expand Minimize

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:
© 2014 Microsoft