Share via


SHGetSpecialFolderPath

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function retrieves the path of a special folder, identified by its CSIDL.

Syntax

BOOL SHGetSpecialFolderPath(
  HWND hwndOwner,
  LPTSTR lpszPath,
  int nFolder,
  BOOL fCreate 
);

Parameters

  • hwndOwner
    [in] Handle to the owner window the client should specify if it displays a dialog box or message box.
  • lpszPath
    [in] Address of a character buffer that receives the drive and path of the specified folder. This buffer must be at least MAX_PATH characters in size.
  • nFolder
    [in] Value specifying the folder for which to retrieve the location. The following table shows the possible values. For Windows Mobile specific support information, see the Remarks section.

    Value Description

    CSIDL_APPDATA

    File system directory that serves as a common repository for application-specific data.

    CSIDL_BITBUCKET

    File system directory that contains file objects in the user's Recycle Bin. The location of this directory is not in the registry; it is marked with the hidden and system attributes to prevent the user from moving or deleting it.

    CSIDL_CONTROLS

    Not supported.

    CSIDL_DESKTOP

    File system directory used to physically store file objects on the desktop.

    CSIDL_DESKTOPDIRECTORY

    File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself).

    CSIDL_DRIVES

    My Computer, which is a virtual folder that contains everything on the local computer: storage devices, and printers. The folder may also contain mapped network drives.

    CSIDL_FAVORITES

    File system directory that serves as a common repository for the user's favorite items.

    CSIDL_FONTS

    Virtual folder containing fonts.

    CSIDL_MYMUSIC

    Folder that contains music files.

    CSIDL_MYPICTURES

    Folder that contains picture files.

    CSIDL_MYVIDEO

    Folder that contains video files.

    CSIDL_NETHOOD

    Not supported.

    CSIDL_NETWORK

    Network Neighborhood Folder, which is a virtual folder that represents the top level of the network hierarchy.

    CSIDL_PERSONAL

    File system directory that serves as a common repository for documents.

    CSIDL_PRINTERS

    Not supported.

    CSIDL_PROFILE

    Folder that contains the profile of the user.

    CSIDL_PROGRAM_FILES

    Program files folder.

    CSIDL_PROGRAMS

    File system directory that contains the user's program groups (which are also file system directories).

    CSIDL_RECENT

    File system directory that contains the user's most recently used documents.

    CSIDL_SENDTO

    Not supported.

    CSIDL_STARTMENU

    File system directory that contains Start menu items.

    CSIDL_STARTUP

    File system directory that corresponds to the user's Startup program group. The system starts these programs when a device is powered on.

    CSIDL_TEMPLATES

    Not supported.

    CSIDL_WINDOWS

    Windows folder.

  • fCreate
    [in] Indicates whether the folder should be created if it does not already exist. If this value is nonzero, the folder is created. If this value is zero, the folder is not created.

Return Value

In the standard shell, this function returns TRUE if it is successful and FALSE if it fails.

If you are using the AYGShell extensions, then this function returns FALSE even if successful. If the folder represented by the CSIDL does not exist and is not created, a NULL string is returned indicating that the directory does not exist.

Note

For Windows Mobile 2003 and later, returns TRUE if successful, FALSE otherwise. For Pocket PC 2002 and Smartphone 2002 and earlier, returns FALSE even if successful. If the folder represented by the nFolder parameter does not exist and is not created, a NULL string is returned indicating that the directory does not exist.

Remarks

A number of folders are used frequently by applications, but may not have the same name or location on any given system. CSIDL values provide a unique system-independent way to identify these special folders. The values supersede the use of environment variables for this purpose.

For Windows Mobile the following table lists support for CSIDL values for the nFolder parameter:

Value Description

CSIDL_BITBUCKET

Not supported.

CSIDL_DESKTOPDIRECTORY

Not supported.

CSIDL_MYMUSIC

Supported only for Windows Mobile devices.

CSIDL_MYPICTURES

Supported only for Windows Mobile devices.

CSIDL_MYVIDEO

Supported only for Windows Mobile devices.

CSIDL_NETWORK

Not supported.

CSIDL_PROFILE

Not supported.

CSIDL_RECENT

Not supported.

Requirements

Header shellapi.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2000 and later, Smartphone 2002 and later