Skip to content

Latest commit

 

History

History
214 lines (157 loc) · 8.12 KB

nf-shlobj_core-shgetfolderpatha.md

File metadata and controls

214 lines (157 loc) · 8.12 KB
Raw
UID title description old-location tech.root ms.assetid ms.date ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames req.redist ms.custom f1_keywords topic_type api_type api_location api_name
NF:shlobj_core.SHGetFolderPathA
SHGetFolderPathA function (shlobj_core.h)
Deprecated. (SHGetFolderPathA)
shell\SHGetFolderPath.htm
shell
a240abc0-e0a6-4f95-8e74-7dc410970212
12/05/2018
SHGFP_TYPE_CURRENT, SHGFP_TYPE_DEFAULT, SHGetFolderPath, SHGetFolderPath function [Windows Shell], SHGetFolderPathA, SHGetFolderPathW, _win32_SHGetFolderPath, _win32_SHGetFolderPath_cpp, shell.SHGetFolderPath, shlobj_core/SHGetFolderPath, shlobj_core/SHGetFolderPathA, shlobj_core/SHGetFolderPathW
shlobj_core.h
Shlobj.h, Shlobj_core.h
Windows
Windows 2000 Professional, Windows XP [desktop apps only]
Windows 2000 Server [desktop apps only]
SHGetFolderPathW (Unicode) and SHGetFolderPathA (ANSI)
Shell32.lib
Shell32.dll (version 5.0 or later)
Windows
19H1
SHGetFolderPathA
shlobj_core/SHGetFolderPathA
APIRef
kbSyntax
DllExport
Shell32.dll
API-MS-Win-shell-shellfolders-l1-1-0.dll
KernelBase.dll
Ext-MS-Win-Shell32-Shellfolders-L1-1-0.dll
Ext-MS-Win-Shell32-Shellfolders-L1-1-1.dll
Windows.Storage.dll
bcrypt.dll
SHGetFolderPath
SHGetFolderPathA
SHGetFolderPathW

SHGetFolderPathA function

-description

Deprecated. Gets the path of a folder identified by a CSIDL value.

Note  As of Windows Vista, this function is merely a wrapper for SHGetKnownFolderPath. The CSIDL value is translated to its associated KNOWNFOLDERID and then SHGetKnownFolderPath is called. New applications should use the known folder system rather than the older CSIDL system, which is supported only for backward compatibility.
 

-parameters

-param hwnd [in]

Type: HWND

Reserved.

-param 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 by combining the folder's CSIDL with CSIDL_FLAG_CREATE.

-param hToken [in]

Type: HANDLE

An access token that can be used to represent a particular user.

Microsoft Windows 2000 and earlier: Always set this parameter to NULL.

Windows XP and later: This parameter is usually set to NULL, but you might need to assign a non-NULL 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 Documents.

The calling process is responsible for correct impersonation when hToken is non-NULL. The calling process must have appropriate security privileges for the particular user, including TOKEN_QUERY and TOKEN_IMPERSONATE, and the user's registry hive must be currently mounted. See Access Control for further discussion of access control issues.

Assigning the hToken parameter a value of -1 indicates the Default User. This enables clients of SHGetFolderPath 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 My Documents and Desktop. Any items added to the Default User folder also appear in any new user account.

-param dwFlags [in]

Type: DWORD

Flags that specify the path to be returned. This value is used in cases where the folder associated with a KNOWNFOLDERID (or CSIDL) can be moved, renamed, redirected, or roamed across languages by a user or administrator.

The known folder system that underlies SHGetFolderPath allows users or administrators to redirect a known folder to a location that suits their needs. This is achieved by calling IKnownFolderManager::Redirect, which sets the "current" value of the folder associated with the SHGFP_TYPE_CURRENT flag.

The default value of the folder, which is the location of the folder if a user or administrator had not redirected it elsewhere, is retrieved by specifying the SHGFP_TYPE_DEFAULT flag. This value can be used to implement a "restore defaults" feature for a known folder.

For example, the default value (SHGFP_TYPE_DEFAULT) for FOLDERID_Music (CSIDL_MYMUSIC) is "C:\Users\user name\Music". If the folder was redirected, the current value (SHGFP_TYPE_CURRENT) might be "D:\Music". If the folder has not been redirected, then SHGFP_TYPE_DEFAULT and SHGFP_TYPE_CURRENT retrieve the same path.

SHGFP_TYPE_CURRENT

Retrieve the folder's current path.

SHGFP_TYPE_DEFAULT

Retrieve the folder's default path.

-param pszPath [out]

Type: LPTSTR

A pointer to a null-terminated string of length MAX_PATH which will receive the path. If an error occurs or S_FALSE is returned, this string will be empty. The returned path does not include a trailing backslash. For example, "C:\Users" is returned rather than "C:\Users\".

-returns

Type: HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

-remarks

This function is a superset of SHGetSpecialFolderPath.

Only some CSIDL values are supported, including the following:

Examples

The following code example uses SHGetFolderPath to find or create a folder and then creates a file in it.

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

-see-also

IKnownFolder::GetPath