Microsoft KB Archive/216954

HOWTO: Support Common Dialog Browsing in a Shell Namespace Extension

Q216954

---

The information in this article applies to:

• Microsoft Win32 Software Development Kit (SDK), on platform(s):
  • Microsoft Windows 98
  • Microsoft Windows 95
  • Microsoft Windows NT Server version 4.0
  • Microsoft Windows NT Workstation version 4.0
  • the operating system: Microsoft Windows 2000

---

SUMMARY

When implementing a shell namespace extension, it is a common misconception that the extension can be easily browsed by using the File Open and Save File As dialog boxes. It is possible to implement a shell namespace extension that can be browsed using these common dialog boxes; however, there are certain requirements that must be fulfilled to make this possible. This article describes what is necessary to implement a shell namespace extension that can be browsed using the common dialogs and the reasons that these steps are necessary.

MORE INFORMATION

The following file is available for download from the Microsoft Download Center:

CDBView.exe

Release Date: May 16, 2000

For additional information about how to download Microsoft Support files, click the article number below to view the article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

Microsoft used the most current virus detection software available on the date of posting to scan this file for viruses. Once posted, the file is housed on secure servers that prevent any unauthorized changes to the file.

Different versions of the operating system have varying levels of support for browsing a shell namespace extension with the common dialogs. The following all assume that your namespace extension follows the implementation guidelines below. The Office file dialog mentioned below refers to the dialog box implemented by Office 97 and Office 2000 to open or save files.

On Windows 95 and Windows NT 4.0 without the Desktop Update (SHELL32.DLL version 4.0), you can browse into a namespace extension that is registered on the Desktop or My Computer or is a junction point within the file system, but the file names will not be created correctly. The Office file dialog will not work with a namespace extension that is registered on the Desktop or My Computer but will work with a namespace extension that is a junction point within the file system.

On Windows 95 and Windows NT 4.0 with the Desktop Update (SHELL32.DLL version 4.71 or greater), you can browse into a namespace extension that is registered on the Desktop or My Computer or is a junction point within the file system, but the file names will not be created correctly. The Office file dialog will work with a namespace extension that is registered on the Desktop or My Computer and also will work with a namespace extension that is a junction point within the file system.

On Windows 98, you can browse into and retrieve file names if the namespace extension is registered on the Desktop or My Computer. If the namespace extension is a junction point within the file system, the namespace extension can be browsed into but the file names will not be created correctly. The Office file dialog will work with a namespace extension that is registered on the Desktop or My Computer and also will work with a namespace extension that is a junction point within the file system.

On Windows 2000, you can browse into and retrieve file names if the namespace extension is registered on the Desktop or My Computer or is a junction point within the file system. The Office file dialog will work with a namespace extension that is registered on the Desktop or My Computer and also will work with a namespace extension that is a junction point within the file system.

Prior to Windows 2000, browsing a shell namespace extension in the common dialogs does not work correctly if the calling application has specified the OFN_ALLOWMULTISELECT flag for the common dialog. This is because when OFN_ALLOWMULTISELECT is specified, the common dialog will call SHGetPathFromID ist and not IShellFolder::GetDisplayNameOf to obtain the name of the objects. This has been corrected in Windows 2000.

To support browsing in your shell namespace extension, all of the following restrictions must be met:

At a minimum, the namespace extension's objects must have the following attributes:

1. The extension's root folder and sub-folders must have both the SFGAO_FILESYSANCESTOR attribute and the SFGAO_FILESYSTEM attribute.
2. The extension's nonfolder items must have the SFGAO_FILESYSTEM attribute and not the SFGAO_FILESYSANCESTOR attribute.

The extension must be able to supply a valid file system path in response to its IShellFolder::GetDisplayNameOf when SHGDN_FORPARSING is specified. For example, assume your extension is rooted off of the Desktop, has the name MyView, and an item with the name MyItem exists under the root of the namespace. When the user attempts to open MyItem, the file common dialogs will obtain the name of the containing folder by calling IShellFolder::GetDisplayNameOf with SHGDN_FORPARSING. In response to this, your namespace extension must supply a valid file system path. If your namespace's local storage is under C:\MyView, then IShellFolder::GetDisplayNameOf must supply the name C:\MyView. The name(s) of the selected item(s) will then be concatenated onto the end of this path. A description of how the common dialogs obtain the item names follows.

NOTE: Your extension's IShellFolder::GetDisplayNameOf must also be able to provide a valid file system path for any item that it contains. This is especially important because future versions of the common dialogs may use this method to obtain the full path to the item name.

When the extension is registered, the following registry entries must be added:

1. Under HKEY_CLASSES_ROOT - CLSID - {<clsid>} - InprocServer32, create a string value with the name of LoadWithoutCOM, leaving the data as an empty string. This allows the shell to load the extension even if COM has not been initialized.
2. Under HKEY_CLASSES_ROOT - CLSID - {<clsid>} - ShellFolder, create a string value with the name WantsFORPARSING, leaving the data as an empty string. This causes the shell to call the extension's IShellFolder::GetDisplayNameOf for the root folder if only the SFGAO_FORPARSING is specified. Without this value, the shell just provides the registered name for the root folder. In some cases, the File dialog box attempts to verify that the name returned by GetDisplayNameOf is a valid path. Because of this, it is necessary to have the extension provide the root folder's name rather than having it come from the registry.

Your namespace extension must also be able to map its root and every folder and item under it to an object that actually exists within the file system. The reason for this is that the common dialog builds the returned name from the path of the folder combined with the name(s) of the selected item(s) (as described above). At no point will the common dialog attempt to obtain the entire name from the extension. Because of this, the extension never has an opportunity to re-map the selected name to the name and location of the "real" file object.

The shell view must call the ICommDlgBrowser methods in response to the proper events. The common dialog's ICommDlgBrowser interface pointer is obtained by calling IShellBrowser::QueryInterface.

Because the common dialog is only hosting the view and not implementing the view, it is necessary for the view to notify the host when certain events occur. If the view does not notify the host, the host will not be able to perform subsequent actions that are necessary for proper operation. The following bullets list the events that the host must be notified of and how to perform this notification.

1. When enumerating the items to be added to the view, the view must call ICommDlgBrowser::IncludeObject for each item to be added. If IncludeObject returns S_OK, then the common dialog has approved the item and it can be added to the view. This method allows the common dialog to filter certain file types. For example, if the common dialog only wants to view objects that have the .txt file extension, IncludeObject will only approve items with the .txt file extension.
2. When the default action is executed on an item in the view, such as when the user double-clicks the item, the view must call ICommDlgBrowser::OnDefaultCommand. If OnDefaultCommand does not return S_OK, the view executes its default command for the item. This allows the common dialog to override the default command. For example, if the user double-clicks a folder object in the view, OnDefaultCommand will not return S_OK, which, in most cases, will cause the view to navigate to the folder. If, however, the user double-clicks an item in the view, the common dialogs interpret this as a command to select the item and close the dialog. In this case, OnDefaultCommand will return S_OK to prevent the view from trying to open the item itself.
3. Whenever the view gains the focus, loses the focus, or an item is renamed or when the selection in the view changes, the view must call ICommDlgBrowser::OnStateChange with the appropriate event flag. This allows the common dialog to take appropriate action in response to the event. The most important of these events is when the selection in the view changes. When the selection in the view changes, the view calls ICommDlgBrowser::OnStateChange with CDBOSC_SELCHANGE. In response to this event, the common dialog will call the extension's IShellView::GetItemObject with IID_IDataObject and SVGIO_SELECTION. The extension must supply an IDataObject that presents the selected items in response to this. Once the IDataObject interface has been obtained, the common dialog will call IDataObject::GetData with CFSTR_SHELLIDLIST to get the ITEMIDLIST(s) for the selected item(s). The data object must supply a correctly filled out CIDA structure in response to this. The common dialog will then use the ITEMIDLIST(s) in a call to IShellFolder::GetDisplayNameOf to get the display name for each item. This is how the common dialog obtains the name(s) for the selected items that it puts in the dialog's edit control.

The common dialog's IShellBrowser does not respond to the SetToolbarItems, SendControlMsg and GetControlWindow methods. The items in the common dialog toolbar are fixed, but will be enabled or disabled based on your namespace extension's response to certain events. On shell versions prior to ver ion 5.0 (Windows 2000), IContextMenu::GetCommandString will be called for the following command strings:

1. CMDSTR_NEWFOLDER - If GetCommandString returns a successful HRESULT, the New Folder button will be enabled. Otherwise, this button will be disabled.
2. CMDSTR_VIEWLIST- If GetCommandString returns a successful HRESULT, the List view button will be enabled. Otherwise, this button will be disabled.
3. CMDSTR_VIEWDETAILS - If GetCommandString returns a successful HRESULT, the Details view button will be enabled. Otherwise, this button will be disabled.

On Windows 2000, the New Folder button is enabled if the currently viewed folder has the SFGAO_FILESYSTEM, SFGAO_FILESYSANCESTOR and SFGAO_FOLDER attributes. The View button is a dropdown toolbar button. However, the common dialog does not forward the TBN_DROPDOWN notification to the view. Therefore, a namespace extension cannot respond to this notification directly.
If you conform to all of the restrictions detailed above, users can browse into your namespace extension using the common dialogs.

Additional query words:

Keywords : kbCmnDlg kbCmnDlgFileO kbCmnDlgSave kbExtension kbNameSpace kbOSWinNT400 kbOSWin2000 kbSDKPlatform kbSDKWin32 kbOSWin95 kbOSWin98 kbGrpDSShell
Issue type : kbhowto
Technology : kbWin32SDKSearch kbAudDeveloper kbSDKSearch

Last Reviewed: June 13, 2001 © 2001 Microsoft Corporation. All rights reserved. Terms of Use.