SHGetSpecialFolderLocation (Windows CE 5.0)

Windows CE 5.0
Send Feedback

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. For specific support information, see the Windows Mobile Remarks section.
ValueDescription
CSIDL_APPDATAFile 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_CONTROLSNot 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_MYMUSICFolder that contains music files.
CSIDL_MYPICTURESFolder that contains picture files.
CSIDL_MYVIDEOFolder 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_PROFILEFolder that contains the profile of the user.
CSIDL_PROGRAM_FILESProgram 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_WINDOWSWindows 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 Values

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

Windows Mobile Remarks

The following table lists support for CSIDL values for the nFolder parameter:

ValueDescription
CSIDL_DESKTOPDIRECTORY Not supported in Windows Mobile 5.0 SDK.
CSIDL_MYMUSICSupported only for a Windows Mobile-based device.
CSIDL_MYPICTURESSupported only for a Windows Mobile-based device.
CSIDL_MYVIDEOSupported only for a Windows Mobile-based device.
CSIDL_NETWORK Not supported in Windows Mobile 5.0 SDK.
CSIDL_PROFILENot supported in Windows Mobile 5.0 SDK.
CSIDL_RECENT Not supported in Windows Mobile 5.0 SDK.

Not supported for a Windows Mobile-based Smartphone.

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

OS Versions: Windows CE 2.12 and later.
Header: Shlobj.h.
Link Library: Ceshell.lib.

See Also

Standard Shell Functions | SHGetSpecialFolderPath


Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.


Show: