Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

IExtendContextMenu::AddMenuItems method

The IExtendContextMenu::AddMenuItems method enables a snap-in to add items to a context menu.

Syntax


HRESULT AddMenuItems(
  [in]      LPDATAOBJECT          piDataObject,
  [in]      LPCONTEXTMENUCALLBACK piCallback,
  [in, out] long                  *pInsertionAllowed
);

Parameters

piDataObject [in]

A pointer to the IDataObject interface on the data object of the menu to which items are added.

piCallback [in]

A pointer to an IContextMenuCallback that can add items to the context menu.

pInsertionAllowed [in, out]

A value that identifies MMC-defined menu-item insertion points that can be used. This can be a combination of the following flags:

CCM_INSERTIONALLOWED_TOP

Items can be inserted at the top of a context menu.

CCM_INSERTIONALLOWED_NEW

Items can be inserted in the New submenu.

CCM_INSERTIONALLOWED_TASK

Items can be inserted in the All Tasks 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 value

This method can return one of these 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 required by calling IDataObject::GetDataHere on piDataObject, then 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 menu items at 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.

The pInsertionsAllowed flags allow the following two features:

Subset Context Menus

The console can create context menus that 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 kinds 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 New menu items.

The primary snap-in should not attempt to set bits in pInsertionAllowed that were originally cleared. This is because future versions of MMC may use bits not currently defined. Third-party extensions should not attempt to change pInsertionAllowed.

If the user selects a scope item and then displays its context menu, MMC will give both the snap-in's IComponentData and IComponent (that owns the current view) implementations the opportunity to add menu items. MMC calls the IExtendContextMenu::AddMenuItems method implemented by the snap-in's IComponent implementation to allow the snap-in to add menu items to the View menu. MMC calls the IExtendContextMenu::AddMenuItems method implemented by the snap-in's IComponentData to allow the snap-in to add menu items to all other menus. Only the snap-in's IComponent implementation can add items to the View menu.

If the user displays a scope item's context menu without first selecting the scope item, MMC will only give the snap-in's IComponentData implementation the opportunity to add menu items to all menus except for the View menu. Consequently, the View menu only appears for a scope item if the user first selects an item.

Notes to Callers

The AddMenuItems 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.

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2008

Header

Mmc.h

See also

CONTEXTMENUITEM
IContextMenuCallback
IDataObject
IExtendContextMenu
Working with Context Menus

 

 

Show: