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 abstract the actual physical location of a file on a specific system, allowing an application to query the system for the system's actual configuration.

The use of known folders replaces the use of predefined "special folders" identified by CSIDL constants. For more information, see the CSIDL topic.

Known Folders Data

Each known folder is identified by a GUID or a KNOWNFOLDERID, which by convention has a name of FOLDERID_XXXX. These extensible KNOWNFOLDERID values supersede the fixed CSIDLs available in earlier releases of the operating system.

A known folder stores data about the directories it manages under the HKEY_LOCAL_MACHINE subtree in the registry:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\FolderDescriptions

The subkey with the name equal to the GUID contains the values that map to the KNOWNFOLDER_DEFINITION structure, which defines the particular known folder. Applications can create new known folder subkeys in one of two ways:

• As part of installation, an application can define the registry subkeys and values in its application manifest. When an application is installed, a new known folder subkey 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 folder subkey can be created programmatically. This is particularly important in creating per-user settings. An application obtains an IKnownFolderManager interface and calls RegisterFolder, supplying a KNOWNFOLDERID and a KNOWNFOLDER_DEFINITION argument.

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

HKEY_LOCAL_MACHINE\Software\Company\Product\Version\

These settings can be modified or new known folder directories created after installation, but these will require privilege elevation under User Account Protection (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 registry subtree. The registry path should be of the form:

HKEY_CURRENT_USER\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. 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 IShellFolder Interface.

• 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 Folder APIs (SHGetKnownFolderPath or SHGetKnownFolderIDList) to look up system or standard folders (such as Documents). These directories and settings have predefined known folder constants created for them as part of the Windows SDK.

• Define new known folder constants to contain important information, such as application data, user settings, and registry information, and then always look up these folders using the SHGetKnownFolderPath or SHGetKnownFolderIDList function in the Known Folder 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 CSIDL values with SHGetFolderPath, SHGetFolderLocation, SHGetSpecialFolderPath, or SHGetSpecialFolderLocation.

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 KNOWNFOLDERID with the value of FOLDERID_ProgramFiles. The physical path is obtained by calling SHGetKnownFolderPath or SHGetKnownFolderIDList.

• Do not write directly 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_RoamingAppData.

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

• Files needed for downloads and updates should be placed in the Temp folder.

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.

Mapping Known Folders

The Windows namespace, which identifies the conventional locations of important or system folders on the system, has been updated under Windows Vista. The KNOWNFOLDERID topic provides a table that maps KNOWNFOLDERID constants to their CSIDL values and the default location on disk.