Directory Services

Implementing the Context Menu COM Object

A context menu extension is a COM object implemented as an in-proc server. The context menu extension must implement the IShellExtInit and IContextMenu interfaces. A context menu extension is instantiated when the user displays the context menu for an object of a class for which the context menu extension has been registered.

Implementing IShellExtInit

After the context menu extension COM object is instantiated, the IShellExtInit::Initialize method is called. IShellExtInit::Initialize supplies the context menu extension with an IDataObject object that contains data pertinent to the directory object that the context menu applies to.

The IDataObject contains data in the CFSTR_DSOBJECTNAMES format. The CFSTR_DSOBJECTNAMES data format is an HGLOBAL that contains a DSOBJECTNAMES structure. The DSOBJECTNAMES structure contains data about the directory object that the property sheet extension applies to.

The IDataObject also contains data in the CFSTR_DS_DISPLAY_SPEC_OPTIONS format. The CFSTR_DS_DISPLAY_SPEC_OPTIONS data format is an HGLOBAL that contains a DSDISPLAYSPECOPTIONS structure. The DSDISPLAYSPECOPTIONS contains configuration data for use by the extension.

If any value other than S_OK is returned from IShellExtInit::Initialize, the context menu extension will not be used.

The pidlFolder and hkeyProgID parameters of the IShellExtInit::Initialize method are not used.

Implementing IContextMenu

After IShellExtInit::Initialize returns, the IContextMenu::QueryContextMenu method is called to obtain the menu item or items that the context menu extension will add. The QueryContextMenu implementation is fairly straightforward. The context menu extension adds its menu items using the InsertMenuItem or similar function. The menu command identifiers must be greater than or equal to idCmdFirst and must be less than idCmdLast. QueryContextMenu must return the greatest numeric identifier added to the menu plus one. The best way to assign menu command identifiers is to start at zero and work up in sequence. If the context menu extension does not need to any menu items, it should simply not add any items to the menu and return zero from QueryContextMenu.

IContextMenu::GetCommandString is called to retrieve textual data for the menu item, such as help text to be displayed for the menu item. It is possible that the context menu host will use Unicode strings while the extension uses ANSI strings. Because of this, the GCS_HELPTEXTA, GCS_HELPTEXTW, GCS_VERBA and GCS_VERBW cases must be handled individually. Implementation of this method is optional.

IContextMenu::InvokeCommand is called when one of the menu items installed by the context menu extension is selected. The context menu performs or initiates the desired actions in response to this method.