Edit

Working with Known Folders in Applications

  • Article

The Known Folder system provides a way to interact with certain high-profile folders that are present by default in Windows. It also allows those same interactions with folders installed and registered with the Known Folder system by applications. This topic discusses those possible interactions as they are provided by the Known Folder APIs.

Important

To redirect the Documents, Pictures, or Desktop folders to OneDrive, use OneDrive Known Folder Move instead of the redirection method described in this article. For information, see Redirect and move Windows known folders to OneDrive.

Known Folder Interfaces

There are two Known Folder interfaces: IKnownFolder and IKnownFolderManager.

IKnownFolderManager provides many of the more general functions in regard to these folders. Its methods allow you to:

  • Retrieve an IKnownFolder based on either that folder's KNOWNFOLDERID, its canonical name, its path expressed as a string, or its path expressed as an IDList.
  • Convert a CSIDL to its KNOWNFOLDERID equivalent or convert a KNOWNFOLDERID to its legacy CSIDL equivalent.
  • Register or unregister a Known Folder with the system.
  • Retrieve all KNOWNFOLDERID values registered on that system.
  • Redirect a Known Folder to a new location.

IKnownFolder provides a method that allows a folder to redirect itself by providing a new path. Its other methods get information about a specific Known Folder, including:

  • The category of the folder: virtual, fixed, common, or per-user.
  • The type of the folder, such as compressed, documents, pictures, or user files.
  • The KNOWNFOLDERID of the folder.
  • The full path of the folder as an IDList or as a string. Also its relative path to a parent folder.
  • The canonical name of the folder.
  • The tooltip displayed for the folder.
  • The icon displayed for the folder.
  • A description of the folder that explains its purpose and use.
  • Whether the folder is capable of being redirected.

IKnownFolder also provides a method to retrieve an IShellItem based on the folder. That allows you to bind the folder to a handler, compare two folders, and retrieve the folder's attributes, display name, and parent folder.

Redirection

Folder redirection is an important feature of the known folder system. All known folders of category commonKF_CATEGORY_COMMON**** or per-userKF_CATEGORY_PERUSER**** are redirectable. Folder of category virtualKF_CATEGORY_VIRTUAL**** or fixedrKF_CATEGORY_FIXED****, however, cannot be redirected.

Folders can be redirected either to another location on the same computer or to a location on a network. In the case of a network redirection, the folder can be cached locally through client-side caching to provide offline access. However, even if a local cache exists, the redirected folder itself must be accessed through the network.

Folder redirection is not new for Windows Vista. For example, in Windows XP some folders identified through the CSIDL system could be redirected through a call to SHSetFolderPath or by modifying the CSIDL's entry in the registry. In Windows Vista and later, redirection should be accomplished through IKnownFolder::SetPath or SHSetKnownFolderPath.

To determine whether a folder can be redirected, call IKnownFolder::GetRedirectionCapabilities. If the folder cannot be redirected, this call can give an explanation.

If a folder is redirected to a network location, the IKnownFolder methods can still be successfully called on it.

Known Folders Sample