IExtendContextMenu::AddMenuItems

[This is preliminary documentation and subject to change.]

Enables a snap-in to add items to a context menu.

HRESULT AddMenuItems(
  LPDATAOBJECT piDataObject,  // Pointer to a data object
  LPCONTEXTMENUCALLBACK piCallback,
                            // Pointer to callback itf
  long * pInsertionAllowed  // Pointer to insertion pt flags
);

Parameters

piDataObject

[in] Pointer to the IDataObject interface on the data object of the menu to which items are being added.

piCallback

[in] Pointer to an IContextMenuCallback that can add items to the context menu.

pInsertionAllowed

[in, out] Identifies MMC-defined menu-item insertion points that can be used. This can be a combination of the following flags:

Value	Meaning
CCM_INSERTIONALLOWED_TOP	Items can be inserted at the top of a context menu.
CCM_INSERTIONALLOWED_NEW	Items can be inserted in the Create New submenu.
CCM_INSERTIONALLOWED_TASK	Items can be inserted in the Task submenu.
CCM_INSERTIONALLOWED_VIEW	Items can be inserted in the toolbar view menu or in the View submenu of the result pane context menu.

Return Values

S_OK: Zero or more items were successfully added to the context menu.
E_UNEXPECTED: An unexpected error occurred.

Remarks

An implementation of IExtendContextMenu::AddMenuItems typically reads the node type and any other parameters needed by calling IDataObject::GetDataHere on piDataObject, then it adds context menu items as appropriate by calling IContextMenuCallback::AddItem on piCallback.

Your snap-in should check the pInsertionsAllowed flags for permission before attempting to add a menu item to the MMC defined insertion points. For example, a snap-in should not add menu items to CCM_INSERTIONPOINTID_PRIMARY_NEW or CCM_INSERTIONPOINTID_3RDPARTY_NEW unless the CCM_INSERTIONALLOWED_NEW flag is set.

These flags allow the following two features:

Subset Context Menus: The console can create context menus which contain a subset of the full context menu items, such as the toolbar View menu. This menu is created in the same manner as a typical context menu except that only the CCM_INSERTIONALLOWED_VIEW flag is set in calls to the snap-in's AddMenuItems method.
Extension Snap-in Restrictions: A primary snap-in is permitted to reset any of the insertion flags in its AddMenuItems method as a way of restricting the kind of menu items that a third-party extension can add. For example, the primary snap-in can clear the CCM_INSERTIONALLOWED_NEW flag to prevent extensions from adding their own Create New menu items.
The primary snap-in should not attempt to set bits in pInsertionAllowed that were originally cleared. Future versions of MMC may use bits not currently defined so the primary snap-in should not change bits not currently defined. Third-party extensions should not attempt to change *pInsertionAllowed at all.

Notes to Callers

This method should not call AddRef on either the piDataObject pointer or the piCallback pointer, nor should it call the methods of those interfaces after returning. Instead, it should make all necessary calls to the methods of those interfaces before returning. If any of these items is selected, you will be given back the pointer to IDataObject in IExtendContextMenu::Command, so do not keep this pointer after this method returns. You will not be notified if the menu is dismissed without any of your items being selected. In addition, do not query for alternate interfaces from piCallback because the one method, IContextMenuCallback::AddItem, should be sufficient.