IKnownFolderManager::RegisterFolder method (shobjidl_core.h)

Adds a new known folder to the registry. Used particularly by independent software vendors (ISVs) that are adding one of their own folders to the known folder system.

Syntax

HRESULT RegisterFolder(
  REFKNOWNFOLDERID             rfid,
  const KNOWNFOLDER_DEFINITION *pKFD
);

Parameters

rfid

Type: REFKNOWNFOLDERID

A GUID that represents the known folder.

pKFD

Type: const KNOWNFOLDER_DEFINITION*

A pointer to a valid KNOWNFOLDER_DEFINITION structure that provides the details of the new folder.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Note  This method updates HKEY_LOCAL_MACHINE and therefore needs to be run in the context of an administrator. Setup programs need administrator privileges to register or unregister a known folder.
 
IKnownFolderManager::RegisterFolder attempts to verify that the new KNOWNFOLDERID does not refer to a file system path already pointed to by an existing KNOWNFOLDERID. If the new KNOWNFOLDERID is found to do so, this method fails.

Multiple KNOWNFOLDERID values for the same file system path can cause several issues, such as conflicts in the Desktop.ini file that lead to confusion as to what language or properties to show for the folder. Multiple KNOWNFOLDERID values can also cause confusion as to the address bar path or what tasks to show for the folder in Windows Explorer.

You can suppress the display of the Customize page of your known folder's Properties window. To do so, set the following registry REG_DWORD value:

            <pre xml:space="preserve"><b>HKEY_LOCAL_MACHINE</b>

   Software       Microsoft          Windows             CurrentVersion                Explorer                   FolderDescriptions                      Folder GUID                         PropertyBag                            NoCustomize = 0x00000001 (1)

Requirements

   
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header shobjidl_core.h (include Shobjidl.h)
DLL Shell32.dll

See also

IKnownFolderManager

IKnownFolderManager::UnregisterFolder

Known Folders Sample