IKnownFolderManager::RegisterFolder method (shobjidl_core.h)

Article
10/21/2021

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(
  [in] REFKNOWNFOLDERID             rfid,
  [in] const KNOWNFOLDER_DEFINITION *pKFD
);

Parameters

[in] rfid

Type: REFKNOWNFOLDERID

A GUID that represents the known folder.

[in] 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:

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

Requirements

Requirement	Value
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