Developing Quality Applications with Known Folders
Developing Quality Applications with Known Folders
Known Folders

Using the appropriate Windows Vista® and application-specific locations to determine where to store files and registry information keeps an application from conflicting with other applications, and makes it easier to migrate your application or make it accessible to roaming users.

Known Folders abstracts the actual physical location of a file on a specific system, allowing an application to query the system for the system's actual configuration.

Known Folders succeeds the fixed list of predefined "special folders" identified by CSIDL constants. For more information on CSIDL, see the CSIDL section of the Windows SDK.

Known Folders Data

Each Known Folders directory is identified by a GUID or a KNOWN FOLDERID, which by convention has a name of FOLDERID_XXXX. These extensible KNOWN FOLDERID values supersede the fixed CSIDL available in earlier releases of the operating system.

Known Folders stores data about the directories it manages under the HKEY_LOCAL_MACHINE(HKLM) hive in the registry:

HKLM\Software\Microsoft\Windows\CurrentVersion\Explorer\FolderDescriptions

The key with the name equal to the KNOWN FOLDERID name contains the values that map to the KNOWN FOLDER_DEFINITION structure, which defines the particular Known Folder directory. Applications can create new Known Folders keys in one of two ways:

  • As part of installation, an application can define the registry keys and values in its application manifest. When an application is installed, a new Known Folders key is added to the registry.

    For more information on creating manifests, see the Manifest Generation and Editing Tool (Mage.exe) and Manifest Generation and Editing Tool—Graphical Client (MageUI.exe) sections of the Windows SDK documentation and the Visual Studio 2005 documentation.

  • A Known Folders key can be created programmatically. This is particularly important in creating per-user settings. An application obtains an IKnown FolderManager interface and calls RegisterFolder on it, supplying a KNOWN FOLDERID and a KNOWN FOLDER_DEFINITION argument.

All per-computer settings should be created during installation under the HKEY_LOCAL_MACHINE (HKLM) registry hive. The registry path should be of the form:

HKLM\Software\Company\Product\Version\

These settings can be modified or new Known Folder directories created after installation, but these will require privilege elevation under UAP. Per-user settings should be created when an application is first run, or recreated if they do not currently exist in the registry (for example, if a new user logs into a system and runs the application).

Per-user configurations should be stored under the HKEY_CURRENT_USER (HKCU) registry hive. The registry path should be of the form:

HKCU\Software\Company\Product\Version\

Applications can add or modify Known Folders information in the registry at any time.

Known Folders Types

There are four different types of Known Folders directories (folders). All folders must belong to one of the following four categories:

  • Virtual Shell Folders are specified by the constant KF_CATEGORY_VIRTUAL. These folders appear in the shell namespace and do not have any actual file-system folders associated with them. For example, Control Panel and Printers are virtual shell folders. Obtaining a folder path and redirection is not supported for virtual shell folders. These folders have customized IShellFolder interfaces associated with them.

    For more information on IShellFolder, see the "IShellFolder Interface" section of the Windows SDK.

  • Fixed File-System Folders are specified by the constant KF_CATEGORY_FIXED. These folders are file-system folders that are not managed by the shell and whose location is fixed when the system is installed; for example, the Windows folder and Program Files folder. Obtaining a folder path and redirection is not supported for fixed file-system folders.

  • Public (All Users) Folders are specified by the constant KF_CATEGORY_COMMON. These folders are file-system folders used for sharing data and settings between users. For example, C:\Users\Public\Desktop can be shared by all users on a computer as a common desktop folder. Public Folders support redirection and customization.

  • Per-User (Profile) Folders are specified by the constant KF_CATEGORY_PERUSER. These folders contain a user's individual profile and are owned by the user; for example, C:\Users\<UserName>\Documents and C:\Users\<UserName>\Pictures. Per-user folders support redirection and customization.

Using Known Folders

Applications running under Windows Vista should use Known Folders as much as possible and always:

  • Use the Known Folders APIs (SHGetFolderPathEx or SHGetFolderLocationEx) to look up system or standard folders (such as Documents). These directories and settings have predefined Known Folders created for them as part of the Windows SDK.

  • Define new Known Folders to contain important information, such as application data, user settings, and registry information, and then always look up these folders using the SHGetFolderPathEx or SHGetFolderLocationEx function in the Known Folders API. This allows administrators to control the roaming of your data, preventing unwanted access and allowing data to move about.

  • If it is necessary to support backward compatibility with earlier releases (such as Microsoft Windows XP), use the older ShGetFolder and CSIDL values.

It is also a requirement of certification that an application's use of Known Folders be tested against folder redirection.

The following folder usage conventions will allow applications to support Windows Vista roaming and migration technology:

  • Applications that are available to all users (an all-user installation) should be placed in the directory identified by a KNOWN FOLDERID with the value of FOLDERID_ProgramFiles. The physical path is obtained by calling SHGetFolderPathEx or SHGetFolderLocationEx.

  • Do not directly write to the Windows or Program Files directory.

  • Driver, font, or application installation should be handled through installers.

  • Application data used to support roaming on a per-user basis should be stored in the directory indicated by FOLDERID_RoamingApplications Data.

  • Non-roaming data should be stored in the directory indicated by FOLDERID_LocalApplications Data.

  • Files needed for downloads and updates should be placed in FOLDERID_Temp.

Resources

Windows Vista provides Win32 access to Known Folders through C-callable libraries and COM interfaces. .NET Framework 3.0 applications can access this functionality through interoperability support in the Windows SDK. For more information, see the Interoperability & Migration section of this document.

Libraries

Description

shell32.dll

Library containing Known Folders functionality.

Headers

Description

shlobj.h

The header file for Known Folders functionality.

Win32 APIs

Description

SHGetFolderLocationEx

Retrieves the path of a folder as an ITEMIDLIST structure based on a KNOWN FOLDERID identifier.

SHGetFolderPathEx

Takes the KNOWN FOLDERID of a folder and retrieves the path.

SHSetFolderPathEx

Assigns a new path to a system folder through its KNOWN FOLDERID.

COM Interfaces

Description

IKnown Folder

The main COM interface for the Known Folders functionality. It evolved from IFolderInformation. It defines methods that retrieve information about a special folder's type, location, and properties.

IKnown FolderManager

Manages the collection of Known Folders and provides methods for adding custom Known Folders.

IEnumKnownFolder

Enumerator for the collection of Known Folders.

IKnownFolderHandler

Implemented by components needing to add special code for the creation or deletion of a Known Folder.

Mapping Known Folders

The table below maps between Known Folders, the CSIDL values used to specify those folders, and the default Windows Vista location on disk.

NoteNote:

The Windows namespace, which identifies the conventional locations of important or system folders on the system, has been updated under Windows Vista. For more information on changes to the Windows namespace, see Working with the New Windows Namespace section in this document.

The environment variables used in this table are defined as:

Environment variable

Associated path

%ALLUSERSPROFILE%

C:\Documents and Settings

%USERPROFILE%

%ALLUSERSPROFILE%\<UserName>

%APPDATA%

%USERSPROFILE%/Applications Data

%LOCALAPPDATA%

%USERPROFILE%\Programs\Local

%SYSTEMROOT%

C:\Windows

%PROGRAMFILES%

C:\Program Files

Known Folder ID

CSIDL

Default location in Windows Vista

FOLDERID_CommonDocuments

CSIDL_COMMON_DOCUMENTS

%ALLUSERSPROFILE%\Documents

FOLDERID_CommonPictures

CSIDL_COMMON_PICTURES

%ALLUSERSPROFILE%\Pictures

FOLDERID_CommonMusic

CSIDL_COMMON_MUSIC

%ALLUSERSPROFILE%\Music

FOLDERID_CommonVideos

CSIDL_COMMON_VIDE

%ALLUSERSPROFILE%\Videos

FOLDERID_CommonDesktop

CSIDL_COMMON_DESKTOPDIRECTORY

%ALLUSERSPROFILE%\Desktop

FOLDERID_CommonFavorites

CSIDL_COMMON_FAVORITES

%ALLUSERSPROFILE%\Favorites

FOLDERID_CommonDownloads

None

%ALLUSERSPROFILE%\Downloads

FOLDERID_SamplePictures

None

%ALLUSERSPROFILE%\Pictures\Sample Pictures

FOLDERID_SampleMusic

None

%ALLUSERSPROFILE%\Music\Sample Music

FOLDERID_SampleVideos

None

%ALLUSERSPROFILE%\Videos\Sample Videos

FOLDERID_CommonRoamingApplications Data

CSIDL_COMMON_APPLICATIONS DATA

%ALLUSERSPROFILE%\Applications Data\Roaming

FOLDERID_CommonLocalApplications Data

None

%ALLUSERSPROFILE%\Applications Data\Local

FOLDERID_CommonTemplates

CSIDL_COMMON_TEMPLATES

%ALLUSERSPROFILE%\Applications Data\Roaming\Microsoft\Windows\Templates

FOLDERID_CommonStartMenu

CSIDL_COMMON_STARTMENU

%ALLUSERSPROFILE%\Applications Data\Roaming\Microsoft\Windows\Start Menu

FOLDERID_CommonPrograms

CSIDL_COMMON_PROGRAMS

%ALLUSERSPROFILE%\Applications Data\Roaming\Microsoft\Windows\Start Menu\Programs

FOLDERID_CommonStartup

CSIDL_COMMON_STARTUP

%ALLUSERSPROFILE%\Applications Data\Roaming\Microsoft\Windows\Start Menu\Programs\StartUp

N/A

CSIDL_COMMON_ALTSTARTUP

N/A

FOLDERID_CommonAdminTools

CSIDL_COMMON_ADMINTOOLS

%ALLUSERSPROFILE%\Applications Data\Roaming\Microsoft\Windows\Start Menu\Programs\Administrative Tools

FOLDERID_CommonOEMLinks

CSIDL_COMMON_OEM_LINKS

%ALLUSERSPROFILE%\Applications Data\Roaming\OEM Links

FOLDERID_Fonts

CSIDL_FONTS

%SYSTEMROOT%\Fonts

FOLDERID_Windows

CSIDL_WINDOWS

%SYSTEMROOT%

FOLDERID_System

CSIDL_SYSTEM

%SYSTEMROOT%/System32

FOLDERID_SystemX86

CSIDL_SYSTEMX86

%SYSTEMROOT%

FOLDERID_ProgramFiles

CSIDL_PROGRAM_FILES

%PROGRAMFILES%

FOLDERID_ProgramFilesX86

CSIDL_PROGRAM_FILESX86

%PROGRAMFILES%

FOLDERID_ProgramFilesCommon

CSIDL_PROGRAM_FILES_COMMON

%PROGRAMFILES%\Common Files

FOLDERID_ProgramFilesCommonX86

CSIDL_PROGRAM_FILES_COMMONX86

%PROGRAMFILES%\Common Files

FOLDERID_ResourceDir

CSIDL_RESOURCES

%SYSTEMROOT%\resources

FOLDERID_LocalizedResourcesDir

CSIDL_RESOURCES_LOCALIZED

%SYSTEMROOT%\resources\<Locale>

FOLDERID_Profile

CSIDL_PROFILE

%USERPROFILE%

FOLDERID_CommonProfile

None

%ALLUSERPROFILE%\Common

FOLDERID_ProfilesRoot

None

%ALLUSERPROFILE%

FOLDERID_Documents

CSIDL_PERSONAL,CSIDL_MYDOCUMENTS

%USERPROFILE%\Documents

FOLDERID_Pictures

CSIDL_MYPICTURES

%USERPROFILE%\Pictures

FOLDERID_Music

CSIDL_MYMUSIC

%USERPROFILE%\Music

FOLDERID_Videos

CSIDL_MYVIDE

%USERPROFILE%\Videos

FOLDERID_Desktop

CSIDL_DESKTOPDIRECTORY

%USERPROFILE%\Desktop

FOLDERID_Downloads

None

%USERPROFILE%\Downloads

FOLDERID_Favorites

CSIDL_FAVORITES

%USERPROFILE%\Favorites

FOLDERID_RoamingApplications Data

CSIDL_APPLICATIONS DATA

%USERPROFILE%\Applications Data\Roaming, %APPDATA%

FOLDERID_PrintHood

CSIDL_PRINTHOOD

%APPDATA%\Microsoft\Windows\Printer Shortcuts

FOLDERID_NetHood

CSIDL_NETHOOD

%APPDATA%\Microsoft\Windows\Network Shortcuts

FOLDERID_SendTo

CSIDL_SENDT

%APPDATA%\Microsoft\Windows\SendTo

FOLDERID_Templates

CSIDL_TEMPLATES

%APPDATA%\Microsoft\Windows\Templates

FOLDERID_Cookies

CSIDL_COOKIES

%APPDATA%\Microsoft\Windows\Cookies

FOLDERID_Recent

CSIDL_RECENT

%APPDATA%\Microsoft\Windows\Recent

FOLDERID_StartMenu

CSIDL_STARTMENU

%APPDATA%\Microsoft\Windows\Start Menu

FOLDERID_Programs

CSIDL_PROGRAMS

%APPDATA%\Microsoft\Windows\Start Menu\Programs

FOLDERID_Startup

CSIDL_STARTUP

%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup

NA

CSIDL_ALTSTARTUP

N/A

FOLDERID_AdminTools

CSIDL_ADMINTOOLS

%APPDATA%\Microsoft\Windows\Start Menu\Programs\Administrative Tools

FOLDERID_LocalApplications Data

CSIDL_LOCAL_APPLICATIONS DATA

%USERPROFILE%\Applications Data\Local, %LOCALAPPLICATIONS DATA%

FOLDERID_CDBurning

CSIDL_CDBURN_AREA

%LOCALAPPLICATIONS DATA%\Microsoft\Windows\CD Burning

FOLDERID_InternetCache

CSIDL_INTERNET_CACHE

%LOCALAPPLICATIONS DATA%\Microsoft\Windows\Temporary Internet Files

FOLDERID_History

CSIDL_HISTORY

%LOCALAPPLICATIONS DATA%\Microsoft\Windows\History

FOLDERID_QuickLaunch

None

%APPDATA%\Microsoft\Internet Explorer\Quick Launch

FOLDERID_DesktopFolder

CSIDL_DESKTOP

%USERPROFILE%\Desktop

FOLDERID_InternetFolder

CSIDL_INTERNET

%USERPROFILE%

FOLDERID_ControlPanelFolder

CSIDL_CONTROLS

Virtual Shell Folder

FOLDERID_PrintersFolder

CSIDL_PRINTERS

Virtual Shell Folder

FOLDERID_RecycleBinFolder

CSIDL_BITBUCKET

Virtual Shell Folder

FOLDERID_PersonalFolder

CSIDL_PERSONAL, CSIDL_MYDOCUMENTS

%USERPROFILE%\Documents

FOLDERID_MyComputerFolder

CSIDL_DRIVES

Virtual Shell Folder

FOLDERID_NetworkPlacesFolder

CSIDL_NETWORK

Virtual Shell Folder

FOLDERID_ConnectionsFolder

CSIDL_CONNECTIONS

Virtual Shell Folder

FOLDERID_ComputersNearMe

CSIDL_COMPUTERSNEARME

Virtual Shell Folder

FOLDERID_HardwareFolder

None

TODO

FOLDERID_SyncManFolder

None

TODO

FOLDERID_ConflictFolder

None

TODO

FOLDERID_Public

None

TODO

FOLDERID_User

None

TODO

FOLDERID_CommonFolder

None

TODO

Community Content

Errors
Added by:Thomas Lee

FOLDERID_CommonDocuments does not exist, but FOLDERID_PublicDocuments does

CSIDL_MYVIDE entry in the second column should be CSIDL_MYVIDEO

This entry seems to be outdated, incomplete and wrong.

More errrors
Added by:Stanley Roark
%APPDATA% environment variable is not '%USERSPROFILE%/Application Data'. There are several errors.
  • There is no USERSPROFILE variable. It should be USERPROFILE (without the S).
  • The forward slash should be a backslash.
  • There is no "Application Data" folder. It is "AppData".
  • It is missing the "Roaming" component.
  • The whole thing should read "%USERPROFILE%\AppData\Roaming" instead.

%LOCALAPPDATA% environment variable is not '%USERPROFILE%\Programs\Local'

  • There is no "Programs" folder. It should be "AppData".
  • The whole thing should read "%USERPROFILE%\AppData\Local" instead.

%ALLUSERSPROFILE% environment variable is not 'C:\Documents and Settings'

  • On vista there is no "Documents and Settings" folder!
  • On vista it is "C:\ProgramData" instead.

%USERPROFILE% environment variable should not be under '%ALLUSERSPROFILE%'

  • It should be "C:\Users\<UserName>" instead.

Moral of the story: check the environment on a real Vista machine before trusting this documentation.
© 2009 Microsoft Corporation. All rights reserved.   Terms of Use | Trademarks | Privacy Statement
Page view tracker
Rate the Lightweight library
x
Lightweight builds on ScriptFree (loband) by adding features you've requested: a SearchBox and default code language selection.
Do you like the SearchBox?
Do you like the tabbed code blocks?
How useful is this topic?
Tell us more.
Thanks
x
You're helping to improve MSDN Online.
Feedback
Switch View
x
Classic
Lightweight Beta
ScriptFree
Switch View