Share via

SHGetSpecialFolderLocation (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function retrieves the location of a special folder, such as My Handheld PC, Recycle Bin, Desktop, Printers, Fonts, or various file system directories.

Syntax

WINSHELLAPI HRESULT WINAPI SHGetSpecialFolderLocation(
  HWND hwndOwner, 
  int nFolder, 
  LPITEMIDLIST* ppidl 
);

Parameters

  • hwndOwner
    [in] Handle to the owner window the client should specify if it displays a dialog box or message box.

  • nFolder
    [in] Value specifying the folder for which to retrieve the location. The following table shows the possible values.

    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

    Virtual folder that contains the desktop items. This is the folder at the root of the virtual namespace.

    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.
  • ppidl
    [in] Pointer to a pointer to an item identifier list specifying the folder's location relative to the root of the namespace (the desktop). The calling application is responsible for freeing this pointer with the shell's IMalloc interface (see SHGetMalloc).

Return Value

NOERROR indicates success. An OLE-defined error result indicates failure.

Example Code

The following example shows how to use SHGetSpecialFolderLocation to retrieve the display name and path for the Favorites folder. The StrRetToBuf function is used to convert the STRRET structure returned by IShellFolder::GetDisplayNameOf into a string.

IMalloc * pShellMalloc = NULL;        // A pointer to the shell's IMalloc interface
IShellFolder *psfParent;              // A pointer to the parent folder object's IShellFolder interface.
LPITEMIDLIST pidlItem = NULL;         // The item's PIDL.
LPITEMIDLIST pidlRelative = NULL;     // The item's PIDL relative to the parent folder.
STRRET str;                           // The structure for strings returned from IShellFolder.
WCHAR szDisplayName[MAX_PATH]= L"";   // The display name's string for Favorites
WCHAR szPath[MAX_PATH] = L"";         // The path for Favorites.
HRESULT hres = SHGetMalloc(&pShellMalloc);
if (FAILED(hres))
{
    return hres;
}
hres = SHGetSpecialFolderLocation(NULL,
                                  CSIDL_FAVORITES,
                                  &pidlItem);
if (SUCCEEDED(hres))
{
    hres = SHBindToParent(pidlItem,
                          IID_IShellFolder,
                          (void**)&psfParent,
                          (LPCITEMIDLIST*)&pidlRelative);
    if (SUCCEEDED(hres))
    {
        // Retrieve the display name
        memset(&str, 0, sizeof(str));
        hres = psfParent->GetDisplayNameOf(pidlRelative, SHGDN_NORMAL, &str);
        if (SUCCEEDED(hres))
        {
            StrRetToBuf(&str, pidlItem, szDisplayName, ARRAYSIZE(szDisplayName));
        }
        // Retrieve the path
        memset(&str, 0, sizeof(str));
        hres = psfParent->GetDisplayNameOf(pidlRelative, SHGDN_NORMAL | SHGDN_FORPARSING, &str);
        if (SUCCEEDED(hres))
        {
            StrRetToBuf(&str, pidlItem, szPath, ARRAYSIZE(szPath));
        }
        psfParent->Release();
    }
}
// Clean up allocated memory
if (pidlItem)
{
    pShellMalloc->Free(pidlItem);
}
if (pidlRelative)
{
    pShellMalloc->Free(pidlRelative);
}
pShellMalloc->Release();

Requirements

Header shlobj.h
Library ceshell.lib
Windows Embedded CE Windows CE 2.12 and later

See Also

Reference

Standard Shell Functions
SHGetSpecialFolderPath