SHGetFolderPathEx function

[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]

Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID. This extends SHGetKnownFolderPath by allowing you to set the initial size of the string buffer.

Syntax


HRESULT WINAPI SHGetFolderPathEx(
  _In_     REFKNOWNFOLDERID rfid,
  _In_     DWORD            dwFlags,
  _In_opt_ HANDLE           hToken,
  _Out_    LPWSTR           pszPath,
  _In_     UINT             cchPath
);

Parameters

rfid [in]

A reference to the KNOWNFOLDERID that identifies the folder.

dwFlags [in]

Flags that specify special retrieval options. This value can be 0; otherwise, one or more of the KNOWN_FOLDER_FLAG values.

hToken [in, optional]

An access token that represents a particular user. If this parameter is NULL, which is the most common usage, the function requests the known folder for the current user.

Request a specific user's folder by passing the hToken of that user. This is typically done in the context of a service that has sufficient privileges to retrieve the token of a given user. That token must be opened with TOKEN_QUERY and TOKEN_IMPERSONATE rights. In some cases, you also need to include TOKEN_DUPLICATE. In addition to passing the user's hToken, the registry hive of that specific user must be 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 SHGetKnownFolderPath 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 Documents and Desktop. Any items added to the Default User folder also appear in any new user account. Note that access to the Default User folders requires administrator privileges.

pszPath [out]

A null-terminated, Unicode string. This buffer must be of size cchPath. When SHGetFolderPathEx returns successfully, this parameter contains the path for the known folder.

cchPath [in]

The size of the ppszPath buffer, in characters.

Return value

Returns S_OK if successful, or an error value otherwise.

Remarks

Since SHGetFolderPath is a wrapper for SHGetKnownFolderPath, this function (SHGetFolderPathEx) also serves as an extension to SHGetFolderPath.

Requirements

Header

Shlobj.h

Library

Shell32.lib

DLL

Shell32.dll

See also

KNOWNFOLDERID
KNOWN_FOLDER_FLAG
SHGetFolderPath
SHGetKnownFolderIDList
SHGetKnownFolderPath

 

 

Show: