Handles

  • Article

When a scope item is inserted into the scope pane, MMC creates a handle, or HSCOPEITEM, that uniquely identifies the inserted item. For all items other than the static node, MMC returns the item's HSCOPEITEM after the snap-in successfully inserts the item in the scope pane using IConsoleNameSpace2::InsertItem.

In the case of the static node, MMC itself inserts it into the snap-in's namespace. MMC then passes the static node's HSCOPEITEM to the snap-in as the param parameter in the MMCN_EXPAND notification.

MMC also returns to the snap-in a handle for each inserted result item. This handle, called an HRESULTITEM, is returned after the snap-in successfully inserts the result item using IResultData::InsertItem.

A scope item's handle is valid for as long as the item is present in the snap-in's scope pane. Furthermore, a scope item's handle is the same in all views (MDI child windows). A result item's handle is only valid for as long as the item is displayed in a result pane. When the result pane is torn down, MMC destroys all handles to any of the result items that were displayed in the result pane.

A snap-in needs an item's handle in order to manipulate it using the methods of the IConsoleNameSpace2, IConsole2, and IResultData interfaces. Therefore, the snap-in should store the item's handle after successfully inserting it into the scope pane or result pane. In the case of result items, snap-ins can also acquire a result item's handle by calling the IResultData::FindItemByLParam method, which enables a snap-in to find result item based on the snap-in-defined lParam value (cookie value).

Cookies Compared with Handles

Cookies and handles both refer to inserted scope or result items. However, it's important to keep in mind the following differences between the two:

  • An inserted item's cookie value is determined solely by the snap-in that inserts the item. The snap-in specifies the item's cookie value in the lParam member of the SCOPEDATAITEMor RESULTDATAITEM structure it must fill when inserting the item. MMC caches this value and uses it to uniquely identify the item in calls made to the snap-in's IComponentData::QueryDataObject or IComponent::QueryDataObject implementation.
  • MMC creates an inserted item's handle and returns it to the snap-in after the item is successfully inserted. Snap-ins must specify an item's handle when attempting to manipulate the item using the methods of the IConsoleNameSpace2, IConsole2, or IResultData interface.