SHGetFolderPathAndSubDirW function (shlobj_core.h)

Article
02/22/2024

Gets the path of a folder and appends a user-provided subfolder path.

Syntax

HRESULT SHGetFolderPathAndSubDirW(
  [in]  HWND    hwnd,
  [in]  int     csidl,
  [in]  HANDLE  hToken,
  [in]  DWORD   dwFlags,
  [in]  LPCWSTR pszSubDir,
  [out] LPWSTR  pszPath
);

Parameters

[in] hwnd

Type: HWND

Reserved.

[in] csidl

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.

[in] hToken

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.

[in] dwFlags

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.

[in] pszSubDir

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.

[out] pszPath

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.

Remarks

Note

The shlobj_core.h header defines SHGetFolderPathAndSubDir 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.60 or later)

Share via