SHGetSpecialFolderLocation (Compact 2013)

3/28/2014

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.

Important

For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

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

See Also

Reference

Shell Functions
SHGetSpecialFolderPath