The Microsoft Management Console -- Overview

[This is preliminary documentation and subject to change.]

The Microsoft Management Console (MMC) is an extensible user interface that provides an environment for running systems management applications structured as components called snap-ins. This documentation provides an overview of MMC elements that affect snap-in developers and a reference containing information about all interfaces, methods, functions, structures, enumerations, and enumerations in the header file, mmc.idl.


Purpose of the Console

Many customers in a variety of industries have identified integration, delegation, task orientation, and overall interface simplification as key issues. The Microsoft® Management Console (MMC) provides an improved environment in which Microsoft and ISVs can present management tools called snap-in components (snap-ins).

Microsoft Management Console is a Windows®-based multiple document interface (MDI) application that makes extensive use of Internet technologies. Both Microsoft and ISVs can extend the console by writing MMC snap-ins, which are responsible for performing management tasks.

MMC does not replace existing enterprise management applications, such as Hewlett-Packard OpenView or the IBM Tivoli Management Environment. Instead, it extends these tools by allowing them to interact with or be packaged as snap-ins that can be accessed from the MMC user interface, as indicated in the illustration below. For example, an enterprise management application could detect an event and send an alarm to a snap-in. A system administrator would then see the event in an MMC session and would take appropriate action.


MMC and the Component Object Model

MMC is built using interfaces that conform to the Component Object Model (COM) specification snap-ins are always implemented as a COM in-process (in-proc) server DLL. In case you are unfamiliar with that term, every COM object is implemented inside a server. Your snap-in executes in the same process as MMC so it is implemented as a dynamic-link library (DLL).

A server makes a COM object available by implementing one or more interfaces. These interfaces are based on a binary standard and enable your snap-in to integrate with the console. MMC gains access to your snap-in by obtaining a pointer to one of its interfaces. With this pointer, MMC can use your snap-in without understanding its implementation and can depend on it to behave in a consistent manner all the time.

COM interfaces also provide a way to extend the functionality of the MMC user interface without dictating how each snap-in performs its particular tasks. Implementation is entirely up to the snap-in. In other words, MMC interfaces allow snap-ins to share a common hosting environment and provide cross-application integration, as indicated below:

By using this approach, both Microsoft and ISVs can write administrative applications that are hosted by MMC. This is also true when it comes to developing management tools to run in MMC and writing applications to be managed by MMC administrative tools. The design of MMC allows developers to spend less time building and rebuilding windowing frameworks for tools and more time on the tasks associated with building real management functionality. Once the prerelease phase is complete, MMC will be part of the Microsoft Platform Software Developers Kit (SDK) and available for general use.


Do Other Tools Work With MMC?

Tools written to run on the worldwide web can be integrated directly into MMC, as can tools written as ActiveX™ controls. Non-MMC tools can be integrated with MMC by incorporating them into snap-ins, or they can run separately from the MMC user interface. A systems administrator can have non-MMC management programs running on the computer at the same time as one or more instances of MMC, and use the operating system to switch between them, as you would expect.

Within MMC, administrators can also create shortcuts in the console to any executable program (EXE), script, or uniform resource locator (URL), including non-MMC tools. These shortcuts are persisted when the MMC tool is saved as a .msc document file. Within MMC, administrators can create shortcuts to any EXE, script, or URL.


Can I Write a Snap-In?

If you've never written a COM application, writing a snap-in that's implemented as a COM in-proc server may sound daunting; however, it may not be as difficult as you think. By leveraging the code provided in the sample application accompanying MMC and studying other COM samples, you can reduce the resources required to complete a snap-in.

If you intend to explore COM and ActiveX™ technologies further, you can find more in-depth explanations and code sample in the COM and ActiveX Object Services section of the Microsoft Platform Software Development kit (SDK). Microsoft also provides an invaluable source of sample code in the ActiveX tutorial, which itself also covers topics directly applicable to building snap-ins. Finally, although there is a growing number of books about COM and ActiveX now available, three books from Microsoft Press are particularly informative:

  • Inside OLE (second edition), by Kraig Brockschmidt, 1995. A quintessential programming guide, it is full of technical explanations, details, and samples. This book is also included in the MSDN Library.
  • Inside COM by Dale Rogerson, 1997. (Targets C++ programmers.)
  • Understanding ActiveX and OLE, by David Chappell, 1996. A solid introduction without much code.

Choosing the right development tools can also make a major difference. A COM in-process server can be written in virtually any language that supports function calls, but using C++ is generally the easiest way to implement and use COM. At present, the MMC-specific interfaces described in this documentation do not support Java or Microsoft® Visual Basic®, although this will change further into the development process.

The Step4 sample application included with the MMC software development kit is written in C++ and makes use of the Microsoft Foundation Classes (MFC) and the Active Template Library (ATL). Like you, we do what we can to reduce our coding time and these tools help do just that. You are not required to use Microsoft software development tools, of course, but you will probably benefit by using something that reduces line-by-line coding.

Additional information about MMC is also available on the worldwide web at http://www.microsoft.com/management.


MMC-Related COM Interfaces

The Microsoft Management Console exposes and makes use of COM interfaces, you need to be familiar with the specific interfaces you will be using and implementing. The following introductory list categorizes the interfaces according to the implementor and are given in the same order as shown on the first page of the mmc.idl header file. For details on these interfaces, see the accompanying reference pages.

The node manager is the COM in-process server that contains the MMC interfaces, methods, functions, and so on that the console implements and that can snap-ins use. The following interfaces are implemented by the Node Manager in MMC :

IConsole

IHeaderCtrl

IToolbar

IImageList

IResultData

IConsoleNameSpace

IPropertySheetProvider

IPropertySheetCallback

IContextMenuProvider

IContextMenuCallback

IControlbar

IConsoleVerb

IMenuButton

IQuickFilter

The following interfaces are implemented by the snap-in:

IComponent

IComponentData

IExtendPropertySheet

IExtendContextMenu

IExtendControlbar

IResultDataCompare

ISnapinAbout

IResultOwnerData

Depending on the features you want, you may not need to use or implement all of these interfaces in your particular snap-in. Other sections of this overview refer to these interfaces and their methods frequently so familiarizing yourself with them now may be helpful.


The MMC User Interface

When you first see it, an MMC user interface may look and feel a lot like an MDI version of Explorer. By itself, MMC provides no management behavior and has almost nothing visible in its windows, as shown in the following graphic:

As you can see, the MMC parent frame has a master menu and toolbar. The master menu offers file and window management, along with Help, features that are typical of an MDI parent.

A complete MMC console, however, might look like the one shown in the following illustration:

The MDI child windows provide a variety of views. Each of these child views includes a command bar, a scope pane, and a result pane. The command bar contains both pop-down menus and buttons. The scope pane (the one on the upper left) is a tree view control that displays the tool's namespace, the tree-formatted listing of all visible nodes. Each of these nodes represents a manageable object, task, or view. The scope pane need not be visible in all views.

Each child window's result pane (the one on the upper right of the preceding illustration and the two in the lower part of the parent frame) displays the result of selecting a node in the scope pane. In many cases it lists the contents of a folder, but in other cases it provides a management-related view (such as the performance graph in this example)that can be Web- or ActiveX control-based.

MMC, as shown above, can be configured to provide powerful management tools. MMC is also designed to offer a scaled-down view that is more approachable to less-experienced administrators. In its simplest form, MMC can appear as a task-oriented set of icons.


Scope Pane

Each item in the scope pane is presented as a node identified by a label and represented by a folder icon to the left of an item's label in the tree-view control. The folder is opened when the item is selected and closed when the item is not selected. The snap-in inserts the nodes once into a master tree that is maintained by MMC. For each view created on the same data, the console is responsible for adding the scope pane nodes to the new view's scope pane.

A user can expand the tree by double-clicking an item in the scope pane. The primary snap-in is a container and any subcontainers within it become visible because the node is responsible for enumerating the subcontainers for that scope pane. This enumeration is accomplished by a call to IComponentData::Notify. This method and all other methods belonging to this interface are summarized in Implementing the IComponentData interface.

The scope pane of an MMC tool combines the subcontainers from the snap-ins selected by the creator of the tool. In this way, the administrator can create an MMC tool specific to local needs without modifying snap-in code. This is part of MMC's support for task delegation.

It is up to the snap-in to define the term subcontainer. Regardless of the particular definition, however, you can use the node manager's implementation of IConsoleNameSpace methods to manipulate subcontainers. InsertItem and DeleteItem are used to insert or remove single items from the scope pane. You can set or retrieve single items by using the SetItem and GetItem pair of methods. GetChildItem, GetNextItem, and GetParentItem walk the tree's nodes.

The SCOPEDATAITEM structure is available to pass much of the information handled by IConsoleNameSpace methods.


Result View Pane

Positioned on the right side of the snap-in's windowing frame, the result view pane presents the data within the selected node shown in the scope pane. If the scope pane item is a container, and the result pane is a view that supports enumeration, the result pane displays an enumeration of those contained items. This enumeration is accomplished by a call to IComponent::Notify. All the methods belonging to this interface are summarized in Implementing the IComponent interface.

It is also common to display a custom view in the result pane. In some cases, the selected scope pane node displays a result pane view that is not a standard enumerated view of its children. These nodes are known as viewable containers. If the selected scope pane item is a viewable object, the result pane will be a rendered view of that object. An example of a viewable container is a node that has an OCX or a Web page as its result pane view. Furthermore, the same scope node can take on many views by extending the view context menu. This allows the snap-in to display results in different forms.

Many of the features associated with the result view pane are provided by the console's node manager through interfaces that it implements. For example, IResultData allows a user to manipulate items and the view style associated with the standard result view pane. IResultData methods include InsertItem and DeleteItem, which are used by snap-ins to insert or delete single items in the result view pane, DeleteAllRsltItems allows deletion of all items in the pane. Snap-ins can find items or subitems by using FindItemByLParam. Single items can be set or retrieved using SetItem and GetItem and the next item can be retrieved by using GetNextItem. The view mode can be set or retrieved by using SetViewMode and GetViewMode. The state of a particular item can be modified with ModifyItemState and the result pane's view style can be set with ModifyViewStyle. You can sort all items in the result view pane with Sort and, after changing an item being displayed, the user can update the item using UpdateItem. The text for the result view's description bar can be set by using SetDescBarText.

IHeaderCtrl methods manipulate the number of columns and their text label for the result view pane. With InsertColumn, you can add a column to a default result view; with DeleteColumn you can remove one. You can set the width of a column with SetColumnWidth and retrieve the current width with GetColumnWidth. The SetColumnText method is available to set text in a specified column, and GetColumnText to retrieve current text.

With the IImageList interface, the user can insert images to be used as icons for items in the result view pane. You can use ImageListSetIcon to set an icon in an image list or ImageListSetStrip to set a strip of icons in an image list.

The RESULTDATAITEM structure is used frequently to accomplish much of the work associated with the result view pane.


Snap-In Manager

Another important feature of MMC is the snap-in manager. This the console-provided means of identifying available snap-ins and allowing the user to select and then manipulate a snap-in. The console identifies snap-ins by the information you make available through the system registry. This is explained in the section of this documentation called Snap-In Components and the Registry.

The snap-in manager is responsible for presenting a list of available snap-in components and allowing the user to insert or delete properties in the scope pane. The snap-in manager relies on complete and accurate entries in the system registry. Accordingly, snap-ins should be self-registering and should complete this task as part of the installation sequence.

If you are writing a snap in, you need to understand that during this phase of console configuration the console requests the snap-in to optionally put up a configuration wizard for gathering settings during the insertion process. The console passes in the CCT_SNAPIN_MANAGER as a value for the DATA_OBJECT_TYPES.


Nodes in the MMC NameSpace

The node manager is the COM in-process server that implements all the interfaces that the console and snap-ins use. It is the most important aspect of the console. It includes the code required for your snap-in to function within the console's environment. If you've looked at the list of MMC-related interfaces, you probably noticed that the node manager implements the majority of them. As a result, much of the functionality you are likely to want for your snap-in is already available to you.

The node manager creates instances of your in-process server as needed and calls the methods of the interfaces your server offers. In turn, your server can call the methods of the interfaces that the node manager offers, thereby incorporating features such as toolbars, context menus, and property sheets. If you don't extend the console in at least one way, your snap-in will never be loaded.

For any instance of a snap-in, one object exposing IComponentData is created using CoCreateInstance, a function fully explained in the Microsoft Platform SDK. For each view of the snap-in (that is, each MDI child window), MMC asks IComponentData::CreateComponent to create an instance of an object exposing IComponent. Most snap-ins internally create a new instance of the object for each request. This simplifies the internal memory model for the snap-in author. The snap-in can get added any number of times. For each time, however, another object exposing IComponentData is created.


Nodes and the Node Manager

Snap-in components and the objects they manage are represented in the scope pane as nodes on a tree control. These nodes can be divided into three types:

  • Built-in nodes
  • Static nodes
  • Enumerated nodes

Built-in nodes include shortcuts, HTML pages, ActiveX™ controls (OCXs), and several other categories. They are implemented by MMC and do not interact directly with your snap-in OLE server. The other two types of nodes, static and enumerated, each offers a viewing mechanism: details view, HTML control, and OCX.

A node's most important property is its node type (known by your system as the nodetype). This is a GUID (a COM acronym that stands for "globally unique identifier") that describes the node's overall type such as whether it's a user, a machine, a domain entry in a DNS database, or something else. A node type is defined by the individual snap-in rather than by MMC and even though it is a GUID, this is so only because it is a dependable way to avoid name collisions. GUIDs in this context have no COM significance, although you generate them using uuidgen.exe just as you would other GUIDs. This procedure is documented in the OLE Programmers Reference included in the Platform SDK CD.

Every node type implies one or more clipboard formats that a data object for any node of that node type must support. For example, the node type for a user might imply that the object supports clipboard formats that provide the domain where the user is located, plus the distinguished name of the user. With a few exceptions these clipboard formats, and the format of the data they return, are defined by the snap-in, not by MMC. For example, a snap-in could show the NodeType in both GUID and string formats. Entering these clipboard formats in the system registry to make them available for use could then be done by using the Win32 RegisterClipboardFormat function, which is documented in the Platform SDK.

Each data object must support four specific clipboard formats:

CCF_NODETYPE

CCF_SZNODETYPE

CCF_DISPLAY_NAME

CCF_SNAPIN_CLASSID

The first two are the node type's GUID in CLSID (class identifier) and string form. CCF_DISPLAY_NAME is used by MMC's Snap-In Manager to provide the snap-in an opportunity to change the default name of the snap-in. Finally, CCF_SNAPIN_CLASSID is the snap-in coclass identifier. For more information about CLSIDs and related topics, see the Microsoft Platform SDK.

In all cases, MMC uses IDataObject::GetDataHere and specifies the medium and format. For example, MMC (through the node manager) determines the node type by calling IDataObject::GetDataHere on the data object for a specified node, using clipboard format CCF_NODETYPE. This particular format must be supported but this does not imply that MMC treats nodes differently according to node type; instead, the node type provides a way to determine which other snap-ins extend that node. For example, when a snap-in registers itself as extending the property sheets of objects generated by other snap-ins, it actually extends the property sheets for nodes of one or more specific node types. The GetDataHere method is provided as part of COM and is documented in the Platform SDK.

MMC Static Nodes

A static node is a node in the MMC namespace that is present as long as the snap-in providing it is loaded. Snap-ins must implement IComponentData to have static nodes in the tree. The first time a static node is accessed in an MDI child, MMC calls CoCreateInstance to create an instance of the snap-in COM server that owns this static node in this MDI child. Each static node in each MDI child has a different instance of the COM server, even when the same snap-in owns more than one static node, or when the same node appears in more than one view.

Standalone snap-ins use static nodes to store their setup configuration and relative placement in the console. This node is inserted when the snap-in is added to the console on behalf of the snap-in. It has a cookie value equal to NULL. The snap-in needs to be prepared to get notifications on a NULL cookie just like any other node.

MMC Enumerated Nodes

Every static node in each MDI child can have its own subtree of enumerated nodes. These enumerated nodes are not persisted by MMC to the .MSC file; rather, the snap-in rebuilds them in each view as needed. The children of enumerated nodes are always other enumerated nodes, never static or built-in nodes.

When the user selects or expands the static node in the scope pane, the snap-in's implementation of IComponentData is notified and gets the opportunity to add enumerated nodes as children of that static node. Similarly, the same IComponentData is notified when one of those enumerated children is selected or expanded. The same IComponentData serves the static node and all of its enumerated children belonging to the snap-in that owns the static node.

If there is more than one MDI child viewing a static node, the node will appear the same in each MDI child.


Persistence Model

One of the great strengths of MMC is its ability to be persistently stored with all data necessary to re-create the tool on any machine. For this reason, a snap-in can implement the OLE interface, IPersistStorage. This interface allows you to make use of OLE's compound file implementation of structured storage. If IPersistStorage is not implemented, IPersistStream is called as an alternative. The latter is a simpler interface for snap-ins whose properties fit in a single stream. IPersistStreamInit can also be used.

The console implements the IStorage interface that generates a storage file. The name of the file is never known to the snap-in but, at some point, the console calls QueryInterface to get a pointer to the snap-in's IPersistStorage. The snap-in's data is loaded and saved, although the console never reads the content of the resulting file. The file is assigned a .MSC extension and the console, in effect, provides storage and allows the snap-in to persist. All of the interfaces noted here are provided as part of COM and are documented in the Platform SDK.


Snap-In Components

MMC is the host for tools that you develop. Thus, the console itself has no management behavior, and you provide snap-ins to extend the console. MMC allows snap-ins to expose behavior through one or more supported extension mechanisms.


Snap-In Modes: Stand-Alone and Extensions

Every Snap-In provides some external functionality to administrators. In addition, each Snap-In supports one or both of the following internal modes (these modes are transparent to the user except in Snap-In Manager, where the user will be asked to decide which mode the particular Snap-In will have.)


Stand-Alone Snap-In

A stand alone Snap-In provides management functionality even if there are no other supporting Snap-Ins. Snap-Ins designed for this mode cannot rely on any other Snap-Ins being present.


Extension Snap-In

An extension Snap-In provides functionality only when invoked by a primary Snap-In. An extension Snap-In can extend given node types only. It declares itself as being a subordinate to nodes of certain types, and then for each occurrence of those node types, the console automatically adds the related Snap-In extensions.

For example, an extension snap-in might be a "Log Pretty Print" Snap-In, providing users several ways to print out log files (such as the Windows NT Event Log). With this snap-in installed, every log object in the namespace would be extended with the "Pretty Print" context menu item.

Extension Snap-Ins can provide a variety of functionality. Some can actually extend the console namespace (for example, a Snap-In that provides system information about computers would add that information to the namespace under each computer in the namespace), while others simply extend context menus or specific wizards. For more information, see the section, Extension Features For Snap-Ins, later in this document.


Dual Mode Snap-In

Many Snap-Ins will support both modes of operation, offering some stand-alone functionality and also extending the functionality of other snap-ins. For example, the Windows NT Event Log snap-in reads the event logs of computers. If the MyComputer object exists in the console, the event log Snap-In automatically extends each instance of a MyComputer object and provides the event logs for that computer. Alternatively, the event log can also operate in stand-alone mode, in which case an administrator must manually provide a computer name when the snap-in is opened, and the snap-in simply provides the event logs of this one computer.

Almost all snap-ins are expected to function standalone, and it's quite common to see snap-ins supporting both modes of behavior. Generally, a snap-in built to support either of these modes is built the same way. The main difference is in how they are registered. Incidentally, the sample snap-in provided with this software development kit is dual mode.


Snap-In Components and the Registry

Following is the registry layout used by the Microsoft Management Console. Two registry keys, each with a set of subkeys, are used as the basis for all required entries. The first is called the SnapIns key and it contains the CLSID of the snap-in. The second key is called NodeTypes and contains the GUID of the snap-in's node type.


The SnapIns Registry Key

Only snap-ins that extend the namespace should be registered here, which also means any snap-in that can be inserted by using the snap-in manager. The following example shows the SnapIns key entry and the subkeys that might be required beneath it.

Incidentally, do not use these GUIDs for your own applications. They are examples only.

HKEY_LOCAL_MACHINE\Software\Microsoft\MMC\Snapins {04ebc1e6-a16c-11d0-a799-00c04fd8d565}

NameString = REG_SZ "Snap-In Name"

About = REG_SZ "{128ac4e6-a16c-11d0-a799-00c04fd8d565}"

NodeTypes

{c713e06c-a16e-11d0-a799-00c04fd8d565}

{c713e06d-a16e-11d0-a799-00c04fd8d565}

{c713e06e-a16e-11d0-a799-00c04fd8d565}

{c713e06f-a16e-11d0-a799-00c04fd8d565}

StandAlone

RequiredExtensions

{a2087336-a16c-11d0-a799-00c04fd8d565}

{70098cd3-a16c-11d0-a799-00c04fd8d565}

Some of the subkeys under the SnapIns key are optional and may not be necessary for your application. Following are definitions of the subkeys shown above:

NameString
The name of the snap-in.
About
CLSID of the object that will be created using the CoCreateInstance COM function to get the interface pointer to ISnapInAbout.
NodeTypes
Enumerate all the node type GUIDs that may be displayed by this snap-in.
StandAlone
[Optional] Add the StandAlone key only if the snap-in can appear by itself under the Console Root. If this key is not present, the snap-in is assumed to be a namespace extension snap-in.

Also note that a stand-alone snap-in can also be an extension snap-in (that is, it can extend some other snap-in.

RequiredExtensions
[Optional] Enumerate the CLSIDs of extension snap-ins that are required for this snap-in to function.


The NodeTypes Registry Key

As noted elsewhere, the snap-in's nodetype is identified by a GUID that describes the node's overall type such as whether it's a user, a machine, a domain entry in a DNS database, or something else. The following example shows a sample entry for the NodeTypes key, and the subkey entries associated with extensions that may be required beneath it.

Incidentally, do not use these GUIDs for your own applications. They are examples only.

HKEY_LOCAL_MACHINE\Software\Microsoft\MMC\NodeTypes

{12345601-EA27-11CF-ADCF-00AA00A80033}

= REG_SZ "Log object"

Extensions

NameSpace

{19876201-EA27-11CF-ADCF-00AA00A80033}

= REG_SZ "Alert SnapIn"

{34346202-EA27-11CF-ADCF-00AA00A80033}

= REG_SZ "Viewer Snap-In"

ContextMenu

{19876202-EA27-11CF-ADCF-00AA00A80033}

= REG_SZ "Alert Snap-In"

{34346202-EA27-11CF-ADCF-00AA00A80033}

= REG_SZ "Viewer Snap-In"

ToolBar

{19876202-EA27-11CF-ADCF-00AA00A80033}

= REG_SZ "Alert Snap-In"

{45091ca8-EA27-11CF-ADCF-00AA00A80033}

= REG_SZ "Crystal Report"

PropertySheet

{19876202-EA27-11CF-ADCF-00AA00A80033}

= REG_SZ "Alert Snap-In"

If a snap-in is designed only to extend another snap-in, it must also register itself under the particular NodeTypes subkey that it extends and must indicate the type of extension it has. Following are explanations of subkey uses:

NameSpace
List the CLSIDs of snap-ins that can extend the namespace of this nodetype.
ContextMenu'
List the CLSIDs of snap-ins that can extend the context menu of items put up by this nodetype.
ToolBar
List the CLSIDs of snap-ins that can extend the toolbar of items put up by this nodetype.
PropertySheet
List the CLSIDs of snap-ins that can extend the property sheet of items displayed by this nodetype.

For general information about the registry, see Installing Applications and related sections of the Microsoft Platform SDK.


Console and Snap-in Communication

MMC is based on COM interfaces and it implements a variety of interfaces through which a snap-in can implement its own interfaces to communicate with the console and perform assigned tasks. Foremost among those interfaces the snap-in's interface to the console, IConsole.

The snap-in implements IComponentData and IComponent interfaces specifically to interact with IConsole. Looking at IComponentData first, any snap-in component that extends the namespace is an IConsole and IComponentData pair. The IComponent interface is closely associated with items displayed in the result view pane and is typically implemented at the view level. IComponent is required for any snap-in component that will enumerate items in the result pane.


Using the IConsole Interface

Every instance of a snap-in that exists in the scope pane is unique and IConsole's methods preserve that uniqueness. You use SetHeader and SetToolbar to associate the IHeaderCtrl and IToolbar interfaces with the snap-in's instance of IConsole and to provide column headers and toolbars associated with the result view pane. You can use QueryResultView to get a pointer to an IUnknown interface to the result pane control only if your view is a custom OCX. This is the way to get the pointer to the IDispatch interface, which is documented in the Platform SDK.

QueryScopeImageList and QueryResultImageList allow you to get interface pointers to the console-provided image lists for their respective panes. QueryConsoleVerb allows the snap-in to incorporate the functionality of standard verbs like cut, copy, and paste, while SelectScopeItem is used to select a particular scope pane item. UpdateAllViews generates a notification to update one or more views because the content has changed. You can obtain a handle to the main frame window by using GetMainWindow. The remaining IConsole method is MessageBox, which the snap in uses to provide feedback information.


Implementing the IComponentData Interface

Every snap-in that extends the namespace must implement IComponentData. As noted earlier, this is one of the console's interfaces to the snap-in and is closely associated with the functionality of the items (folders) displayed in the scope pane.

Among the IComponentData methods, Initialize provides an entry point for the snap-in by allowing QueryInterface calls to the IConsole and IConsoleNamespace interfaces. Initialize must be called before the namespace can be enumerated. CreateComponent is used to create a snap-in's object that exposes the IComponent interface.

Notify is called by the console to inform the snap-in component of an event that has occurred as the application's end user clicks on the mouse and so on. Destroy releases all interfaces to the console such as IConsole and IConsoleNamespace. You should be aware that MMC remains in a state in which everything can be queried during the call to Destroy so the snap-in can get information from the console. On return from Destroy, however, data integrity cannot be guaranteed.

QueryDataObject is used to get a data object for a specific cookie, including the static folder (NULL cookie). The data object type is taken from the DATA_OBJECT_TYPES enumeration and is used to determine the context in which someone is asking for the data object. A CCT_SCOPE flag is set to indicate that the data object is for the scope pane. CCT_RESULT is set to indicate it is for the result view pane, and another, CCT_SNAPIN_MANAGER, indicates when the snap-in manager is being used. Another constant, CCT_UNITIALIZED indicates that the data object has an invalid type. Given context information, the snap-in can determine the context in which it is being asked for a data object.

For example, when inserting a snap-in into the scope pane using the snap-in manager (CCT_SNAPIN_MANAGER), the snap-in may use one set of property pages on the static node (folder). After it has been inserted into the scope pane, the user may issue a Properties request on the folder. A request for a data object must be made. The context type CCT_SCOPE is used, giving the same snap-in the option of displaying different property sheets. This behavior is not required, but the console provides the information anyway.

As noted earlier, IConsole is the snap-in's interface to the console, and objects that expose the IDataObject interface are used to pass context information from the snap-in to the console or between snap-ins. IDataObject is documented in the Platform SDK.

The GetDisplayInfo method retrieves display information for a namespace item in the scope pane. This is similar to the Win32 callback mode for the tree-view control. CompareObjects provides a way for a snap-in component to compare two data objects and determine whether they refer to the same physical object. This method is used for detecting duplicate property sheets. The snap-in must compare the two managed objects.


Implementing the IComponent Interface

Every snap-in that enumerates items in the result pane must implement IComponent. Similar to IComponentData, this is one of the console's interfaces to the snap-in and is closely associated with the functionality of the items displayed in the result pane.

Among the IComponent methods, Initialize provides an entry point for the snap-in by allowing QueryInterface calls to IConsole. Notify is called by the console to notify the snap-in component that an event has occurred as a result of a user action. Destroy releases all interfaces to the console such as IConsole.

QueryDataObject returns a pointer to a data object that can be used to retrieve context information for a specified cookie. The data object type is taken from the DATA_OBJECT_TYPES enumeration and is used to determine the context in which someone is asking for the data object. A CCT_SCOPE flag is set to indicate that the data object is for the scope pane. CCT_RESULT is set to indicate it is for the result view pane. Another constant, CCT_UNITIALIZED indicates that the data object has an invalid type.

As noted earlier, IConsole is the snap-in's interface to the console, and objects with the IDataObject interface on them are used to pass context information from the snap-in to the console. IDataObject is documented in the Platform SDK.

GetResultViewType returns the result view type for a particular cookie that determines what the result pane control should be. This could be the default list view, an OCX (an ActiveX control) CLSID string, or a URL path. The GetDisplayInfo method retrieves display information for an item in the result pane. CompareObjects provides a way for a snap-in component to compare two result-view pane items.


Context Information

Context information is data shared between snap-ins. In MMC, information is shared based on hierarchy. The console itself acts like a snap-in, and root snap-ins thus get base context information. This data comes from basic information, command line parameters, and other sources. Snap-ins are responsible for providing data to their own nodes in that the console has no need to know or interfere with how a snap-in disseminates information to its own nodes.

The COM interface IDataObject is implemented by the snap-in, and data is shared in clipboard formats. This interface includes methods that enable data to be transferred and notifications to be generated when data changes. The console uses IDataObject::GetDataHere to get the information. This interface and method are documented in the Platform SDK.

Snap-ins are required to support four formats and the TYMED is always an HGLOBAL.

Calling AddRef (also documented in the Platform SDK) to increment the reference count on these data objects is generally not advantageous because it is possible that the snap-in could unload by the time it is needed. If the snap-in uses the function call that it was handed, the data object is guaranteed to be valid, unless an exception such as an access violation occurs.


Extension Features for Snap-Ins

The following sections summarize the interfaces associated with features of snap-ins that can be extended. The modes of extensibility currently available include:

  • NameSpace
  • Context Menus
  • Toolbars and Toolbar Buttons
  • Property Pages


Extending the NameSpace

A simplified way to understand which snap-ins extend the MMC namespace is to remember that any snap-in you can insert by using the Snap-In Manager extends the namespace. For more information, see Implementing the IComponent Interface.


Extending Context Menus for Snap-Ins

MMC will generate default context menus for the items in the scope and result panes, and snap-ins may extend these default context menus. The default context menus contain items for the Create New and Task menus. These default menus are integral to the usability of the console, because they provide lists of the methods (or tasks) that can be invoked on a given node or a list of the objects that can be created within a given container.

Snap-ins extend these context menus by implementing IExtendContextMenu, where the snap-in's implementation of IExtendContextMenu will call methods in IContextMenuCallback which is implemented by MMC. Some snap-ins will also call methods in IContextMenuProvider (also implemented by MMC) when they need to build a context menu from scratch.

IContextMenuCallback is a callback mechanism that has one method, AddItem, for adding single items to a context menu. MMC will provide the snap-in with an instance of IContextMenuCallback when one is needed. Snap-ins should not call QueryInterface for an instance of IContextMenuCallback, nor should they keep the instance of IContextMenuCallback beyond the scope in which it is provided.

IExtendContextMenu is implemented by the snap-in and allows items to be added using the callback mechanism just mentioned. MMC will call AddMenuItems to give the extension an opportunity to add menu items; the snap-in will typically call IContextMenuCallback::AddItem zero or more times to add items to the context menu. MMC will call Command if an when one of the items added by AddMenuItems is chosen.

Most snap-ins will not need to use IContextMenuProvider. This interface allows snap-ins to add extensible context menus to result pane views other than the default list view. For example, if the view is an OCX, the snap-in could always create the context menu itself using the Win32 API. The problem is that using Win32 does not allow other snap-ins to extend this context menu as they could on other nodes. Instead, the OCX should call QueryInterface for a pointer to IContextMenuProvider, and generate the context menu using its COM methods. This context menu can then be extended by other snap-ins. Incidentally, IContextMenuProvider derives from IContextMenuCallback, so it implicitly contains the AddItem method.

IContextMenuProvider methods include EmptyMenuList, which clears the context menu and ShowContextMenu, which displays the menu. Its two remaining methods, AddPrimaryExtensionItems and AddThirdPartyExtensionItems, give other snap-ins the opportunity to extend the context menu.

The snap-in that has added an item to the scope or result pane is always considered to "extend" the context menu. MMC will always call its implementation of IExtendContextMenu::AddMenuItems if that snap-in implements IExtendContextMenu. Snap-ins that wish to extend context menus for items which they did not add themselves must explicitly register themselves as being context menu extensions for nodes of that particular node type.

When a snap-in adds a menu item, it must specify an insertion point in the context menu where that item should be located. The default context menus created by MMC contain a set of insertion points where extension snap-ins may add items. To maintain consistency, snap-ins may not add items other than at those predefined insertion points. Snap-ins creating context menus from scratch using IContextMenuProvider must add these insertion points themselves in order to allow other extensions to add items to those context menus.

The CONTEXTMENUITEM structure provides a variety of flags that can be set to manage MMC context menus, even when they are nested deeply and items are to be inserted in specific positions on the menu. The node manager enforces menu integrity.


Extending Toolbars and Toolbar Buttons for Snap-Ins

Toolbars are among the most-frequently included features in today's applications and the Microsoft Management Console makes taking advantage of them rather simple. Your snap-in can either extend the toolbars made available by the console or it can provide its own. There are several interfaces related to this feature, beginning with IControlbar. This interface allows for creating and manipulating a control bar to hold toolbars and other controls. This interface's methods includes Create, which is used to create and return the control requested. At this time, this can be either a toolbar or a combo box bar. The other IControlbar methods are Attach, which associates a control with the control bar, and Detach, which breaks that association. You should also use these methods to use display or hide the toolbar.

The IExtendControlbar interface allows an extension snap-in to add toolbars by using a callback interface, and has two methods. The first is SetControlBar, which gets a pointer to the IControlbar interface implemented by the console. The second method, ControlbarNotify, is the mechanism that allows the snap-in to respond to user actions such as mouse-button clicks. When the user causes an event, the node manager sends a notification message to the snap-in. All notifications applicable to MMC are listed alphabetically in MMC Notifications.

IToolbar is implemented by the console and it allows your snap-in to perform a variety of actions related to toolbars, including creating them, adding items to them, extending them, and displaying them. AddBitmap allows you to add an image to the toolbar, and AddButtons provides a way to add an array of buttons to the toolbar. To add a single button, you can use InsertButton and to remove one, you can use DeleteButton. Finally, you can get an attribute of a button by using GetButtonState and set an attribute with SetButtonState.

The last interface you have to consider when working with toolbars is IConsoleVerb. The verbs are listed in the MMC_CONSOLE_VERB enumeration and include cut, copy, paste, print, and others you would expect to see. You can determine the state of a verb by using the GetVerbState method and you can set the state with SetVerbState.


Extending Property Pages for Snap-Ins

Property page extensions are based on a per-node extensibility mechanism so a snap-in can add one or more property pages to a property frame. More than one snap-in can be registered to extend behavior in this way for a given node. The size of the property sheet is determined by the primary snap-in and extensions are forced to accept that size. MMC implements two property sheet interfaces, IPropertySheetProvider and IPropertySheetCallback to incorporate property page extensions. The snap-in implements a third, IExtendPropertySheet.

The concept behind IPropertySheetProvider is similar to that for context menus: it implements Win32 property sheets as COM objects. This interface includes five methods. CreatePropertySheet is used to create a property sheet frame and FindPropertySheet determines whether a property sheet already exists. AddPrimaryPages collects pages from a primary snap-in and AddExtensionPages collects pages from extension snap-ins. Show displays a specific property sheet frame.

IPropertySheetCallback is a callback mechanism that incorporates two methods. AddPage allows a snap-in to add a single page to a property sheet and RemovePage allows a snap-in to remove a page.

Property pages are offered by snap-ins and by the console itself. The snap-in creates a page frame and adds its own items. Snap-ins can optionally ask the console to add pages provided by extension snap-ins. The console adds pages from extension snap-ins and returns control to the owner snap-in. Page size is determined by the primary snap-in and extension snap-ins are forced to use the same size. Maintaining a consistent size promotes usability and looks much better. A property page is another example of a feature being reusable because it is a COM object.


Providing Your Snap-In's About Information

The standard method of providing version and provider information within most applications the run on Windows platforms, is the About menu selection item. The Microsoft Management Console supports providing this type of information by snap-in applications. The information is displayed on a property page and is made available by using the ISnapinAbout interface.

Methods belonging to ISnapinAbout include GetSnapinDescription, which provides text for the snap-in's description box. GetProvider handles the name of the provider, and GetSnapinVersion obtains the snap-in's version number. GetSnapinImage gets the main icon for the About property page, and GetStaticFolderImage gets the static folder images for the scope and result panes.


Owner Data / Virtual Lists

Owner data, also referred to as a virtual list, is supported by the IResultOwnerData interface. See IResultOwnerData for information and implementation details.


Drag and Drop

Drag and drop works automatically, if copy, delete, and paste work.


Copy/Delete/Paste

Copy, delete, and paste are based on the standard verbs. The snap-in controls the standard verbs by setting the console verbs when it gets an MMCN_SELECT notification.

If one item in a group of selected items can be copied or deleted, then the copy and delete verbs will be enabled.

Paste is disabled for multiselection.

Copy

Nothing is required by the snap-in to implement copy.

Delete

The snap-in has to handle the MMCN_DELETE and MMCN_CUTORMOVE notifications.

Paste

The snap-in has to handle the MMCN_QUERY_PASTE and MMCN_PASTE notifications.


Multi-Selection

Multiselection is allowed only in the result pane. By default multiselection is off in the list view. To enable multiselection, set the multiselection flag (MMC_VIEW_OPTIONS_MULTISELECT) in the ViewOptions param for IComponent::GetResultViewType.

What happens on multiselect, depends on the items that are selected. There are three possible scenarios.

  1. The multiselection includes the selection of one or more Static Nodes.
  2. No static node is selected, but items (nodes and/or leaves) from multiple snap-ins are selected.
  3. Only items (nodes and/or leaves) from a single snap-in are selected.


Multi Selection and Standard Verbs:

For multi-selection, verbs behave as follows:

  1. Open and Refresh are disabled by default.
  2. Copy, Paste and Delete are inclusive. That is, if one of the selected items can be copied, then Copy will be enabled. The same is true for the Paste and Delete verbs.
  3. Property and Print are exclusive and are applicable only for case-C above. Their state depends the snap-in.


Snap-in Extensions:

Snap-in extensions are exclusive. Only snap-ins that extend all the selected items are valid.


Multi selection and the Data Objects Used For Communication

If snap-in items are included in multiselection includes, the console queries the snap-ins for a multiselect data object. This is done by passing the special cookie MMC_MULTI_SELECT_COOKIE to the QueryDataObject call.

The snap-in provided multiselection data object (SI-MS-DO) that will be returned MUST provide the list of object types of all the currently selected items put by the snap-in in the CCF_OBJECT_TYPES_IN_MULTI_SELECT clipboard format. The data for this format will be cast as a pointer to SMMCObjectTypes structure.

The console will use this structure to determine the extension snap-ins.

The console also creates a composite data object consisting of an array of these snap-in provided multiselection data objects from all the selected snap-ins, (MMC-MS-DO). The clipboard format for the array of snap-in provided multiselection data object is CCF_MULTI_SELECT_SNAPINS, and the data can be cast as a pointer to SMMCDataObjects structure.

The data object passed to the snap-in for notifications when multiple items are selected is shown in the table at the end of this section.

Another data object, CUTORMOVE_DO, is best understood in terms of the paste process. If objects that are being pasted need to be deleted at the source as a result of a previous cut or move operation, then the param for MMCN_PASTE will be a pointer to a boolean or a pointer to LPDATAOBJECT, depending on whether one item is selected or multiple items are selected (determined from the data object). If the paste is successful, the destination snap-in should return TRUE for single-selection data objects. For multiple-selection data objects, the destination snap-in should return the CUTORMOVE_DO data object, which in turn will be passed to the source snap-in for the MMCN_CUTORMOVE notification. The format to communicate the list of items successfully pasted should be defined by the source snap-in. Note that the param for MMCN_PASTE will be 0, if it does not involve a previous cut or move operation.

Notification | Data object sent
MMCN_BTN_CLICK | MMC-MS-DO
MMCN_CONTEXTMENU | MMC-MS-DO
MMCN_CUTORMOVE | CUTORMOVE_DO
MMCN_DELETE | SI_MS_DO
MMCN_QUERY_PASTE | MMC-MS-DO
MMCN_PASTE | SI_MS_DO
MMCN_SELECT | SI_MS_DO


MMC Reference

Microsoft® Console (MMC) interfaces and their methods are arranged alphabetically in the reference section. However, the methods are also provided in vtable order on the page describing each interface. This listing is found in the topic MMC Interfaces and Methods.


MMC Interfaces and Methods

IComponent

IComponentData

IConsole

IConsoleNameSpace

IConsoleVerb

IContextMenuCallback

IContextMenuProvider

IControlbar

IExtendContextMenu

IExtendControlbar

IExtendPropertySheet

IHeaderCtrl

IImageList

IMenuButton

IPropertySheetCallback

IPropertySheetProvider

IQuickFilter

IResultData

IResultDataCompare

IResultOwnerData

ISnapinAbout

IToolbar


IComponent

The IComponent interface enables the Microsoft® Management Console to communicate with snap-in components. Similar to the IComponentData interface, IComponent is typically implemented at the view level and is closely associated with items being displayed in the result pane.

When to Implement

Implement the IComponent interface in your in-process (in-proc) server DLL to communicate with the console,.which displays the result pane and enumerates the items it contains.

When to Use

Your snap-in component must expose the IComponent interface if it enumerates items in the result pane because the snap-in cannot enumerate without it. Extension snap-ins that do not extend the namespace (but extend other features like context menus, toolbars, and so on) do not need to implement this interface or the IComponentData interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IComponent Methods | Description
Initialize | Provides an entry point to the console.
Notify | Called by the console to notify the snap-in of actions taken by a user.
Destroy | Releases all references to the console.
QueryDataObject | Returns a data object that can be used to retrieve context information for the specified cookie.
GetResultViewType | Determines what the result pane view should be.
GetDisplayInfo | Retrieves display information about an item in the result pane.
CompareObjects | Enables a snap-in to compare two data objects acquired through QueryDataObject. Note that data objects can be acquired from two different instances of IComponent.


IComponent::CompareObjects

Enables a snap-in component to compare two data objects acquired through IComponent::QueryDataObject. Note that data objects can be acquired from two different instances of IComponent.

HRESULT CompareObjects(
  LPDATAOBJECT lpDataObjectA,  // pointer to the first data object
  LPDATAOBJECT lpDataObjectB  // pointer to the second data object
);

Parameters

lpDataObjectA
[in] Pointer to the first object exposing an IDataObject interface that is to be compared.
lpDataObjectB
[in] Pointer to the second object exposing an IDataObject interface that is to be compared.

Return Values

S_OK
The comparison was successful.
S_FALSE
The comparison was unsuccessful.
E_UNEXPECTED
An unexpected error occurred.

Remarks

The IDataObject interface is documented in the Platform SDK.

See Also

IComponent, IComponentData, IConsole


IComponent::Destroy

Releases all references to the console.

HRESULT Destroy(
  LONG cookie  // reserved
);

Parameter

cookie
Reserved. Not in use at this time.

Return Values

S_OK
Indicates that all the references to the console were successfully released.
E_UNEXPECTED
An unexpected error occurred.

Remarks

The snap-in is in the process of being unloaded. Release all references to the console.

Notes to Callers

Only the console calls this method.

See Also

IComponent


IComponent::GetDisplayInfo

Retrieves display information for an item in the result pane.

HRESULT GetDisplayInfo(
  RESULTDATAITEM * pResultDataItem  // pointer to a result item
);

Parameters

pResultDataItem
[in, out] Pointer to a RESULTDATAITEM structure. On input, the mask member specifies the type of information required and the lParam member identifies the item of interest. When called for a virtual list, the nIndex member identifies the desired virtual item and the lParam member is zero.

Return Values

S_OK
Display information was successfully retrieved.
E_UNEXPECTED
An unexpected error occurred.

See Also

IComponent, IComponentData, IConsole


IComponent::GetResultViewType

Determines what the result pane view should be.

HRESULT GetResultViewType(
  long cookie,            // unique identifier
  LPOLESTR * ppViewType,  // pointer to address of the view
  long * pViewOptions     // pointer to view options
);

Parameters

cookie
[in] Specifies the unique identifier associated with scope items for which the result-view type is required.
ppViewType
[out] Pointer to the address of the returned view type for the specified cookie.
pViewOptions
[out] Pointer to the MMC_VIEW_OPTIONS enumeration, which provides the console with options specified by the owning snap-in. This value can be a combination of the following:
Value | Meaning
MMC_VIEW_OPTIONS_
NOLISTVIEWS = 0x0001 		Tells the console to refrain from presenting standard list view choices in the View menu. Allows the snap-in to display its own custom views only in the result view pane.
MMC_VIEW_OPTIONS_OWNERDATALIST = 0x0002 | Specifies that the result pane list view should be a virtual list.
MMC_VIEW_OPTIONS_MULTISELECT = 0x0004 | Allows multiple item selections in the result pane view.
MMC_VIEW_OPTIONS_NONE
= 0 		Allows the default view options.

Return Values

S_OK
The returned view type was either an OLE custom control (OCX) CLSID string or a URL.
S_FALSE
The default list view should be used.
E_UNEXPECTED
An unexpected error occurred.
E_OUTOFMEMORY
Not enough memory to complete the operation.

Remarks

The caller will allocate using CoTaskMemAlloc and the called will free it using CoTaskMemFree. These functions are documented in the Platform SDK.

A cookie is a pointer to a structure containing information unique to a specific item that is passed in through the lParam member of a SCOPEDATAITEM structure.

See Also

IComponent, IDataObject


IComponent::Initialize

Provides an entry point to the console. At this point, the snap-in should set up the toolbar. If the snap-in uses the default list view it should also set up the list view's headers and add images to be used in the result pane.

HRESULT Initialize(
  LPCONSOLE lpConsole,  // pointer to IConsole's IUnknown
);

Parameters

lpConsole
[in] Pointer to the IConsole interface's IUnknown interface. This interface pointer can be used to call QueryInterface for IConsole.

Return Values

S_OK
Successfully initialized.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
One or more parameters is NULL.

Remarks

IComponent::Initialize is called when a snap-in is being created and has items to enumerate in the result pane. The pointer to IConsole that is passed in is used to make QueryInterface calls to the console for interfaces such as IResultData.

See Also

IComponent, IComponent::Destroy, IDataObject, IConsole


IComponent::Notify

Notifies the snap-in of actions taken by the user.

HRESULT Notify(
  LPDATAOBJECT lpDataObject,  // pointer to a data object
  MMC_NOTIFY_TYPE event,  // action taken by a user
  long arg,               // depends on event
  long param              // depends on event
);

Parameters

lpDataObject
[in] Pointer to the data object of the currently selected item.
event
[in] Identifies an action taken by a user. IComponent::Notify can receive the following notifications:
  • MMCN_ACTIVATE_slate_MMCN_ACTIVATE
  • MMCN_ADD_IMAGES_slate_MMCN_ADD_IMAGES
  • MMCN_BTN_CLICK_slate_MMCN_BTN_CLICK
  • MMCN_CLICK_slate_MMCN_CLICK
  • MMCN_DBLCLICK_slate_MMCN_DBLCLICK
  • MMCN_DELETE_slate_MMCN_DELETE
  • MMCN_EXPAND_slate_MMCN_EXPAND
  • MMCN_MINIMIZED_slate_MMCN_MINIMIZED
  • MMCN_PROPERTY_CHANGE_slate_MMCN_PROPERTY_CHANGE
  • MMCN_REMOVE_CHILDREN_slate_MMCN_REMOVE_CHILDREN
  • MMCN_RENAME_slate_MMCN_RENAME
  • MMCN_SELECT_slate_MMCN_SELECT
  • MMCN_SHOW_slate_MMCN_SHOW
  • MMCN_VIEW_CHANGE_slate_MMCN_VIEW_CHANGE
arg
Depends on the notification type.
param
Depends on the notification type.

Return Values

S_OK
Depends on the notification type.
E_UNEXPECTED
An unexpected error occurred.

Remarks

See individual notifications for detailed information.

See Also

IComponent, IComponentData, IConsole, IExtendControlbar::ControlbarNotify


IComponent::QueryDataObject

Returns a data object that can be used to retrieve context information for the specified cookie.

HRESULT QueryDataObject(
  long cookie,             // unique identifier
  DATA_OBJECT_TYPES type,  // type of the data object
  LPDATAOBJECT * ppDataObject  // pointer to address of the object
);

Parameters

cookie
[in] Specifies the unique identifier for which the data object is required. When called for virtual list items, which don't have cookies, this parameter is set to the item's list index.
type
[in] Specifies the data object as one of the following:
Value | Meaning
CCT_SCOPE = 0x8000 | Data object for the scope pane.
CCT_RESULT = 0x8001 | Data object for the result pane.
CCT_SNAPIN_MANAGER = 0x8002 | Data object for the Snap-in Manager context.
CCT_UNITIALIZED = 0xFFFF | Data object has an invalid type.

These constants are members of the DATA_OBJECT_TYPES enumeration.

ppDataObject
[out] Pointer to the address of the returned data object.

Return Values

S_OK
The data object was successfully returned.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
One or more parameters are invalid.

Remarks

These data objects can be passed to the same snap-in or to extension snap-ins that require them. Some of the MMC interfaces that may use this data object are IComponent, IComponentData, IContextMenuProvider, IExtendContextMenu, IPropertySheetProvider, and IExtendPropertySheet.

See Also

IComponent, IComponentData::QueryDataObject, IDataObject


IComponentData

The IComponentData interface enables the Microsoft® Management Console (MMC) to communicate with snap-in components. Similar to the IComponent interface, IComponentData is typically implemented at the document level and is closely associated with items (folders) being displayed in the scope pane.

When to Implement

Implement IComponentData in your in-proc server DLL to communicate with the console's Node Manager. It enumerats a snap-in'sdynamic scope pane items (called folders). It is also displays information for the scope items.

When to Use

The IComponentData interface is required for any snap-in component that enumerates items in the master namespace (scope pane). Extension snap-ins that do not extend the namespace (but extend other features like context menus, toolbars, and so on) do not need to implement this interface or the IComponent interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IComponentData Methods | Description
Initialize | Provides an entry point to the console.
CreateComponent | Creates a component that will be associated with this IComponentData.
Notify | Console calls to notify the snap-in of actions taken by a user.
Destroy | Release all references to the console.
QueryDataObject | Returns a data object that can be used to retrieve context information for the cookie.
GetDisplayInfo | Retrieves display information for an item in the scope pane.
CompareObjects | Enables a snap-in to compare two data objects acquired through QueryDataObject. Note that data objects can be acquired from two different instances of IComponentData.


IComponentData::CompareObjects

Enables a snap-in component to compare two data objects acquired through QueryDataObject. Note that the data objects can be acquired from two different instances of IComponentData.

HRESULT CompareObjects(
  LPDATAOBJECT lpDataObjectA,  // pointer to the first data object
  LPDATAOBJECT lpDataObjectB  // pointer to the second data object
);

Parameters

lpDataObjectA
[in] Pointer to the first data object exposing an IDataObject interface that is to be compared.
lpDataObjectB
[in] Pointer to the second data object exposing an IDataObject interface that is to be compared.

Return Values

S_OK
The comparison was successful.
S_FALSE
The comparison was unsuccessful.
E_UNEXPECTED
An unexpected error occurred.

Remarks

The IDataObject interface is documented in the Platform SDK.

See Also

IComponent, IComponentData, IConsole


IComponentData::CreateComponent

Creates a component that will be associated with this IComponentData interface.

HRESULT CreateComponent (
  LPCOMPONENT * ppComponent  // pointer to the new pointer's
                             // location
);

Parameters

ppComponent
[out] Pointer to the location that stores the newly created pointer to IComponent.

Return Values

S_OK
The component was successfully created.
E_UNEXPECTED
An unexpected error occurred.

See Also

IComponent, IComponentData, IConsole


IComponentData::Destroy

Releases all references to the console.

HRESULT Destroy( )

Parameters

This method has no parameters.

Return Values

S_OK
Indicates all the references to the console were successfully released.
E_UNEXPECTED
An unexpected error occurred.

Remarks

The snap-in is in the process of being unloaded. Release all references to the console.

Notes to Callers

Only the console calls this method.

See Also

IComponent, IComponentData, IConsole


IComponentData::GetDisplayInfo

Retrieves display information for a namespace item in the scope pane.

HRESULT GetDisplayInfo(
  SCOPEDATAITEM * pScopeDataItem  // pointer to a scope item struct
);

Parameters

pScopeDataItem
[in, out] Pointer to a SCOPEDATAITEM structure. On input the structure's mask member specifies the type of information required and the lParam member identifies the item of interest.

Return Values

S_OK
Display information was successfully retrieved.
E_UNEXPECTED
An unexpected error occurred.

See Also

IComponent, IComponentData, IConsole


IComponentData::Initialize

Provides an entry point to the console.

HRESULT Initialize(
  LPUNKNOWN pUnknown  // Pointer to console's IUnknown.
);

Parameters

pUnknown
[in] Pointer to the console's IUnknown interface. This interface pointer can be used to call QueryInterface for IConsole and IConsoleNameSpace.

Return Values

S_OK
The component was successfully initialized.
E_UNEXPECTED
An unexpected error occurred.

Remarks

IComponentData::Initialize is called when a snap-in is being created and has items in the scope pane to enumerate. The pointer to IConsole that is passed in is used to make QueryInterface calls to the console for interfaces such as IConsoleNamespace. The snap-in should also call IConsole::QueryScopeImageList to get the image list for the scope pane and add images to be displayed on the scope pane side.

See Also

IComponent, IComponentData, IConsole


IComponentData::Notify

Notifies the snap-in of actions taken by the user.

HRESULT Notify(
  LPDATAOBJECT lpDataObject,  // Pointer to a data object
  MMC_NOTIFY_TYPE event,  // Action taken by a user
  long arg,               // Depends on event
  long param              // Depends on event
);

Parameters

lpDataObject
[in] Pointer to the data object of the currently selected item.
event
[in] Identifies an action taken by a user. IComponentData::Notify can receive the following notifications:
  • MMCN_RENAME
  • MMCN_EXPAND
  • MMCN_DELETE
  • MMCN_PROPERTY_CHANGE.
arg
[in] Depends on the notification type.
param
[in] Depends on the notification type.

Return Values

S_OK
Depends on the notification type.
E_UNEXPECTED
An unexpected error occurred.

Remarks

See individual notifications for detailed information.

See Also

IComponent, IComponentData, IConsole


IComponentData::QueryDataObject

Returns a data object that can be used to retrieve the context information for the specified cookie.

HRESULT QueryDataObject(
  long cookie,             // Unique identifier
  DATA_OBJECT_TYPES type,  // Type of data object
  LPDATAOBJECT * ppDataObject  // Pointer to data object address
);

Parameters

cookie
[in] Specifies the unique identifier for which the data object is required.
type
[in] Specifies the data object as one of the following:
Value | Meaning
CCT_SCOPE = 0x8000 | Data object for the scope pane.
CCT_RESULT = 0x8001 | Data object for the result pane.
CCT_SNAPIN_MANAGER = 0x8002 | Data object for the snap-in manager context.
CCT_UNITIALIZED = 0xFFFF | Data object has an invalid type.

These constants are members of the DATA_OBJECT_TYPES enumeration.

ppDataObject
[out] Pointer to the address of the returned data object.

Return Values

S_OK
The notification was successfully sent.
E_UNEXPECTED
An unexpected error occurred.

Remarks

You can pass these data objects to the same snap-in or to extension snap-ins that require them. Some of the MMC interfaces that may use this data object are IComponent, IComponentData, IContextMenuProvider, IExtendContextMenu, IPropertySheetProvider, and IExtendPropertySheet.

See Also

IComponent, IComponentData, IConsole, IDataObject


IConsole

The IConsole interface enables communication with the console.

When to Implement

You do not implement IConsole. It is implemented by the console's node manager. A pointer to the IConsole interface is passed to the snap-in through IComponent::Initialize and IComponentData::Initialize. Each IComponent and IComponentData get their own private IConsole interface pointers.

When to Use

This interface enables your snap-in component to communicate with the console.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IConsole Methods | Description
SetHeader | Used by instances of IComponent only.Sets the header interface to be used for this IComponent..
SetToolbar | Used by instances of IComponent only. Sets the toolbar interface to be used for this IComponent.
QueryResultView | Queries IConsole for the result view object's IUnknown interface pointer.
QueryScopeImageList | Queries the console-provided scope pane's image list.
QueryResultImageList | Queries the console-provided result pane's image list.
UpdateAllViews | Generates a notification to update views because of content change.
MessageBox | Displays a message box.
QueryConsoleVerb | Query for the IConsoleVerb interface.
SelectScopeItem | Selects the given scope pane item.
GetMainWindow | Returns a handle to the main frame window.
NewWindow | Returns a handle to the main frame window.


IConsole::GetMainWindow

Returns a handle to the main frame window.

HRESULT GetMainWindow(
  HWND * phwnd  // Pointer to the handle of the main frame window.
);

Parameter

phwnd
[out] Address of a variable that receives the window handle.

Return Values

S_OK
The handle was successfully returned.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The parameter is invalid. This may indicate a NULL pointer.

See Also

IConsole


IConsole::MessageBox

Displays a message box.

HRESULT MessageBox(
  LPCWSTR lpszText,  // Pointer to the text to be displayed
  LPCWSTR lpszTitle, // Pointer to the title of the box
  UINT fuStyle,      // Style of the message box
  int * piRetval     // Pointer to the return value
);

Parameter

lpszText
[in] Pointer to a null-terminated string containing the message to be displayed.
lpszTitle
[in] Pointer to a null-terminated string used for the message box title. If this parameter is NULL, the default title "Error" is used.
fuStyle
[in] Specifies a set of bit flags that determine the contents and behavior of the message box. This parameter can be a combination of flags from the following groups of flags taken from the documentation for the Win32 MessageBox function in the Platform SDK, under the uType parameter.

Specify one of the following flags to indicate which buttons appear in the message box:
Flag | Meaning
MB_ABORTRETRYIGNORE | The message box contains three buttons: Abort, Retry, and Ignore.
MB_OK | The message box contains one button: OK. This is the default.
MB_OKCANCEL | The message box contains two buttons: OK and Cancel.
MB_RETRYCANCEL | The message box contains two buttons: Retry and Cancel.
MB_YESNO | The message box contains two buttons: Yes and No.
MB_YESNOCANCEL | The message box contains three push buttons: Yes, No, and Cancel.

Specify one of the following flags to indicate which icon appears in the message box:
Flag | Meaning
MB_ICONEXCLAMATION, MB_ICONWARNING | An exclamation-point icon appears in the message box.
MB_ICONINFORMATION, MB_ICONASTERISK | An icon consisting of an "I" in a circle appears in the message box.
MB_ICONQUESTION | A question-mark icon appears in the message box.
MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND | A stop-sign icon appears in the message box.

Specify one of the following flags to indicate the default button:
Flag | Meaning
MB_DEFBUTTON1 | The first button is the default button unless one of the other flags in this group is specified as the default.
MB_DEFBUTTON2 | The second button is the default button.
MB_DEFBUTTON3 | The third button is the default button.
MB_DEFBUTTON4 | The fourth button is the default button.

Specify one of the following flags to indicate the modality of the dialog box:
Flag | Meaning
MB_APPLMODAL | The User must respond to the message box before continuing work in the current window. However, the user can move to the windows of other applications and work in those windows. The default is MB_APPLMODAL if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.
MB_SYSTEMMODAL | All applications are suspended until the user responds to the message box. System-modal message boxes are used to notify the user of serious, potentially damaging errors that require immediate attention and should be used sparingly.
MB_TASKMODAL | Similar to MB_APPLMODAL, but not useful within a Microsoft Foundation class application. This flag is reserved for a calling application or library that does not have a window handle available.

In addition, you can specify the following flags:
Flag | Meaning
MB_DEFAULT_DESKTOP_ONLY | The desktop currently receiving input must be a default desktop; otherwise, the function fails. A default desktop is one an application runs on after the user has logged on.
MB_HELP | Adds a Help button to the message box. Choosing the Help button or pressing F1 generates a Help event.
MB_RIGHT | The text is right-justified.
MB_RTLREADING | Displays message and caption text using right-to-left reading order on Hebrew and Arabic systems.
MB_SETFOREGROUND | The message box becomes the foreground window. Internally, the operating system calls the Win32 SetForegroundWindow function for the message box.
MB_TOPMOST | The message box is created with the WS_EX_TOPMOST window style.
MB_SERVICE_NOTIFICATION | TBD
MB_SERVICE_NOTIFICATION_NT3x | TBD

piRetval
[out] Pointer to the return value.

Return Values

S_OK
The header was successfully set.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The parameter is invalid. This may indicate a NULL pointer.

See Also

IConsole


IConsole::NewWindow

Creates a new MDI child window at a particular item.

HRESULT NewWindow(
  HSCOPEITEM hScopeItem,    // Scope item for root of new window
  unsigned long lOptions,   // Not currently used
);

Parameters

hScopeItem
[in] The scope item that will form the root of the new window.
lOptions
[in] Not currently used.

Return Values

S_OK
The interface was successfully returned.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The parameter is invalid. This may indicate a NULL pointer.

Remarks

Not implemented in Beta 3.


IConsole::QueryConsoleVerb

Queries for the IConsoleVerb interface.

HRESULT QueryConsoleVerb(
  LPCONSOLEVERB * ppConsoleVerb  // Pointer to IConsoleVerb's
                                 // location
);

Parameter

ppConsoleVerb
[out] Pointer to the address of a variable that receives the IConsoleVerb interface pointer.

Return Values

S_OK
The interface was successfully returned.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The parameter is invalid. This may indicate a NULL pointer.

See Also

IConsole, IConsoleVerb


IConsole::QueryResultImageList

Returns the console-provided result-view image list. This image list should be used only if the snap-in is using the default list view.

HRESULT QueryResultImageList(
  LPIMAGELIST * ppImageList  // Pointer to the image list's location
);

Parameter

ppImageList
[out] Address of a variable that receives the IImageList interface pointer.

Return Values

S_OK
The image list was successfully returned.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The parameter is invalid. This may indicate a NULL pointer.

See Also

IConsole, IImageList


IConsole::QueryResultView

Queries IConsole for the result view object's IUnknown interface pointer.

HRESULT QueryResultView(
  LPUNKNOWN * pUnknown  // Address of the returned pointer.
);

Parameter

pUnknown
[out] Pointer to the location of the IUnknown interface pointer to the result view object.

Return Values

S_OK
The IUnknown pointer was successfully returned.
E_UNEXPECTED
An unexpected error occurred.
E_POINTER
This may indicate a NULL pointer.

Remarks

For example, QueryResultView can be used when the result view is a custom OCX that implements the IDispatch interface. The user should call QueryResultView to get the IUnknown pointer to the OCX. This is necessary because the node manager handles the creation of the OCX.

See Also

IConsole


IConsole::QueryScopeImageList

Queries the console-provided scope pane's image list.

HRESULT QueryScopeImageList(
  LPIMAGELIST * ppImageList  // Address of the returned pointer
);

Parameters

ppImageList
[out] Address of a variable that receives the scope pane's IImageList interface pointer.

Return Values

S_OK
The image list was successfully returned.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The parameter is invalid. This may indicate a NULL pointer.
E_OUTOFMEMORY
The operation could not be completed due to lack of memory.

See Also

IConsole, IImageList


IConsole::SelectScopeItem

Selects the given scope pane item.

HRESULT SelectScopeItem(
  HSCOPEITEM hScopeItem  // Handle to a scope item
);

Parameter

hScopeItem
[in] Handle of the item in the scope pane to be selected.

Return Values

S_OK
The specified scope item was selected.
E_UNEXPECTED
An unexpected error occurred.
E_FAIL
hScopeItem is neither the currently selected node, nor the parent or child of the currently selected node.

Remarks

Use this method to reselect the currently selected node, or select the parent or child of the currently selected node.

You can have a single scope node with several different views available, such as several OCX views and the default list view. When the user selects a different view from a menu, your snap-in receives the command and should then call SelectScopeItem to reselect the node. IComponent::GetResultViewType can then return the selected view type.

See Also

IComponent, IConsole


IConsole::SetHeader

Sets the header interface to be used for this instance of IComponent. You should note that this is used only by instances of IComponent.

HRESULT SetHeader(
  LPHEADERCTRL pHeader  // Pointer to IHeaderCtrl the interface
);

Parameter

pHeader
[in] Pointer to the IHeaderCtrl interface.

Return Values

S_OK
The header was successfully set.
E_UNEXPECTED
An unexpected error occurred.

Remarks

The snap-in must tell the console to release the interface by calling IConsole::SetHeader(NULL). The best time to do this is during a call to IComponent::Destroy.

See Also

IHeaderCtrl, IConsole


IConsole::SetToolbar

Sets the toolbar interface to be used for this instance of IComponent. You should note that this is used only by instances of IComponent.

HRESULT SetToolbar(
  LPTOOLBAR pToolbar  // Pointer to the IToolbar interface
);

Parameter

pToolbar
[in] Pointer to the IToolbar interface.

Return Values

S_OK
The toolbar was successfully set.
E_UNEXPECTED
An unexpected error occurred.

See Also

IConsole, IToolbar


IConsole::UpdateAllViews

Updates all the views whenever this is a content change. This method can be called either by IComponent or IComponentData.

HRESULT UpdateAllViews(
  LPDATAOBJECT lpDataObject,  // Pointer to the data object
  long data,                  // Modified content
  long hint                   // Information about modifications
);

Parameter

lpDataObject
[in] Pointer to a user-supplied data object.
data
[in] User defined.
hint
[in] User defined.

Return Values

S_OK
The notification was successfully sent.
E_UNEXPECTED
An unexpected error occurred.

Remarks

This method sends an MMCN_VIEW_CHANGE notification to all instances of IComponent associated with the snap-in instance calling this method. The lpDataObject, data, and hint parameters will be passed as the lpDataObject, arg, and param for the IComponent::Notify method.

See Also

IConsole, IToolbar


IConsoleNameSpace

The IConsoleNameSpace interface enables snap-in components to enumerate dynamic subcontainers in the scope pane. The particular snap-in determines what qualifies as a subcontainer. For example, a snap-in that features a domain object might enumerate individual groups or organizations within the domain.

When to Implement

You do not implement IConsoleNameSpace. It is implemented by the console's node manager.

When to Use

A snap-in uses IConsoleNameSpace to add or delete items associated with the scope pane.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IConsoleNameSpace Methods |  | Description
InsertItem | Enables the snap-in to Insert a single item into the scope view.
DeleteItem | Enables the snap-in to delete a single item from the scope.
SetItem | Enables the snap-in to set a single scope view item.
GetItem | Enables the snap-in to get a single scope view item.
GetChildItem | Enables the snap-in to get the handle of the first child item.
GetNextItem | Enables the snap-in to get the handle of the next item.
GetParentItem | Enables the snap-in to get the handle of the parent item.


IConsoleNameSpace::DeleteItem

Enables the snap-in to delete a single item from the scope view pane.

HRESULT DeleteItem(
  HSCOPEITEM hItem, // Handle of item
  long fDeleteThis  // Flag specifying deletion of hItem
);

Parameters

hItem
[in] Handle of the item whose children need to be deleted from the scope view.
fDeleteThis
[in] If this parameter is TRUE, the item specified by hItem is also deleted; otherwise, it is not.

Return Values

S_OK
One or more items were successfully deleted.
E_UNEXPECTED
An unexpected error occurred.

See Also

IConsoleNameSpace


IConsoleNameSpace::GetChildItem

Enables the snap-in to get the handle of a child item in the scope view pane.

HRESULT GetChildItem(
  HSCOPEITEM item,          // Handle to parent item
  HSCOPEITEM * pItemChild,  // Pointer to new handle address
  long * plCookie           // Pointer to new cookie address
);

Parameters

item
[in] Handle of a parent item in the scope pane
pItemChild
[out] Pointer to the handle identifying the new child item in the scope pane that has been returned.
plCookie
[out] Pointer to the cookie associated with the new child item that has been returned.

Return Values

S_OK
The child item was successfully retrieved.
E_UNEXPECTED
An unexpected error occurred.

Remarks

If the handle of the child item is not obtained, NULL is returned.

See Also

IConsoleNameSpace


IConsoleNameSpace::GetItem

Enables the snap-in to retrieve some or all of a single scope item's attributes.

HRESULT GetItem(
  LPSCOPEDATAITEM item  // Pointer to a structure with item
                        // information
);

Parameters

item
[in, out] Pointer to a SCOPEDATAITEM structure that specifies the information to retrieve and receives information about the item. When the message is sent, the ID member of the structure identifies the item to retrieve information about and the mask member specifies the attributes to retrieve.

If mask specifies the SDI_STATE value, the nState member contains the item's state information.

Return Values

S_OK
The attributes for the given item were successfully retrieved.
E_UNEXPECTED
An unexpected error occurred.

See Also

IConsoleNameSpace


IConsoleNameSpace::GetNextItem

Enables the snap-in to retrieve the handle of the next item in the scope view.

HRESULT GetNextItem(
  HSCOPEITEM item,         // Handle of scope pane item
  HSCOPEITEM * pItemNext,  // Pointer to the next item address
  long * plCookie          // Pointer to the cookie's address
);

Parameters

item
[in] Handle of an item in the scope pane.
pItemNext
[out] Pointer to the handle of the next item in the scope pane that has been returned.
plCookie
[out] Pointer to the cookie of the next item that has been returned.

Return Values

S_OK
The next item was successfully retrieved.
E_UNEXPECTED
An unexpected error occurred.

Remarks

If the handle of the next item is not obtained, NULL is returned.

See Also

IConsoleNameSpace


IConsoleNameSpace::GetParentItem

Enables the snap-in to retrieve the handle of a parent item in the scope view.

HRESULT GetParentItem(
  HSCOPEITEM item,           // Scope pane item handle
  HSCOPEITEM * pItemParent,  // Pointer to parent handle address
  long * plCookie            // Pointer to cookie's address
);

Parameters

item
[in] Handle of an item in the scope pane.
pItemParent
[out] Pointer to the handle of the parent item returned.
plCookie
[out] Pointer to the cookie associated with the item returned.

Return Values

S_OK
The parent item was successfully retrieved.
E_UNEXPECTED
An unexpected error occurred.

Remarks

If the handle of the parent item is not obtained, NULL is returned.

See Also

IConsoleNameSpace


IConsoleNameSpace::InsertItem

Enables the snap-in to insert a single item into the scope view.

HRESULT InsertItem(
  LPSCOPEDATAITEM item  // Pointer to a structure with item
                        // attributes
);

Parameters

item
[in, out] Pointer to a SCOPEDATAITEM structure that specifies the attributes of the new scope pane item. On return, the ID member of the structure contains the scope-pane-assigned item identifier for the newly inserted item.

Return Values

S_OK
The item was successfully inserted.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The item parameter may be NULL, or the mask member of the SCOPEDATAITEM structure does not contain SDI_STR and SDI_PARAM, or the structure's displayname member is not equal to MMC_CALLBACK.
E_OUTOFMEMORY
The operation could not be completed due to lack of memory.

See Also

IConsoleNameSpace


IConsoleNameSpace::SetItem

Enables the snap-in to set a single scope-view item.

HRESULT SetItem(
  LPSCOPEDATAITEM item  // Pointer to a structure with item
                        // information
);

Parameters

item
[in] Pointer to a SCOPEDATAITEM structure containing information about the item to be set in the scope pane.

Return Values

S_OK
The item was successfully set.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The item parameter may be NULL, or the ID member of the SCOPEDATAITEM structure is NULL.
E_OUTOFMEMORY
The operation could not be completed due to lack of memory.

See Also

IConsoleNameSpace


IConsoleVerb

The IConsoleVerb interface allows snap-ins to enable standard verbs including cut, copy, paste, delete, properties, rename, refresh, and print. Whenever an item is selected, the snap-in can update the state of these verbs.

When to Implement

You do not implement this interface. It is implemented by the Microsoft Management Console's node manager.

When to Use

You use IConsoleVerb whenever your snap-in can be enhanced by offering users the ability to perform the standard actions noted above. By default the standard verbs appear on the menus and toolbars disabled. You have the ability to enable, disable, or hide them based on the currently selected item. You should note that hiding is allowed only for scope item selection changes.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IConsoleVerb Methods | Description
GetVerbState | Gets the state of a verb.
SetVerbState | Sets the state of a verb.
SetDefaultVerb |
GetDefaultVerb |


IConsoleVerb::GetDefaultVerb

Gets the snap-in's default verb.

HRESULT GetDefaultVert(
  MMC_CONSOLE_VERB peCmID,    // Pointer to the default verb
);

Parameters

peCmID
[out] Pointer to where the snap-in's default verb is returned.

Return Values

S_OK
The default verb was returned successfully.

Remarks

The MMC_CONSOLE_VERB enumeration defines the set of default verbs.

See Also

IConsoleVerb::SetDefaultVerb, MMC_CONSOLE_VERB


IConsoleVerb::GetVerbState

Enables a snap-in to obtain a given verb's current button state.

HRESULT GetVerbState(
  MMC_CONSOLE_VERB m_eCmdID,  // Command identifier of the verb
  MMC_BUTTON_STATE nState,  // State of the verb.
  BOOL * pState             // Pointer to information returned.
);

Parameters

m_eCmdID
[in] Specifies the command identifier of the verb. Taken from the MMC_CONSOLE_VERB enumeration, this value can be one of the following:
Value | Meaning
MMC_VERB_CUT | Enables an item that can be selected to be copied to the clipboard and removed. Implemented by the user.
MMC_VERB_COPY | Enables the selected item that can be selected to be copied to the clipboard. Implemented by the user.
MMC_VERB_PASTE | Enables the selected item that have been cut or copied to be pasted into the result pane. Implemented by the user.
MMC_VERB_DELETE | Enables the selected item to be deleted. Implemented by the console. A notification will be sent to the snap-in that owns that item.
MMC_VERB_PROPERTIES | The console asks the snap-in and all snap-in extensions to provide property pages for the currently selected item. Implemented by the console.
MMC_VERB_RENAME | Enables the selected item to be renamed. Implemented by the console.
MMC_VERB_REFRESH | Determines whether the currently selected scope item (folder) can be refreshed. Implemented by the user.
MMC_VERB_PRINT | Determines whether the currently selected item can be printed. Implemented by the user.

nState
[in] Identifies the possible states of the button. Taken from the MMC_BUTTON_STATE enumeration, this value can be one of the following:
Value | Meaning
ENABLED | Enables the menu item so it can be selected and restores it from its grayed state.
HIDDEN | Hides the button in the toolbar or item in the menu.

pState
[out] Pointer to the state information returned. TRUE if the state is enabled or hidden and FALSE if the state is disabled or visible.

Return Values

S_OK
The verb was successfully obtained.
E_FAIL
An error occurred. Do not trust the value in pState.

Remarks

Every time an item is selected, the verb states for all the commands are returned to disabled and visible. It is up to the snap-in developer to update the verb state every time an item is selected.

See Also

IToolbar


IConsoleVerb::SetDefaultVerb

Sets the default action on an object.

HRESULT SetDefaultVert(
  MMC_CONSOLE_VERB eCmID,     // The default verb
);

Parameters

eCmID
The default verb.

Return Values

S_OK.
The verb was successfully set.

Remarks

The MMC_CONSOLE_VERB enumeration defines the set of default verbs.

See Also

IConsoleVerb::GetDefaultVerb, MMC_CONSOLE_VERB

^IConsoleVerb::SetVerbState

[This is preliminary documentation and subject to change.]

Enables a snap-in to set a given verb's button state.

HRESULT SetVerbState(
  MMC_CONSOLE_VERB m_eCmdID,  // Command identifier of the verb.
  MMC_BUTTON_STATE nState,  // State of the menu item
  BOOL bState               // TRUE or FALSE.
);

Parameters

m_eCmdID
[in] Specifies the command identifier of the verb. Values are taken from the MMC_CONSOLE_VERB enumeration and can be one of the following:
Value | Meaning
MMC_VERB_CUT | Enables an item that can be selected to be copied to the clipboard and removed. Implemented by the user.
MMC_VERB_COPY | Enables the selected item that can be selected to be copied to the clipboard. Implemented by the user.
MMC_VERB_PASTE | Enables the selected item that have been cut or copied to be pasted into the result pane. Implemented by the user.
MMC_VERB_DELETE | Enables the selected item to be deleted. Implemented by the console. A notification will be sent to the snap-in that owns that item.
MMC_VERB_PROPERTIES | The console asks the snap-in and all snap-in extensions to provide property pages for the currently selected item. Implemented by the console.
MMC_VERB_RENAME | Enables the selected item to be renamed. Implemented by the console.
MMC_VERB_REFRESH | Determines whether the currently selected scope item (folder) can be refreshed. Implemented by the user.
MMC_VERB_PRINT | Determines whether the currently selected item can be printed. Implemented by the user.

nState
[in] Identifies the possible states of the button. Taken from the MMC_BUTTON_STATE enumeration, this value can be one of the following:
Value | Meaning
ENABLED | Enables the menu item so it can be selected and restores it from its grayed state.
HIDDEN | Hides the button in the toolbar or item in the menu.

bState
[in] This value is TRUE to enable or hide the verb. FALSE to disable or show the selected verb.

Return Values

S_OK
The button's attribute was successfully set.

Remarks

Every time an item is selected, the verb states for all the commands are returned to disabled and visible. It is up to the snap-in writer to update the verb state every time an item is selected.

See Also

IConsoleVerb


IContextMenuCallback

The IContextMenuCallback interface is used to add menu items to a context menu.

When to Implement

You do not implement this interface. It is implemented by the Microsoft Management Console's node manager.

When to Use

There are two situations in which you use IContextMenuCallback. The first is during a call to IExtendContextMenu::AddMenuItems (implemented by the snap-in). Use IContextMenuCallback::AddItem to add items to the context menu for an item you own in the result list view, in the scope pane, or for an item you are extending as a third-party context menu extension. If one of the items you add is selected, you are notified by IExtendContextMenu::Command.

The second situation in which you use this interface is when you create a context menu yourself using IContextMenuProvider. In this case, you call IContextMenuCallback::AddItem after calling IContextMenuProvider::EmptyMenuList and before calling IContextMenuProvider::ShowContextMenu.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IContextMenuCallback Method | Description
AddItem | Adds one item to the context menu.


IContextMenuCallback::AddItem

Adds a single item to a context menu.

HRESULT AddItem(
  CONTEXTMENUITEM * pItem  // Pointer to the identifying structure
);

Parameters

pItem
[in] Pointer to a CONTEXTMENUITEM structure with the item to be added. This parameter may not be NULL.

Return Values

S_OK
The menu item was successfully added.
E_UNEXPECTED
An unexpected error occurred.
E_POINTER
The pItem parameter is NULL.
E_INVALIDARG
One or more of the following conditions occurred:
  • An item already exists with this lCommandID. See CONTEXTMENUITEM.
  • The insertion point identified by the iInsertionPointID member of CONTEXTMENUITEM could not be found.
  • The command ID (if you are adding a menu item) or insertion point ID (if you are adding a submenu or insertion point) identified by the lCommandID member of CONTEXTMENUITEM is invalid or cannot be used at this time. For example, snap-ins acting as context menu extensions cannot insert or reference a primary insertion point. See CONTEXTMENUITEM.
  • fFlags contains MF_OWNERDRAW or MF_BITMAP. See CONTEXTMENUITEM.
  • An extension tried to add an item where either fFlags contains MF_SEPARATOR or fSpecialFlags contains CCM_SPECIAL_SEPARATOR. See CONTEXTMENUITEM.
  • strName is NULL and this is not a separator or insertion point. See CONTEXTMENUITEM.
  • fSpecialFlags contains CCM_SPECIAL_SUBMENU, but fFlags does not contain MF_POPUP.

See Also

CONTEXTMENUITEM, IContextMenuCallback


IContextMenuProvider

The IContextMenuProvider interface implements methods that create new context menus, to add items to those menus, to enable extensions to extend those menus, and to display the resultant context menus.

When to Implement

You do not implement this interface. It is implemented by the Microsoft Management Console's node manager.

When to Use

Use this interface only when you are implementing an OCX that displays context menus independently of those in the scope pane and list view result pane. Although it is possible to use the Win32 API to create context menus, it is generally advisable for snap-in components to use IContextMenuProvider because it provides third-party extensions the opportunity to extend the context menus.

If you are using a general purpose OCX that must be able to display context menus outside of the Microsoft Management Console, you may use the Win32 API. However, those context menus will not be extensible through the MMC context menu extension mechanism.

Methods in Vtable Order

Note that IContextMenuProvider is derived from IContextMenuCallback so you can call the methods of IContextMenuCallback on an instance of IContextMenuProvider.

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IContextMenuCallback Methods | Description
AddItem | Adds one item to the context menu.

IContextMenuProvider Methods | Description
EmptyMenuList | Clears the context menu.
AddPrimaryExtensionItems | Enables one specific snap-in to extend the context menu.
AddThirdPartyExtensionItems | Enables all snap-ins that have registered as third-party context menu extensions for this node type to extend the context menu.
ShowContextMenu | Displays the context menu.


IContextMenuProvider::AddPrimaryExtensionItems

AddPrimaryExtensionItems enables one specific extension to add items to the insertion points defined for this context menu.

HRESULT AddPrimaryExtensionItems(
  LPUNKNOWN piExtension,  // Pointer to an IUnknown interface
  LPDATAOBJECT piDataObject  // Pointer to a data object
);

Parameters

piExtension
[in] Pointer to an IUnknown interface on the object that implements the IExtendContextMenu interface for the primary extension.
piDataObject
[in] Pointer to the IDataObject interface on the object whose context menu is being extended.

Return Values

S_OK
The menu was successfully extended with zero or more menu items.
S_FALSE
The context menu has already been extended.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
At least one parameter is NULL

Other values can be returned, depending on the implementation of IExtendContextMenu::AddMenuItems by the specified snap-in.

See Also

IContextMenuCallback, IContextMenuProvider, IExtendContextMenu


IContextMenuProvider::AddThirdPartyExtensionItems

Enables third-party extensions to add items to specified insertion points in this context menu. The Microsoft Management Console checks its list of snap-ins registered to extend objects of this node type and offers each (if any) the opportunity to extend the context menu by calling IExtendContextMenu::AddMenuItems.

HRESULT AddThirdPartyExtensionItems(
  LPDATAOBJECT piDataObject  // Pointer to a data object
);

Parameters

piDataObject
[in] Pointer to the IDataObject interface on the object whose menu is being extended.

Return Values

S_OK
The menu was successfully extended with zero or more menu items.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The piDataObject parameter is NULL.

See Also

IContextMenuCallback, IContextMenuProvider, IExtendContextMenu


IContextMenuProvider::EmptyMenuList

Clears a context menu.

HRESULT EmptyMenuList( )

This method has no parameters.

Return Values

S_OK
The context menu was cleared.

Remarks

IContextMenuProvider::ShowContextMenu automatically clears the context menu after displaying it. Nevertheless, it is a good practice to call EmptyMenuList before beginning to build a context menu.

See Also

IContextMenuProvider


IContextMenuProvider::ShowContextMenu

Displays a context menu.

HRESULT ShowContextMenu(
  HWND hwndParent,  // Handle of the menu's parent window
  long xPos,        // Horizontal location of the menu
  long yPos,        // Vertical location of the menu
  long * plSelected // Identifier of the selected menu item
);

Parameters

hwndParent
[in] Handle of the parent window in which the context menu will be displayed.
xPos
[in] Specifies the horizontal location of the upper-left corner of the context menu in screen coordinates.
yPos
[in] Specifies the vertical location of the upper-left corner of the context menu in screen coordinates.
plSelected
[out, retval] Specifies the ICommandID value (as passed to IContextMenuCallback::AddItem) of the selected menu item. If this is zero, either none of the context menu items were selected or the selected context menu item was added by an extension. If an extension item was selected, ShowContextMenu notifies the extension by calling IExtendContextMenu::Command.

Return Values

S_OK
The context menu was successfully displayed.
E_UNEXPECTED
An unexpected error occurred.

Remarks

ShowContextMenu automatically clears the context menu after displaying it. Nevertheless, it is a good practice to call IContextMenuProvider::EmptyMenuList before beginning to build a context menu.

See Also

IContextMenuProvider


IControlbar

The IControlbar interface provides a way to create toolbars and other controls.

When to Implement

You do not implement this interface. It is implemented by the Microsoft Management Console's node manager.

When to Use

You use IControlbar whenever toolbars or other controls will enhance the user interface of your snap-in component.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IControlbar Methods | Description
Create | Creates and returns control
Attach | Associates the control with control bar
Detach | Removes control from control bar


IControlbar::Attach

Allows the snap-in to associate a control with a control bar.

HRESULT Attach(
  MMC_CONTROL_TYPE nType,  // Specifies the type of control
  LPUNKNOWN lpUnknown  // Pointer to an IUnknown interface.
);

Parameters

nType
[in] Specifies the type of control to be associated with the control bar. Currently, it can only be the following:
Value | Meaning
TOOLBAR | The control to be associated with the control bar is a toolbar.

lpUnknown
[in] Pointer to the IUnknown interface on the control object to be inserted.

Return Values

S_OK
The toolbar or combo box was successfully created.

Remarks

In connection with the nType parameter, COMBOBOXBAR appears in mmc.idl but is not implemented at this time.

See Also

IToolbar


IControlbar::Create

Creates and returns the control requested by the snap-in.

HRESULT Create(
  MMC_CONTROL_TYPE nType,  // Type of control to be created
  LPEXTENDCONTROLBAR pExtendControlbar,
                         // Pointer to IExtendControlBar
  LPUNKNOWN * ppUnknown  // Address at which to return the object.
);

Parameters

nType
[in] Specifies the type of control to be associated. Currently, it can only be the following:
Value | Meaning
TOOLBAR | The control to be associated with the control bar is a toolbar.

pExtendControlbar
[in] Pointer to the IExtendControlbar interface on the control to be created on the control bar.
ppUnknown
[out] Pointer to the address of the IUnknown interface of the control that was created.

Return Values

S_OK
The control was successfully created and returned.

Remarks

In connection with the nType parameter, COMBOBOXBAR is included in mmc.idl but is not implemented at this time.

See Also

IToolbar


IControlbar::Detach

Breaks the association between a control and the control bar. This command removes or detaches the toolbar from the control bar on which it is displayed.

HRESULT Detach(
  LPUNKNOWN lpUnknown  // Pointer to IUnknown.
);

Parameters

lpUnknown
[in] Pointer to the IUnknown interface on the control object representing the control being removed.

Return Values

S_OK
The control was successfully detached from the control bar.

See Also

IToolbar


IExtendContextMenu

The IExtendContextMenu interface enables an extension to add items to an existing context menu. This is how extensions add menu items to the context menus for the objects they insert into the scope pane or list view result pane. This is also how third-party context menu extensions add items to the context menus for items with their registered node types.

When a user right-clicks items that both belong to a snap-in and that are in the scope pane or list view result pane, MMC generates a default context menu, then offers the snap-in that added the item the opportunity to extend the context menu as a primary extension. Then MMC offers all registered and enabled extensions the opportunity to add additional menu items.

When to Implement

You implement this interface as part of your in-process server DLL when the capability to extend a snap-in component's context menus is expected to be necessary.

When to Use

This interface is only called by the Microsoft Management Console.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IExtendContextMenu Methods | Description
AddMenuItems | Enables the extension to add menu items.
Command | Indicates an extension item on a context menu was selected.


IExtendContextMenu::AddMenuItems

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.

See Also

IContextMenuCallback, IDataObject, IExtendContextMenu


IExtendContextMenu::Command

If one of the items you added to the context menu by IExtendContextMenu::AddMenuItems is subsequently selected, MMC calls Command with the command ID you specified and another pointer to the same IDataObject interface.

HRESULT Command(
  long lCommandID,           // Menu item command identifier
  LPDATAOBJECT piDataObject  // Data object pointer
);

Parameters

lCommandID
[in] Specifies the command identifier of the menu item.
piDataObject
[in] Pointer to the IDataObject interface on the object whose context menu was displayed.

Return Values

S_OK
The context menu item was successfully selected.
E_UNEXPECTED
An unexpected error occurred.

See Also

IContextMenuCallback, IDataObject, IExtendContextMenu


IExtendControlbar

The IExtendControlbar interface enables an extension to add control bars to the console. This provides a way to add toolbars or other user interface enhancements to improve the functionality and appearance of your snap-in.

When to Implement

You implement IExtendControlbar as part of your OLE in-process server DLL when you want to add control bars.

When to Use

This interface is only called by the Microsoft Management Console.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IExtendControlbar Methods | Description
SetControlbar | Adds a control bar
ControlbarNotify | Notifications resulting from user actions


IExtendControlbar::SetControlbar

Allows an extension snap-in to set a control bar.

HRESULT SetControlbar(
  LPCONTROLBAR pControlbar  // Pointer to the IControlbar interface
);

Parameters

pControlbar
[in] Pointer to the IControlbar interface on the control bar object to be set.

Return Values

S_OK
The control bar was successfully set.

See Also

IToolbar


IExtendControlbar::ControlbarNotify

Specifies notification sent to the snap-in from the console as a result of user action.

HRESULT ControlbarNotify(
  MMC_NOTIFY_TYPE event,  // User action
  long arg,               // Depends on the event parameter
  long param              // Depends on the event parameter
);

Parameters

event
[in] Specifies one of the following:
Value | Meaning
MMCN_BTN_CLICK | A button on the toolbar was clicked.
MMCN_SELECT | An item was selected and the user should update the toolbar options.

arg
[in] Depends on the event parameter. For more information, see MMC Notifications.
param
[in] Depends on the event parameter. For more information, see MMC Notifications.

Return Values

S_OK
The buttons were successfully added.

See Also

IToolbar


IExtendPropertySheet

The IExtendPropertySheet interface enables a snap-in component to add pages to the property sheet of an item.

When to Implement

You implement this interface in your in-process server DLL to add property pages for a snap-in component. QueryInterface is called on the primary snap-in object and the console then calls IExtendPropertySheet::QueryPagesFor. If the snap-in responds with S_OK, the console calls IExtendPropertySheet::CreatePropertyPages which gives the snap-in an opportunity to add its pages. Finally, the console creates the sheet to display the pages. If the snap-in returns S_FALSE, no property sheet is created for the object.

Note that each property sheet is created in its own thread. If any COM interface pointer is passed from the IComponent to the property page, this pointer must be marshaled. For more information, see Processes and Threads in the Microsoft Platform SDK and the Apartment Model discussion in the COM specification. The size of the property page is determined by the primary snap-in. If you are extending a property sheet for an object that does not belong to your snap-in, the dialog templates you use should conform to the dimensions established by the primary snap-in.

When to Use

This interface can be used to add information about the properties of an object whenever you consider it appropriate. It may also be useful to know that property pages can also be implemented using either the Win32 API or a class library such as the Microsoft Foundation Class Library.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IExtendPropertySheet Methods | Description
CreatePropertyPages | Adds pages to a property sheet.
QueryPagesFor | Determines whether object needs pages.


IExtendPropertySheet::CreatePropertyPages

Adds pages to a property sheet.

HRESULT CreatePropertyPages(
  LPPROPERTYSHEETCALLBACK lpProvider,
                              // Pointer to the callback interface
  long handle,                // Handle for routing notification
  LPDATAOBJECT lpIDataObject  // Pointer to the data object
);

Parameters

lpProvider
[in] Pointer to the IPropertySheetCallback interface.
handle
[in] Specifies the handle used to route the MMCN_PROPERTY_CHANGE notification message to the appropriate IComponent or IComponentData.
lpIDataObject
[in] Pointer to the IDataObject interface on the object that contains context information about the node.

Return Value

S_OK
The property sheet pages were successfully added.
S_FALSE
There were no pages added.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
One or more parameters are invalid.

See Also

IDataObject, IExtendPropertySheet, IPropertySheetCallback


IExtendPropertySheet::QueryPagesFor

Determines whether the object requires pages.

HRESULT QueryPagesFor(
  LPDATAOBJECT lpDataObject  // Pointer to the data object
);

Parameters

lpDataObject
[in] Pointer to the IDataObject interface on the object that contains context information about the node.

Return Value

S_OK
Properties exist for this cookie.
E_UNEXPECTED
An unexpected error occurred.
E_INVALID
The parameter is invalid.

Remarks

The console calls this method to determine whether the Properties menu item should be added to the context menu.

See Also

IDataObject, IExtendPropertySheet, IPropertySheetCallback


IHeaderCtrl

The IHeaderCtrl interface enables the manipulation of columns and indicates the kind of information that is to be presented in the result view pane of the console. This interface can be queried from the IUnknown passed into IComponent::Initialize during the component's creation.

When to Implement

You do not implement IHeaderCtrl. It is implemented by the console's node manager.

When to Use

You use IHeaderCtrl in the console-provided default result view pane of the console to add or remove columns, or to change column titles or widths.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IHeaderCtrl Methods | Description
InsertColumn | Adds a column to a default result view.
DeleteColumn | Removes a column.
SetColumnText | Sets text in a specified column.
GetColumnText | Retrieves the text from a specified column.
SetColumnWidth | Sets the width of a specified column.
GetColumnWidth | Retrieves the width of a specified column.


IHeaderCtrl::DeleteColumn

Removes a column from the header of the result view.

HRESULT DeleteColumn(
  int nCol  // Index of the column to be removed
);

Parameter

nCol
[in] Zero-based index that identifies the column to be removed.

Return Values

S_OK
The column was successfully deleted.
E_UNEXPECTED
The current result view is not the console-provided default view.
E_INVALIDARG
The nCol parameter is not a valid column index.

Remarks

If a column is removed, all columns with indexes greater than the one removed are adjusted down by one.

Notes to Callers

DeleteColumn returns E_FAIL when an item has already been inserted into the result view.

See Also

IHeaderCtrl


IHeaderCtrl::GetColumnText

Retrieves text from a specified column.

HRESULT GetColumnText(
  int nCol,         // Zero-based index of the column
  LPOLESTR * pText  // Pointer to the text
);

Parameters

nCol
[in] Zero-based index that identifies the column from which the text is to be retrieved.
pText
[out] Pointer to the address of the text to be retrieved. This pointer must not be NULL. The user is responsible for calling CoTaskMemFree on the returned text. This function is documented in the Platform SDK.
E_POINTER
The pText parameter is NULL.

Return Values

S_OK
The column text was successfully retrieved.
E_UNEXPECTED
The current result view is not the console-provided default view
E_INVALIDARG
The nCol parameter is not a valid column index.
E_POINTER
The pText parameter is NULL.

Remarks

GetColumnText allocates the string for the result and stores its pointer at the location specified by pText. The caller must be sure to free the memory using CoTaskMemFree.


IHeaderCtrl::GetColumnWidth

Retrieves the width of the column in pixels.

HRESULT GetColumnWidth(
  int nCol,     // Zero-based index of the column
  int * pWidth  // Pointer to the width
);

Parameters

nCol
[in] Zero-based index of the column from which the width is to be retrieved.
pWidth
[out] Pointer to width of the column. This parameter must not be NULL.

Return Values

S_OK
The column width was successfully retrieved.
E_UNEXPECTED
The current result view is not the console-provided default view.
E_INVALIDARG
The nCol parameter is not a valid column index.
E_POINTER
The pWidth parameter is NULL.
Notes to Callers

GetColumnWidth can be called successfully even if there are items already in the list.

See Also

IHeaderCtrl


IHeaderCtrl::InsertColumn

Adds a column to a default result pane.

HRESULT InsertColumn(
  int nCol,       // Zero-based index of the column
  LPCWSTR title,  // Specifies the name of the column
  int nFormat,    // Specifies justification of text
  int nWidth      // Specifies the column's initial width
);

Parameters

nCol
[in] Zero-based index of the column being inserted.
title
[in] Specifies the string representing the title of the column being inserted.
nFormat
[in] Specifies the position of text within the column. For column zero nFormat must be LVCFMT_LEFT. This value must be one of the following:
Value | Meaning
LVCFMT_LEFT | Text is left-aligned.
LVCFMT_CENTER | Text is center-aligned.
LVCFMT_RIGHT | Text is right-aligned.

nWidth
[in] Specifies the width of the column in pixels. If you pass the value MMCLV_AUTO, the node manager automatically determines the width of the column based on its title string.

Return Values

S_OK
The column was successfully inserted.
E_UNEXPECTED
The current result view is not the console-provided default view.
E_INVALIDARG
The title parameter is NULL or empty (""), or nCol or nFormat is invalid.
Notes to Callers

Calls to InsertColumn fail if any items have already been inserted into the result view.

See Also

IHeaderCtrl


IHeaderCtrl::SetColumnText

Sets the text of the title in a specific column.

HRESULT SetColumnText(
  int nCol,      // Zero-based index of the column
  LPCWSTR title  // Title of the column
);

Parameters

nCol
[in] Zero-based index specifying the location of the column.
title
[in] Pointer to the string representing the title of the column being inserted.

Return Values

S_OK
The title text was successfully set.
E_UNEXPECTED
The current result view is not the console-provided default view.
E_INVALIDARG
The title parameter is NULL or empty (""), or nCol is invalid.

See Also

IHeaderCtrl


IHeaderCtrl::SetColumnWidth

Sets the width of a specific column in pixels.

HRESULT SetColumnWidth(
  int nCol,  // Zero-based index of the column
  int nWidth // Width of the column
);

Parameters

nCol
[in] Zero-based index specifying the location of the column relative to other columns in the result pane.
nWidth
[in] Specifies the width of the column in pixels. If MMCLV_AUTO is given, the width of the column is determined based on the width of the text in the column's title.

Return Values

S_OK
The width of the column was successfully set.
E_UNEXPECTED
The current result view is not the console-provided default view.
E_INVALIDARG
The nCol parameter is invalid.

See Also

IHeaderCtrl


IImageList

The IImageList interface enables the user to insert images to be used as icons for items in the result or scope pane of the console. When an image is inserted, an index is passed in and associated with the image. Any time the image is to be used, the user can refer to it by the index that he or she assigned.

Note that because the image list is shared among many components, the user-specified index is a "virtual" index that gets mapped internally to the actual index.

When to Implement

You do not implement the IImageList interface. It is implemented by the Microsoft Management Console.

When to Use

You can use the IImageList interface whenever a snap-in component will benefit from being able to insert images that can be used as icons.

The scope pane and the result pane (if it is the default list view) each have an image list. The snap-in should add the specified images of items to display before the images are added to either of the panes. The images for the scope pane are added only once, while the images for the result pane are added every time the snap-in gets the SHOW(TRUE) notification message.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IImageList Methods | Description
ImageListSetIcon | Sets an icon in the image list.
ImageListSetStrip | Sets a strip of icons in the image list.


IImageList::ImageListSetIcon

Enables a user to set an icon in the image list or to create one if it is not there.

HRESULT ImageListSetIcon(
  long * pIcon,  // Win32 HICON handle of the icon
  long nLoc      // Specifies the assigned index
);

Parameters

pIcon
[in] Specifies the Win32 HICON handle of the icon to set. The type must be cast as a pointer to a long.
nLoc
[in] Specifies the index assigned to the entry. This is a virtual index that is internally mapped to the actual index.

Return Values

S_OK
The icon was successfully added or replaced.
E_INVALIDARG
The pIcon parameter is NULL or the nloc parameter is negative.
E_UNEXPECTED
An unexpected error occurred.

Remarks

If the index specified by nLoc has been used before, ImageListSetIcon replaces the icon stored at nLoc. If it has not been previously used, a new entry in the image list will be added. The icon being inserted must have both the 32x32 and 16x16 pixel sizes defined.

See Also

IImageList


IImageList::ImageListSetStrip

Enables a user to add a strip of icons to the image list, starting at the location identified by nLoc using a pair of bitmaps (large and small icons).

HRESULT ImageListSetStrip(
  long * pBMapSm, // Point to a handle
  long * pBMapLg, // Pointer to a handle
  long nStartLoc, // Index of the first image in the strip
  COLORREF cMask  // Color of the icon mask
);

Parameters

pBMapSm
[in] Pointer to the Win32 HBITMAP handle of the small (16x16) icon image strip.
pBMapLg
[in] Pointer to the Win32 HBITMAP handle of the large (32x32) icon image strip.
nStartLoc
[in] Specifies the index assigned to the first image in the strip. This is a virtual index that is internally mapped to the actual index.
cMask
[in] Specifies the color used to generate a mask.

Return Values

S_OK
The strip of icons was successfully added to or replaced.
E_INVALIDARG
The pBMapSm or pBMLg parameter is NULL or references bitmaps of an invalid size or nStartLoc is negative.
E_UNEXPECTED
An unexpected error occurred.

Remarks

The small and large bitmaps must be given and the number of icons in each strip must be equal. The small bitmap must be 16 pixels high and 16*n wide. The large bitmap must be 32 pixels high and 32*n pixels wide.

Each pixel of the color used to generate a mask in the specified bitmap is changed to black and the corresponding bit in the mask is set to one.

See Also

IImageList


IMenuButton

The IMenuButton interface enables the user to add and manage menu buttons for a snap-in. MMC provides one menu bar per view and when a snap-in has focus you can add one or more menu buttons for it to this bar. These buttons are always added by appending them to the buttons already in the menu bar.

When to Implement

You do not implement the IMenuButton interface. It is implemented by the Microsoft Management Console.

When to Use

You should use the IMenuButton interface whenever your snap-in requires or can benefit from having one or more additional menu buttons in the MMC menu bar for the particular view. To access the IMenuButton interface your snap-in must implement the IExtendControlbar interface. When MMC invokes your IExtendControlbar::SetControlbar it passes an IControlbar interface. You can create an IMenuButton interface by calling the IControlbar::Create method.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IMenuButton | Description
AddButton | Adds a button to the menu bar.
SetButton | Sets the attributes of a menu bar button.
SetButtonState | Sets the state of a menu bar button.


IMenuButton::AddButton

Enables a user to add a button to the MMC menu bar for a particular view.

HRESULT AddButton(
  int idCommand,  // Specifies a unique user-supplied value
  LPOLESTR lpButtonText
                  // Pointer to the text value for the button
  LPOLESTR lpTooltipText
                  // Pointer to the text value for the button's
                  // tooltip
);

Parameters

idCommand
[in] Specifies a user-supplied value that uniquely identifies the button to be added to the menu bar.
lpButtonText
[in] Pointer to the text value (a null-terminated string) to be displayed on the button.
lpTooltipText
[in] Pointer to the text value (a null-terminated string) to be displayed when the user places the mouse pointer on the button.

Return Values

S_OK
The button was successfully added.
E_UNEXPECTED
An unexpected error occurred.

Remarks

Buttons added to the MMC menu bar for a particular view are always appended to the buttons already present. The initial state of a menu button is hidden and disabled.

When the snap-in loses focus, these buttons are automatically removed from the menu bar. As a result, they must be added each time the snap-in gets focus.

This method can be called by primary or extension snap-ins.

See Also

IMenuButton


IMenuButton::SetButton

Enables a user to set the text attributes of a button in the menu bar that is being changed.

HRESULT SetButton(
  int idCommand,  // Specifies a unique user-supplied value
  LPOLESTR lpButtonText
                  // Pointer to the text value for the button
  LPOLESTR lpTooltipText
                  // Pointer to text for the button's tooltip
);

Parameters

idCommand
[in] Specifies a user-supplied value that uniquely identifies the button to be added to the menu bar.
lpButtonText
[in] Pointer to the text value (a null-terminated string) to be displayed on the button.
lpTooltipText
[in] Pointer to the text value (a null-terminated string) to be displayed when the user places the mouse pointer on the button.

Return Values

S_OK
The attribute or attributes were successfully set.
E_INVALIDARG
lpButtonText or lpTootipText is NULL.
E_UNEXPECTED
An unexpected error occurred.

See Also

IMenuButton


IMenuButton::SetButtonState

Enables a user to change the state of a menu button.

HRESULT SetButtonState(
  int idCommand,           // Specifies the command identifier
  MMC_BUTTON_STATE nState  // Specifies the state of the button
  BOOL bState              // Specifies TRUE or FALSE
);

Parameters

idCommand
[in] Specifies a user-supplied value that uniquely identifies the menu button in which the state is being changed.
nState
[in] Specifies the state of the button. This value can be one of the following values taken from the MMC_BUTTON_STATE enumeration:
Value | Meaning
ENABLED | The button accepts user input. A button that does not have this state does not accept user input and is grayed.
HIDDEN | The button is not visible and cannot receive user input.
BUTTONPRESSED | The button is being pressed.

bState
[in] Specifies whether the state is to be turned on or off. Set to TRUE to turn the button's state ON; otherwise, set it to FALSE.

Return Values

S_OK
The state of the button was successfully set.
E_UNEXPECTED
An unexpected error occurred.

See Also

IMenuButton


IPropertySheetCallback

IPropertySheetCallback is a COM-based interface used by a snap-in to add its property pages to a property sheet.

When to Implement

You do not implement this interface. It is implemented by the node manager in Microsoft Management Console.

When to Use

A pointer to this interface is passed in when IExtendPropertySheet::CreatePropertyPages is called so the snap-in can add or remove property pages.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IPropertySheetCallback Methods | Description
AddPage | The snap-in can add a page to a property sheet.
RemovePage | The snap-in can remove a page from a property sheet.


IPropertySheetCallback::AddPage

Allows a snap-in to add a page to a property sheet.

HRESULT AddPage(
  HPROPSHEETPAGE hPage  // Handle of the page to be added
);

Parameter

hPage
[in] Specifies the handle of the page to be added.

Return Values

S_OK
The page was successfully added.
S_FALSE
There are too many pages on this sheet. The maximum is 255.
E_UNEXPECTED
An unexpected error occurred.
E_POINTER
The parameter is NULL.

Remarks

Pages are added to the sheet in the order they are presented. The primary snap-ins pages are always added first.

Notes to Callers

The hPage parameter is a handle to a PROPSHEETPAGE-structure created by the Win32 function CreatePropertySheetPage, which is documented in the Platform SDK.

See Also

IPropertySheetCallback


IPropertySheetCallback::RemovePage

Enables a snap-in to remove a page from a property sheet.

HRESULT RemovePage(
  HPROPSHEETPAGE hPage  // Handle of the page to be removed
);

Parameter

hPage
[in] Handle of the page to be removed.

Return Values

S_OK
The page was successfully removed or the list is empty.
S_FALSE
The page was not found in the list.
E_UNEXPECTED
An unexpected error occurred.
E_POINTER
The parameter is NULL.

Remarks

RemovePage can be used only for pages that the snap-in itself has added.

See Also

IPropertySheetCallback


IPropertySheetProvider

The IPropertySheetProvider interface implements Win32 property sheets as COM objects. A property sheet object has the code necessary to handle modeless operation and to determine which other snap-ins are extending this node type. The size of the property sheet is determined by the primary snap-in and extensions are forced to accept that size.

When to Implement

You do not implement this interface. It is implemented by the node manager in Microsoft Management Console.

When to Use

You use IPropertySheetProvider whenever you are building a snap-in that has its own result view; that is, a result view other than the default (list view) result pane. IPropertySheetProvider is also be used when a snap-in adds a feature that has a property sheet as the user interface but identifies it as something else.

If the user implements his or her own OCX, IPropertySheetProvider can be used to put the property sheet and automatically get all the features it provides, such as the ability to add extension pages.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IPropertySheetProvider Methods | Description
CreatePropertySheet | Creates a property sheet frame.
FindPropertySheet | Determines whether a property sheet exists.
AddPrimaryPages | Collects property pages from the primary snap-in.
AddExtensionPages | Collects pages from one or more extension snap-ins.
Show | Displays a specific property sheet frame.


IPropertySheetProvider::AddExtensionPages

Collects the pages from the extension snap-ins.

HRESULT AddExtensionPages( );

AddExtensionPages has no parameters.

Return Values

S_OK
The pages were successfully collected.
E_UNEXPECTED
An unexpected error occurred.

Remarks

The primary snap-in must have added at least one page before extensions can add pages.

See Also

IPropertySheetProvider


IPropertySheetProvider::AddPrimaryPages

Collects the pages from the primary snap-in.

HRESULT AddPrimaryPages(
  LPUNKNOWN lpUnknown, // Pointer to an IComponent or IComponentData
  BOOL bCreateHandle,  // Specifies a handle to a notification
  HWND hNotifyWindow,  // Specifies the main HWND
  BOOL bScopePane      // TRUE for scope pane, FALSE for result pane
);

Parameters

lpUnknown
Pointer to the IUnknown interface of either an IComponent or IComponentData. This value can be NULL.
bCreateHandle
Specifies a console-provided handle to a notification that is used to route the notification message to the appropriate IComponent or IComponentData interface during calls to MMCPropertyChangeNotify and MMCFreeNotifyHandle.

If this parameter is TRUE, the provider creates a notify handle. lpUnknown must not be NULL.

hNotifyWindow
Specifies the main HWND that receives the notification of a change from the property page that called MMCPropertyChangeNotify. This value can be NULL.
bScopePane
Set to TRUE if the item is in the scope pane. Set to FALSE if it is in the result pane.

Return Values

S_OK
The property page was successfully created.

Remarks

If a snap-in uses the provider directly, you can call IPropertySheetCallback::AddPage to add the primary pages and call AddPrimaryPages (NULL, FALSE, NULL, [TRUE or FALSE]) so the provider will add these pages to the property sheet.

The snap-in might not add any pages during this method call. If this is the case, extension pages should not be added.

See Also

IDataObject, IPropertySheetProvider


IPropertySheetProvider::CreatePropertySheet

Creates a property sheet frame.

HRESULT CreatePropertySheet(
  LPCWSTR title,             // Pointer to the property page title
  boolean type,              // Specifies property sheet or wizard
  long cookie,               // Identifies the managed object's sheet
  LPDATAOBJECT pIDataObject  // Pointer to a data object
  DWORD dwOptions,           // Not currently used
);

Parameters

title
[in] Pointer to a zero-terminated string that contains the title of the property page.
type
[in] TRUE creates a property sheet and FALSE creates a wizard
cookie
[in] Identifies the managed object's property sheet.
pDataObject
[in] Pointer to the IDataObject interface on the data object for the cookie.
dwOptions
Not currently used.
Option | Meaning
MMC_PSO_NOAPPLYNOW | Remove Apply Now button.
MMC_PSO_HASHELP | Add a Help button.
MMC_PSO_NEWWIZARDTYPE | Use Wizard 97 style.

Return Values

S_OK
The property page was successfully created.
E_POINTER
The title and pIDataObject parameters must not be NULL.

Remarks

This method creates an object that collects all the information needed to create the property sheet. If the CreatePropertySheet call is successful and subsequent errors occur, you must call IPropertySheetProvider::Show (-1, 0) to free objects.

See Also

IDataObject, IPropertySheetProvider, IPropertySheetProvider::Show


IPropertySheetProvider::FindPropertySheet

Determines whether a specific property sheet exists.

HRESULT FindPropertySheet(
  long cookie,  // Managed object's cookie
  LPCOMPONENT lpComponent,
                // Pointer to the component that owns the cookie
  LPDATAOBJECT lpDataObject
                // Pointer to the data object for the cookie
);

Parameter

cookie
[in] Identifies the managed object that is about to have a property sheet displayed.
lpComponent
[in] Pointer to the IComponent interface on the object that owns the cookie. NULL if the object selected is a folder (on the scope or result panes), and the snapin's IComponent if it is a result pane leaf item.
lpDataObject
[in] Pointer to the IDataObject interface on the data object for the cookie.

Return Values

S_OK
The property sheet was successfully located and was brought to the foreground.
S_FALSE
A property sheet with this cookie was not found.

Remarks

Items in the scope pane are owned by the console so there is no need to interact with the IComponentData interface. The snap-in must implement IComponent::CompareObjects or IComponentData::CompareObjects to compare the data object for this cookie with all other cookies for existing property sheets.

See Also

IPropertySheetProvider


IPropertySheetProvider::Show

Displays a property sheet frame parented to the HWND passed in to this function.

HRESULT Show(
  long window,  // Handle of the parent window
  int page      // Page that is shown
);

Parameters

window
[in] Specifies the handle of the parent window.
page
[in] Specifies which page on the property sheet is shown. It is zero indexed.

Return Values

S_OK
The property sheet was successfully displayed.
E_UNEXPECTED
There were no pages to display. IPropertySheetProvider::CreatePropertySheet had not been called.
E_FAIL
The sheet could not be created because window was non-NULL and invalid or the thread could not be created.
E_INVALIDARG
The page was less than zero.

See Also

IPropertySheetProvider


IResultData

The IResultData interface enables a user to add, remove, find, and modify items associated with the result view pane. It also enables the manipulation of the view style of the result view pane.

Even though the IResultData interface was designed to give the impression that the result view pane would be used by only one component, components should be aware that the result view pane can, in fact, be shared by several components. All item manipulations are performed through the use of an item ID that is assigned when the item is inserted. This ID is guaranteed to be both static and unique for the life of the item. After an item is deleted, the ID is freed and may be used by other new items in the list. You should never keep an item ID around after its associated item has been deleted.

When to Implement

You do not implement the IResultData interface. It is implemented by the node manager in Microsoft Management Console.

When to Use

You can use IResultData to allow the user of your snap-in component to change items in the result view pane or when the user decides to change the result pane's view style.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IResultData Methods | Description
InsertItem | The snap-in can insert a single item.
DeleteItem | The snap-in can delete one item.
FindItemByLParam | The snap-in can find an item or subitem based on a user-inserted value.
DeleteAllRsltItems | The snap-in can delete all items.
SetItem | The snap-in can set a single item.
GetItem | The snap-in can retrieve a single item.
GetNextItem | Returns the lParam of the first item.
ModifyItemState | The snap-in can modify the item's state.
ModifyViewStyle | The snap-in can set the result view style.
SetViewMode | The snap-in can set the result view mode.
GetViewMode | The snap-in can retrieve the result view mode.
UpdateItem | Redraws an item in the result pane after it has been changed.
Sort | Sorts all result pane items.
SetDescBarText | Sets result view description bar text.
SetItemCount |


IResultData::DeleteAllRsltItems

Enables the snap-in to remove all user-inserted items and subitems from the result view pane.

HRESULT DeleteAllRsltItems( )

Parameters

This method has no parameters.

Remarks

This method provides the same functionality for both result view panes and virtual lists.

Return Values

S_OK
The items were successfully removed.
E_UNEXPECTED
An unexpected error occurred.

See Also

IResultData


IResultData::DeleteItem

Enables the snap-in to delete a single item in the result view pane.

HRESULT DeleteItem(
  HRESULTITEM itemID,  // Identifier of the item to be deleted
  INT nCol             // Column of a subitem to be deleted
);

Parameters

itemID
[in] Specifies the unique ID of the item to be deleted.
When applied to virtual lists, pass the item index instead of the itemID.
nCol
[in] Not used. Must be zero.

Return Values

S_OK
The item was successfully deleted.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
At least one of the parameters is not valid.

Remarks

DeleteItem removes an item identified by itemID and nCol. If nCol does not equal zero, the subitem identified by itemID and nCol will be cleared of all information. If nCol is equal to zero, the item identified by itemID and all of its subitems will be deleted and removed from the list. If a subitem is deleted, itemID remains a valid identifier. However, if the main item is deleted, itemID can be reassigned by the console to any newly inserted items and should be destroyed or released.

See Also

IResultData


IResultData::FindItemByLParam

Enables the snap-in to find an item or subitem based on its user-inserted lParam value.

HRESULT FindItemByLParam(
  LPARAM lParam,         // Generic 32-bit value
  HRESULTITEM * pItemID  // Pointer to an item identifier
);

Parameters

lParam
[in] Generic 32-bit value in which information can be stored.
pItemID
[out] Pointer to an item identifier to hold the results of the search for the lParam value.

Return Values

S_OK
The item or subitem was successfully found.
S_FALSE
The item was not found.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The pItemID parameter is NULL.

Remarks

FindItemByLParam searches for an item based on its lParam. The unique identifier (cookie) of the first item in the list with a matching lParam is returned in pItemID. If no item is found, the search returns S_FALSE.

This method does not support virtual lists.

See Also

IResultData


IResultData::GetItem

Enables a user to retrieve the parameters of a single item.

HRESULT GetItem(
  LPRESULTDATAITEM item  // Pointer to a RESULTDATAITEM structure
);

Parameter

item
[in, out] Pointer to a RESULTDATAITEM structure containing information about the item whose parameters are being retrieved.
When applied to virtual lists, use the item index instead of the item ID, and set item ID = 0. Can only get select and focus states.

Return Values

S_OK
The item was successfully retrieved.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The pItem parameter is NULL.

Remarks

The itemID member of the RESULTDATAITEM structure pointed to by the item parameter should be set to refer to the item or subitem on which information is being returned. The nCol member should be set to zero because it is the only column in which anything can be obtained or set. In addition, the data members for each of the flags set in the mask member of the item structure if this method call succeeds.

If itemID is zero, the nIndex member can be used.

See Also

IResultData, IResultData::SetItem


IResultData::GetNextItem

Gets the next item in the result view

HRESULT GetNextItem(
  LPRESULTDATAITEM item  // Pointer to a structure with information
                         // about next item
);

Parameters

item
[in, out] Pointer to a RESULTDATAITEM structure containing information about the item to be obtained. Item should have been a structure previously used in a call to GetItem.
When applied to virtual lists, test only for select and focus states. Only returns an item index, not an lParam.

Return Values

S_OK
The item was successfully obtained.
E_UNEXPECTED
An unexpected error occurred.
E_OUTOFMEMORY
The operation could not be completed due to lack of memory.

See Also

IResultData


IResultData::GetViewMode

Enables the snap-in to retrieve a view mode for the result view pane.

HRESULT GetViewMode(
  long * lViewMode  // Pointer to the current view mode
);

Parameters

lViewMode
[out] Pointer to the view mode to be retrieved. It can be one of the following:
Value | Meaning
LVS_ICON | Items are displayed as title strings under their large (32x32) icon representations. Subitems and headers are not displayed.
LVS_REPORT | Items are displayed as title strings to the right of their small (16x16) icon representations. Items are tabulated under the header in the zero position of the zero-based index on the left side of the result view pane. Subsequent headers are produced from left to right and corresponding subitems are placed beneath each. To enter the report mode, you must have already called IConsole::SetHeader.
LVS_SMALLICON | Items are displayed as title strings under their small (16x16) icon representations. Subitems and headers are not displayed.
LVS_LIST | Items are displayed as title strings to the right of their small (16x16) icon representations. Subitems and headers are not displayed.

This parameter must not be NULL.

Return Values

S_OK
The view mode was successfully retrieved.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The IViewMode parameter is NULL.

Remarks

This method provides the same functionality for both result view panes and virtual lists.

See Also

IResultData, IResultData::SetViewMode


IResultData::InsertItem

Enables the snap-in to add a new single item to the result pane view.

HRESULT InsertItem(
  LPRESULTDATAITEM item  // Pointer to a RESULTDATAITEM structure
);

Parameters

item
[in, out] Pointer to a RESULTDATAITEM structure containing information about the item to be added.

Return Values

S_OK
The item was successfully inserted.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The pItem parameter is NULL.

Remarks

The mask and all appropriate associated fields in the RESULTDATAITEM structure should be filled out. Subitems cannot be inserted but can be set; therefore, the nCol member of the item structure must be zero.

After the item is inserted, a unique identifier (an item ID) is assigned to it and returned through the itemID member of the item structure. If this identifier is not stored, it can be looked up using IResultData::FindItemByLParam.

The str member of RESULTDATAITEM must be set to MMC_CALLBACK.

This method does not support virtual lists.

See Also

IResultData


IResultData::ModifyItemState

Allows the snap-in to modify the state of an item.

HRESULT ModifyItemState(
  int nIndex,          // index of the item to be modified
  HRESULTITEM itemID,  // item identifier
  UINT uAdd,           // listview-item state flags
  UINT uRemove         // listview-item state flags
);

Parameters

nIndex
[in] Specifies the index of the item whose state is to be modified. This parameter is used only when the itemID parameter is zero.
When applied to virtual lists, you must use nIndex.
itemID
[in] Unique identifier of the item whose state is to be modified.
When applied to virtual lists, set itemID = 0.
uAdd
[in] Specifies which Win32 list-view state flags can be set. This value can be any valid combination of the following:
When applied to virtual lists, only focus and select states can be modified.
Value | Meaning
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has focus and on the system colors used for selection.

uRemove
[in] Specifies the list-view item state flags that can be removed. This value can be any valid combination of theWin32 LVIS_* flags shown for the uAdd parameter shown above.

Return Values

S_OK
The item was successfully set.
S_FALSE
The item was not found.
E_UNEXPECTED
An unexpected error occurred.

See Also

IResultData


IResultData::ModifyViewStyle

Enables the snap-in set the result pane's view style.

HRESULT ModifyViewStyle(
  MMC_RESULT_VIEW_STYLE add,  // Styles to be added
  MMC_RESULT_VIEW_STYLE remove  // Styles to be removed
);

Parameters

add
[in] Specifies the view style (or styles) to be set in the result view pane. This value can be a valid combination of the following:
Value | Meaning
MMC_SINGLESEL | Allows only one item at a time to be selected. By default, multiple items can be selected.
MMC_SHOWSELALWAYS | Always show the selection, if any, even if the control does not have the focus.
MMC_NOSORTHEADER | Specifies that column headers do not work like buttons. This style is useful if clicking on a column header in report view does not carry out an action, such as sorting.

These values are from the MMC_RESULT_VIEW_STYLE enumeration and correspond to the Win32 LVS_* flags of the same names.

remove
[in] Specifies the view style (or styles) to be removed from the result view pane. This value can be a valid combination of the flags shown for the add parameter shown above. As noted there, these values are from the MMC_RESULT_VIEW_STYLE enumeration and correspond to the Win32 LVS_* flags of the same names.

Return Values

S_OK
The view style was successfully set.
S_FALSE
The view style was not set.
E_UNEXPECTED
An unexpected error occurred.

Remarks

This method provides the same functionality for both result view panes and virtual lists.

See Also

IResultData


IResultData::SetDescBarText

Sets the description bar text for the result view pane.

HRESULT SetDescBarText(
  LPOLESTR DescText  // Description bar text
);

Parameters

[in] DescText
Pointer to a zero-terminated string containing text to be displayed in the description bar.

Return Values

S_OK
The item was successfully set.
E_UNEXPECTED
An unexpected error occurred.

Remarks

This method provides the same functionality for both result view panes and virtual lists.

See Also

IResultData


IResultData::SetItem

Enables the snap-in to set a single item in the result pane.

HRESULT SetItem(
  LPRESULTDATAITEM item  // Pointer to a RESULTDATAITEM structure
);

Parameters

[in] item
Pointer to a RESULTDATAITEM structure containing information about the item to be changed.

Return Values

S_OK
The item was successfully set.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The pItem parameter is NULL

Remarks

The itemID member of the item's structure should be set to refer to the item or subitem to be changed in the list. The mask and all appropriate associated fields in the RESULTDATAITEM structure should be filled out with the preferred changes. The nCol member should be set to zero because it is the only column in which anything can be set or obtained. The str member of RESULTDATAITEM should always be set to MMC_CALLBACK.

This method does not support virtual lists.

See Also

IResultData::GetItem


IResultData::SetItemCount

Sets the number of items in a virtual list.

HRESULT SetItemCount(
  int nItemCount   // Number of items in the list
  DWORD dwOptions  // Option flags
);

Parameters

nItemCount
[in] Number of items that the control will ultimately contain
dwOptions
[in] Combination of the following flags:
Flag | Meaning
MMCLV_UPDATE_NOINVALIDATEALL | Only repaint if visible items are affected.
MMCLV_UPDATE_NOSCROLL | Do not adjust the scroll bar on changed item count.

Return Values

S_OK
The item was successfully set.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The pItem parameter is NULL

Remarks

SetItemCount supports virtual lists.

Prepares a list view control for adding a large number of items.

By calling this function before adding a large number of items, you enable a list view control to reallocate its internal data structures only once rather than every time you add an item.

See Also

IResultOwnerData


IResultData::SetViewMode

Enables the user to set the style in which the result view pane displays its items.

HRESULT SetViewMode(
  long lViewMode  // The view mode to be set
);

Parameters

lViewMode
[in] Specifies the view mode to be set in the result pane. It can be one of the following values:
Value | Meaning
LVS_ICON | Items are displayed as title strings under their large (32x32) icon representations. Subitems and headers are not displayed.
LVS_REPORT | Items are displayed as title strings to the right of their small (16x16) icon representations. Items are tabulated under the header in the zero position of the zero-based index on the left side of the result view pane. Subsequent headers are produced from left to right and corresponding subitems are placed beneath each. To enter the report mode, you must have already called IConsole::SetHeader.
LVS_SMALLICON | Items are displayed as title strings under their small (16x16) icon representations. Subitems and headers are not displayed.
LVS_LIST | Items are displayed as title strings to the right of their small (16x16) icon representations. Subitems and headers are not displayed.

This parameter must not be NULL.

Return Values

S_OK
The view mode was successfully set.
E_UNEXPECTED
An unexpected error occurred.
E_INVALIDARG
The IViewMode parameter is NULL.

Remarks

This method provides the same functionality for both result view panes and virtual lists.

See Also

IResultData, IResultData::GetViewMode


IResultData::Sort

Sorts all items in the result pane.

HRESULT Sort(
  int nColumn          // Index of column header clicked
  DWORD dwSortOptions  // Sort options
  long lUserParam      // User-provided information
);

Parameters

nColumn
[in] Index of the column header clicked.
dwSortOptions
[in] Currently there is only one option, RSI_DESCENDING, which indicates that the sort should be in descending order
lUserParam
[in] Specifies information determined by the user. This parameter can contain a variety of entries including sort order, context information, and so on.

Return Values

S_OK
The sort was successfully performed.
E_UNEXPECTED
An unexpected error occurred.

Remarks

By default, the sort is in ascending order unless RSI_DESCENDING is specified.

When applied to virtual lists, IResultData::Sort calls IResultOwnerData::SortItems instead of IResultDataCompare::Compare.

See Also

IResultData, IResultDataCompare::Compare, IResultOwnerData::SortItems


IResultData::UpdateItem

Causes a specified item in the result pane to be redrawn.

HRESULT UpdateItem(
  HRESULTITEM itemID  // Unique identifier of an item in the result
                      // pane
);

Parameters

[in] itemID
Specifies the unique identifier of the item in the result pane to be redrawn.
When applied to virtual lists, pass the item index instead of the itemID.

Return Values

S_OK
The item was successfully redrawn.
E_UNEXPECTED
An unexpected error occurred.

Remarks

UpdateItem would typically be used to update a displayed item after changes are made to it by the user.

See Also

IResultData


IResultDataCompare

The IResultDataCompare interface that enables your snap-in component to compare items that are displayed in a sorted order in the result pane.

When to Implement

You implement IResultDataCompare in your snap-in when the built-in sorting is not sufficient.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IResultResultDataCompare Methods | Description
Compare | Compares two cookies.


IResultDataCompare::Compare

Provides a way for a snap-in component to compare cookies for the purpose of sorting.

HRESULT Compare(
  long lUserParam,  // User-provided information
  long cookieA,     // Unique identifier of first object
  long cookieB,     // Unique identifier of second object
  int * pnResult    // Column being sorted
);

Parameters

lUserParam
[in] Specifies user-provided information that is passed into IResultData::Sort. The console does not interpret this parameter.
CookieA
[in] The unique identifier of the first object to be compared as part of the sorting operation.
CookieB
[in] The unique identifier of the second object to be compared as part of the sorting operation.
pnResult

[in,out] As an in parameter, the argument contains the column that is being sorted. As an out parameter, the value of the argument should be -1, 0, or 1.

Return Values

S_OK
The comparison was successful.

Remarks

Compare provides a mechanism for determining the sort order of objects appearing in the result pane. The built-in sort provided by the console only uses the C runtime's string-compare function to compare the data. If this interface is implemented, then it is used for all comparisons.

The comparison should be based on ascending sort order. If the user toggles the standard result view header, the console will compliment the compare results and this will result in descending order sort.

See Also

IResultData::Sort


IResultOwnerData

IResultOwnerData supports the use of virtual lists, which is a List View control that has the LVS_OWNERDATA style set. The methods of this interface are applicable only to virtual lists. This is an optional interface and snap-ins may implement it for enhanced virtual list performance.

Virtual lists support large numbers of list items, up to 100,000,000. This is possible because the virtual list control does not provide the storage. All storage requirements are provided by the owner of the items. When the control needs information about an item, it sends a LVN_GETDISPINFO notification to the owner of the item parameters.

Because of the lack of storage, a List View control in virtual mode does not support all of the messages that it supports in normal mode.

Result View Selection
To select a virtual list view, IComponent::GetResultViewType sets a flag in the ViewOptions parameter. Setting the MMC_VIEW_OPTIONS_OWNERDATALIST flag and returning a value of S_FALSE makes the result pane a virtual list.

Controlling a Virtual List
Result pane lists are controlled through the IResultData interface. When a virtual list is selected, only a subset of the interface methods can be used. Of these, some have restrictions and or different interpretations of calling parameters when applied to virtual lists.

The following table summarizes the changes to IResultData methods:

Method | Support | Modification
InsertItem (LPRESULTDATAITEM item) Not supported | None |
DeleteItem (ITEM itemID, int nCol) Modified - Pass item index rather than itemID | Modified | Pass item index instead of itemID
FindItemByLParam (LPARAM lParam, ITEM *pItemID) | None |
DeleteAllRsltItems () | Same |
SetItem (LPRESULTDATAITEM item) | None |
GetItem (LPRESULTDATAITEM item) | Modified | Must use item index and set iItemID = 0. Can only get select, focus states
GetNextItem (LPRESULTDATAITEM item) | Modified | Can only test for select and focus state. Only returns item index, not lParam
ModifyItemState (int nIndex, ITEM itemID, UINT uAdd, UINT uRemove) | Modified | Must use nIndex and set iItemID = 0. Only focus and select states can be modified
ModifyViewStyle (MMC_RESULT_VIEW_STYLE add, MMC_RESULT_VIEW_STYLE remove) | Same |
SetViewMode (long lViewMode) | Same |
GetViewMode (long* LviewMode) | Same |
UpdateItem (ITEM itemID) | Modified | Pass item index rather than itemID
Sort (long lUserParam) | Modified | Calls IResultOwnerData::SortItems instead of IResultDataCompare::Compare
SetDescBarText (LPOLESTR DescText) | Same |

IResultData::SetItemCount sets the number of items in a virtual list.

Supporting the Virtual List
A virtual list calls IComponent::GetDisplayInfo to get the information needed to display an item in the result pane. When called for a virtual list, the itemID and lParam fields of the RESULTDATAITEM structure will be zero. The snap-in must use the nIndex field (item index) to identify the item for which data is being requested.

The virtual list calls IComponent::QueryDataObject to get a data object for a particular result item. When called for a virtual list, no itemID will be available, so the cookie parameter will be the item index.

Note that IResultDataCompare cannot be used with virtual lists because it does not support item sorting.

When to Implement

This interface is implemented by the snap-in in order to support virtual lists.

When to Use

TBD

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IResultOwnerData Methods | Description
IResultOwnerData::FindItem | Finds result items matching the specified string.
IResultOwnerData::CacheHint | Pre-collects range information allowing for possible optimizations.
IResultOwnerData::SortItems |

See Also

IResultData, IResultData::SetItemCount, IComponent::GetDisplayInfo, IComponent::QueryDataObject, IComponent::GetResultViewType, RESULTDATAITEM


IResultOwnerData::FindItem

Finds the result item that matches the specified string.

HRESULT FindItem(
  LPRESULTFINDINFO pFindinfo,   // Pointer to RESULTFINDITEM structure
  int pnFoundIndex,             // Pointer to returned index
);

Parameters

pFindInfo
[in] Pointer to the RESULTFINDITEM structure.
pnFoundIndex
[out] Pointer to the returned index of found the item, -1 if no items are found.

Return Values

S_OK
The item was found.
S_FALSE
The item was not found.

Remarks

Supports keyboard navigation through the virtual list. FindItem requests the callee to find the next result item whose display name matches the search string and return its index.

See Also

RESULTFINDINFO


IResultOwnerData::CacheHint

Called when a virtual list is about to request display information for a range of items, allowing the snap-in to collect the information ahead of time in cases where an optimization can be made.

HRESULT CacheHint(
  int nStartIndex,     // Index to first item
  int nEndIndex,       // Index to last item
);

Parameters

nStartIndex
[in] Index of the first item to be requested.
nEndIndex
[in] Index of the last item to be requested.

Return Values

S_OK
The item was found.

Remarks

Note that there is no guarantee that all the items will be requested or that other items will not be.

See Also

TBD


IResultOwnerData::SortItems

Specifies the parameters the snap-in should use to sort the items.

HRESULT SortItems(
  int nColumn,            // Index of column header clicked
  DWORD dwSortOptions,    // Sort options
  long lUserParam,        // User parameter
);

Parameters

nColumn
[in] Index of the column header clicked.
dwSortOptions
[in] The sort defaults to ascending order unless RSI_DESCENDING is specified, which indicates the sort should be in descending order.
lUserParam
[in] A user parameter passed in an IResultData::Sort call, NULL if user initiated sort.

Return Values

S_OK
The sort was completed successfully. MMC will redraw the list on receiving an S_OK.
S_FALSE
The sort was not completed.

Remarks

Because the snap-in maintains all the item data storage for a virtual list, the list does not support sorting. Call this function when the user clicks the header item of a virtual list or the snap-in calls IResultData::Sort.

See Also

IResultData::Sort


ISnapinAbout

The ISnapinAbout interface enables the console to get copyright and version information from the snap-in. The console also uses this interface to obtain images for the static folder from the snap-in.

When to Implement

You implement this interface any time you want to include in your snap-in information that is typically found in an About property page. Default static folder images and icons are used for display if the interface is not implemented. In addition, a separate coclass should be provided for better efficiency.

When to Use

This interface is used by the snap-in manager in Microsoft Management Console.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

ISnapinAbout Methods | Description
GetSnapinDescription | To obtain snap-in description box text.
GetProvider | To obtain the name of the snap-in provider.
GetSnapinVersion | To obtain the version number of the snap-in.
GetSnapinImage | To obtain the main icon for the About box.
GetStaticFolderImage | To obtain static folder images for both panes, scope and result.


ISnapinAbout::GetSnapinDescription

Enables the console to obtain the text for the snap-in's description box.

HRESULT GetSnapinDescription(
  LPOLESTR * lpDescription  // Pointer to the description text.
);

Parameters

lpDescription
[out] Pointer to the text for the description box on an About property page.

Return Values

S_OK
The text was successfully obtained.

Remarks

Memory for out parameters must be allocated using CoTaskMemAlloc. This function is documented in the Platform SDK.

See Also

ISnapinAbout


ISnapinAbout::GetProvider

Enables the console to obtain the snap-in provider's name.

HRESULT GetProvider(
  LPOLESTR * lpName  // Pointer to the provider's name
);

Parameters

lpName
[out] Pointer to the text making up the snap-in provider's name.

Return Values

S_OK
The name was successfully obtained.

Remarks

Memory for out parameters must be allocated using CoTaskMemAlloc. This function is documented in the Platform SDK.

See Also

ISnapinAbout


ISnapinAbout::GetSnapinVersion

Enables the console to obtain the snap-in's version number.

HRESULT GetSnapinVersion(
  LPOLESTR* lpVersion  // Pointer to the version number.
);

Parameters

lpVersion
[out] Pointer to the text making up the snap-in's version number.

Return Values

S_OK
The version number was successfully obtained.

Remarks

Memory for out parameters must be allocated using CoTaskMemAlloc. This function is documented in the Platform SDK.

See Also

ISnapinAbout


ISnapinAbout::GetSnapinImage

Enables the console to obtain the snap-in's main icon to be used in the About box.

HRESULT GetSnapinImage(
  HICON * hAppIcon  // Pointer to the application's main icon
);

Parameters

hAppIcon
[out] Pointer to the handle of the main icon of the snap-in that is to be used in the About property page.

Return Values

S_OK
The handle to the icon was successfully obtained.

Remarks

Memory for out parameters must be allocated using CoTaskMemAlloc. This function is documented in the Platform SDK.

See Also

ISnapinAbout


ISnapinAbout::GetStaticFolderImage

Allows the console to obtain the static folder images for the scope and result panes.

HRESULT GetStaticFolderImage(
  HBITMAP * hSmallImage,  // Pointer to a handle to a small icon.
  HBITMAP * hSmallImageOpen,  // Pointer to a handle to open folder
                              // icon.
  HBITMAP * hLargeImage,  // Pointer to a handle to a large icon.
  COLORREF * cMask        // Color used to generate a mask.
);

Parameter

hSmallImage
[out] Pointer to the handle of a small icon (16x16n pixels) in either the scope or result view pane.
hSmallImageOpen
[out] Pointer to the handle of a small open-folder icon (16x16n pixels).
hLargImage
[out] Pointer to the handle of a large icon (32x32n pixels).
cMask
[out] Pointer to a COLORREF structure that specifies the color used to generate a mask. This structure is documented in the Platform SDK.

Return Values

S_OK
The icon was successfully obtained.

See Also

ISnapinAbout


IToolbar

The IToolbar interface is used to create new toolbars, to add items to them, to extend them and to display the resultant toolbars. Each toolbar is created on its own band within the control bar.

When to Implement
You do not implement this interface. It is implemented by the node manager in Microsoft Management Console.
When to Use

You use IToolbar whenever your snap-in will be enhanced by the presence of toolbars.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IToolbar Methods | Description
AddBitmap | Adds an image to the toolbar
AddButtons | Adds an array of buttons to the toolbar
InsertButton | Adds a single button to the toolbar
DeleteButton | Removes a button
GetButtonState | Gets an attribute of a button
SetButtonState | Sets an attribute of a button


IToolbar::AddBitmap

Allows a snap-in to add an image to the toolbar.

HRESULT AddBitmap(
  int nImages,     // Index of bitmaps images
  HBITMAP hbmp,    // Handle to the bitmap
  int cxSize,      // Height of the bitmap
  int cySize,      // Width of the bitmap
  COLORREF crMask  // Specifies color to generate a mask
);

Parameters

nImages
[in] Index of images available. Specifies the number of images in the bitmap being passed in hbmp.
hbmp
[in] Handle of the bitmap to be added to the toolbar.
cxSize
[in] Height of the bitmap to be added, in pixels. (In beta 1 we only support a cxSize of 16).
cySize
[in] Width of the bitmap to be added, in pixels. (In beta 1 we only support a cySize of 16).
crMask
[in] Color used to generate a mask to overlay the images on the toolbar buttons.

Return Values

S_OK
The toolbar was added successfully.

See Also

IToolbar


IToolbar::AddButtons

Enables a snap-in to add an array of buttons to the toolbar.

HRESULT AddButtons(
  int nButtons,          // Number of buttons
  LPMMCBUTTON lpButtons  // Pointer to an MMCBUTTON structure
);

Parameters

nButtons
[in] Number of buttons in the array.
lpButtons
[in] Pointer to the MMCBUTTON structure containing information necessary to create a button on the toolbar.

Return Values

S_OK
The buttons were successfully added.

See Also

IToolbar


IToolbar::DeleteButton

Enables a snap-in to remove a specific toolbar button.

HRESULT DeleteButton(
  int nIndex  // Position of button to be removed
);

Parameters

nIndex
[in] Index of the button to be removed from the toolbar.

Return Values

S_OK
The button was successfully removed.
E_UNEXPECTED
An unexpected error occurred.

See Also

IToolbar


IToolbar::GetButtonState

Enables a snap-in to obtain an attribute of a button.

HRESULT GetButtonState(
  int idCommand,            // Command identifier of the button
  MMC_BUTTON_STATE nState,  // Structure of button attributes
  BOOL * pState             // Pointer to information returned.
);

Parameters

idCommand
[in] Command identifier of the toolbar button.
nState
[in] Identifies the possible states of the button. Can be one of the following:
Value | Meaning
ENABLED | The button accepts user input. A button that does not have this state does not accept user input and is grayed.
CHECKED | The button has the CHECKED style and is being pressed.
HIDDEN | The button is not visible and cannot receive user input.
INDETERMINATE | The button is grayed.
BUTTONPRESSED | The button is being pressed.

pState
[out] Pointer to the state information returned.

Return Values

S_OK
The button's attributes were successfully obtained.

See Also

IToolbar


IToolbar::InsertButton

Enables a snap-in to add a single button to the toolbar.

HRESULT InsertButton(
  int nIndex,  // Specifies the button's position.
  LPMMCBUTTON lpButton
               // Pointer to the structure defining the button
);

Parameter

nIndex
[in] Position at which the button will be inserted.
lpButton
[in]Pointer to the MMCBUTTON structure that defines the button to be inserted.

Return Values

S_OK
The button was successfully added to the toolbar.

See Also

IToolbar


IToolbar::SetButtonState

Enables a snap-in to set an attribute of a button.

HRESULT SetButtonState(
  int idCommand,            // Command identifier
  MMC_BUTTON_STATE nState,  // State of the button
  BOOL bState               // Sets the button state
);

Parameters

idCommand
[in] Unique value that the user has associated with a button using the InsertButton or AddButtons method using the MMCBUTTON structure.
nState
[in] Specifies the state of the button you want to set. Can be one of the following:
Value | Meaning
ENABLED | The button accepts user input. A button that does not have this state does not accept user input and is grayed.
CHECKED | The button has the CHECKED style and is being pressed.
HIDDEN | The button is not visible and cannot receive user input.
INDETERMINATE | The button is grayed.
BUTTONPRESSED | The button is being pressed.

bState
[in] Specifies whether the state identified in nState is set to TRUE or FALSE. TRUE sets the button state to the state identified by nState and FALSE unsets the state (if already set).

Return Values

S_OK
The button's attribute was successfully set.

See Also

IToolbar


IQuickFilter

Not currently implemented.


MMC Exported Functions

The following functions are available for building MMC snap-in components.

MMCFreeNotifyHandle

MMCPropertyChangeNotify


MMCFreeNotifyHandle

Must be called by a snap-in when the property sheet is destroyed.

STDAPI MMCFreeNotifyHandle(
  long lNotifyHandle  // Handle to a notification
);

Parameters

INotifyHandle
[in] Specifies a handle provided by the console during a IExtendPropertySheet::CreatePropertyPages call.

Return Values

S_OK
The handle was successfully freed.
For more about OLE error codes, see the COM and ActiveX Object Services documentation in the Platform SDK.

Remarks

MMCFreeNotifyHandle should be called one time only.

See Also

IComponent, IExtendPropertySheet::CreatePropertyPages, MMCPropertyChangeNotify


MMCPropertyChangeNotify

MMCPropertyChangeNotify enables a snap-in property sheet to notify its IComponent or IComponentData interface that an item's properties have changed.

Property sheets run in a different thread than their IComponent and IComponentData server; therefore, if the param is a COM interface pointer, it needs to be marshaled. Making this function call notifies each IComponent or the one IComponentData synchronously.

STDAPI MMCPropertyChangeNotify(
  long INotifyHandle,  // Handle to a notification
  long param           // Unique identifier
);

Parameters

INotifyHandle
[in] Specifies the handle used to route the notification message to the appropriate IComponent or IComponentData.
param
[in] User defined and can be used freely.

Return Values

S_OK
Notification was sent.

For more about COM error codes, see the COM and ActiveX Object Services documentation in the Platform SDK.

Remarks

A call to MMCPropertyChangeNotify causes an MMCN_PROPERTY_CHANGE notification to be sent to the snap-in.

The value in param that is passed into MMCPropertyChangeNotify is, in turn, forwarded to the snap-in as the param argument to MMCN_PROPERTY_CHANGE.

See Also

IComponent, IExtendPropertySheet, MMCFreeNotifyHandle


MMCPropPageCallback

Sets the correct module state during page creation.

STDAPI MMCPropertyPageCallback
  void * vpsp,  // Pointer to PROPSHEET structure
);

Parameters

vpsp
Pointer to the Windows PROPSHEETPAGE structure. Note that by default, MFC installs its own callback in the pfnCallback member of the structure.

Return Values

S_OK
The module state was successfully set.

Remarks

For each page derived from CPropertyPage, call this function with a pointer to the page's callback, following these guidelines:

  • All pages for this sheet must use the same callback pointer.
  • If you replace MFC's callback with your own, your callback must call MFC's callback.
  • You must call this function with each CPropertyPage derived class.

MFC must have correct module state set from exported functions or COM interfaces. This includes calls made from the operating system to the module. For exported functions or COM interfaces this is done with an AFX_MANAGE_STATE (AfxGetStaticModuleState). For the operating system call, MFC does this automatically. Since the property sheet is not an MFC CPropertySheet, the operating system call, due to the callback, is in the wrong module state. MFC will make changes in the future to use the module state contained in the CCmdTarget class, but until then, you hook the window create and make sure the module state is correctly set during the page creation, which is what the MMCPropPageCallback does. Once this is done, the only AFX_MANAGE_STATE calls that need to be made are those exposed by COM interfaces (IExtendPropertySheet::CreatePropertyPages). To determine whether the application has the correct module state, look at CWinApp and note the name.

See Also

PROPSHEETPAGE


Console Structures

The following structures are available for building MMC snap-in components.

CONTEXTMENUITEM

MENUBUTTONDATA

MMCBUTTON

PROPSHEETPAGE

RESULTDATAITEM

RESULTFINDINFO

SCOPEDATAITEM


CONTEXTMENUITEM

The CONTEXTMENUITEM structure is passed to IContextMenuCallback::AddItem or IContextMenuProvider::AddItem to define a new menu item, submenu, or insertion point. The context menu is built from the root down, with each new item going to the end of the submenu or insertion point where it is inserted.

typedef struct _CONTEXTMENUITEM
{
    LPWSTR    strName;
    LPWSTR    strStatusBarText;
    LONG      lCommandID;
    LONG      lInsertionPointID;
    LONG      fFlags;
    LONG      fSpecialFlags;
} CONTEXTMENUITEM;
typedef CONTEXTMENUITEM* LPCONTEXTMENUITEM;

Members

strName
Pointer to a zero-terminated string containing the name of the menu item or of the submenu. This member may not be NULL except for a separator or insertion point.
strStatusBarText
Pointer to a zero-terminated string containing the text that will be displayed in the status bar when this item is highlighted. This member may be NULL.
lCommandID
Specifies the command identifier for menu items.

If this menu item is added by IExtendContextMenu::AddMenuItems and then selected, this is the command ID that will be passed back to IExtendContextMenu::Command.

If this menu item is added by IContextMenuProvider and then selected, this is the command ID that will be passed back to pISelected by IContextMenuProvider::ShowContextMenu.

If this is an insertion point (CCM_SPECIAL_INSERTION_POINT is set in fSpecialFlags) or a submenu (MF_POPUP is set in fFlags), you can use lCommandID in subsequent calls as lInsertionPoint (see the following table). Read the following discussion carefully because specific bits in the new insertion point ID must be on and others must be off.

Some bits in the command ID require special handling for items that are not insertion points or submenus.
Value Meaning
CCM_COMMANDID_MASK_
RESERVED = 0xFFFF0000 		Items other than insertion points and submenus may not be added with these bits set.

Some bits in the insertion point ID require special handling for items that are insertion points (fSpecialFlags and CCM_SPECIAL_INSERTION_POINT) or submenus (fFlags and MF_POPUP).
Value Meaning
CCM_INSERTIONPOINTID_
MASK_SPECIAL = 0xFFFF0000 		Special behavior. Snap-ins may use the other bits as they see fit.
CCM_INSERTIONPOINTID_
MASK_SHARED = 0x80000000 		These insertion points and submenus are shared between the creator of the context menu, the primary extension, and the third-party extension. Any of these entities adding items to a shared insertion point or submenu add them to the same insertion point or submenu.

If this bit is not set, IContextMenuProvider and each extension may use the same ID and each refers to a different insertion point or submenu.

Only IContextMenuProvider may create insertion points or submenus with this bit set, unless CCM_INSERTIONPOINTID_MASK_CREATE_PRIMARY is also set in the insertion point ID. If it is, only the primary extension may create them.
CCM_INSERTIONPOINTID_
MASK_CREATE_PRIMARY = 0x40000000 		Only the system may add insertion points or submenus for which CCM_INSERTIONPOINTID_MASK_SHARED is set and this bit is not set. Only the primary extension may add insertion points or submenus for which both bits are set. This prevents insertion point ID conflicts between insertion points and submenus created by IContextMenuProvider and those created by the primary extension.
CCM_INSERTIONPOINTID_
MASK_ADD_PRIMARY = 0x20000000 		If CCM_INSERTIONPOINT_SHARED is set and this bit is not set, the primary extension may not add to this insertion point or submenu.
CCM_INSERTIONPOINTID_
MASK_ADD_3RDPARTY = 0x10000000 		If CCM_INSERTIONPOINT_SHARED is set and this bit is not set, the third-party extensions may not add to this insertion point or submenu.
CCM_INSERTIONPOINTID_
MASK_RESERVED = 0x0FFF0000 		Insertion points or submenus may not be added with any of these bits set.

lInsertionPointID
Specifies where in the context menu the new item should be added. Extensions are limited in where they can place menu items. The following are the insertion points created by Microsoft Management Console in the default context menus for items in the scope pane and list view result pane:
Value | Meaning
0 (zero) | An IInsertionPointID of zero refers to the root menu for this context menu. Zero may be used interchangeably with CCM_INSERTIONPOINTID_ROOT_MENU. Note that only IContextMenuProvider is permitted to add items directly to the root menu. Extensions may only add items to insertion points and submenus added to the root menu by IContextMenuProvider or by Microsoft Management Console.
CCM_INSERTIONPOINTID_
PRIMARY_TOP = 0xA0000000 		The primary extension may use this insertion point to add items to the top of the main context menu.
CCM_INSERTIONPOINTID_
PRIMARY_NEW = 0xA0000001 		The primary extension may use this insertion point to add items to the top of the Create New submenu. The Create New submenu is only present for context menus in the scope pane and not for context menus in the result pane.
CCM_INSERTIONPOINTID_
PRIMARY_TASK = 0xA0000002 		The primary extension may use this insertion point to add items to the top of the Task submenu.
CCM_INSERTIONPOINTID_
PRIMARY_VIEW 		If the user clicks the View dropdown menu in the toolbar, this insertion point will be present but the New and Task insertion points will be absent.
CCM_INSERTIONPOINTID_
3RDPARTY_NEW = 0x90000001 		Third-party extensions may use this insertion point to add items to the bottom of the Create New submenu. The Create New submenu is only present for context menus in the scope pane and not for context menus in the result pane.
CCM_INSERTIONPOINTID_
3RDPARTY_TASK = 0x90000002 		Third-party extensions may use this insertion point to add items to the bottom of the Task submenu.
CCM_INSERTIONPOINTID_
ROOT_MENU = 0x80000000 		IContextMenuProvider may use this insertion point to add items to the root menu.

Neither primary extensions nor third-party extensions may add items to the root menu except through insertion points added by IContextMenuProvider.

fFlags
Specifies one or more of the following style flags:
Value | Meaning
MF_POPUP | Specifies that this is a submenu within the context menu. Menu items, insertion points, and further submenus may be added to this submenu using its lCommandID as their lInsertionPointID.
MF_BITMAP
MF_OWNERDRAW 		These flags are not permitted and will result in IContextMenuCallback::AddItem returning E_INVALIDARG.
MF_SEPARATOR Draws a horizontal dividing line.

Only IContextMenuProvider is allowed to add menu items with MF_SEPARATOR set.

The following flags all operate the same as in the Win32 API:
Value | Meaning
MF_CHECKED | Places a check mark next to the menu item.
MF_DISABLED | Disables the menu item so it cannot be selected, but the flag does not gray it.
MF_ENABLED | Enables the menu item so it can be selected, restoring it from its grayed state.
MF_GRAYED | Disables the menu item, graying it so it cannot be selected.
MF_MENUBARBREAK | Functions the same as the MF_MENUBREAK flag for a menu bar. For a drop-down menu, submenu, or shortcut menu, the new column is separated from the old column by a vertical line.
MF_MENUBREAK | Places the item on a new line (for a menu bar) or in a new column (for a drop-down menu, submenu, or shortcut menu) without separating columns.
MF_UNCHECKED | Does not place a check mark next to the item (default).

The following groups of flags cannot be used together:

  • MF_DISABLED, MF_ENABLED, and MF_GRAYED
  • MF_MENUBARBREAK and MF_MENUBREAK
  • MF_CHECKED and MF_UNCHECKED
fSpecialFlags
Specifies one or more of the following flags:
Flag | Meaning
CCM_SPECIAL_SEPARATOR = 0x0001 Ignore all other parameters except lInsertionPointID. Add a separator to the end of the menu or the specified insertion point, except that CCM_SPECIAL_SEPARATOR will never add a separator as the first or last item in a menu or submenu. If two or more consecutive CCM_SPECIAL_SEPARATORs are added, only one appears in the menu.

Only IContextMenuProvider is permitted to add separators, either special or otherwise.
CCM_SPECIAL_SUBMENU = 0x0002 | If this submenu is empty, it will be grayed and disabled. This is only valid for MF_POPUP items.
CCM_SPECIAL_DEFAULT_
ITEM = 0x0004 		This should be the default menu item. If more than one menu item specifies this flag, the last one in each submenu takes precedence.
CCM_SPECIAL_INSERTION_
POINT = 0x0008 		Ignore all other parameters except lCommandID and lInsertionPointID. This creates a new insertion point at the end of the insertion point or submenu identified by lInsertionPointID.

Subsequent calls may use the lCommandID from this call as their lInsertionPointID, and insert their own menu items, submenus, or insertion points at this point in this menu.

See Also

IContextMenuCallback, IContextMenuProvider, IExtendContextMenu


MENUBUTTONDATA

The MENUBUTTONDATA structure contains values used to create buttons on a toolbar.

typedef struct _MENUBUTTONDATA
{
    int      idCommand;
    int      x;
    int      y;
} MENUBUTTONDATA;

typedef MENUBUTTONDATA* LPMENUBUTTONDATA;

Members

idCommand
Specifies a user-supplied value that uniquely identifies the menu button.
x
Specifies the horizontal position in pixels of the position at which the snap-in's context menu is to be displayed.
y
Specifies the vertical position in pixels of the position at which the snap-in's context menu is to be displayed.

See Also

IMenuButton, MMCN_MENU_BTNCLICK


MMCBUTTON

The MMCBUTTON structure contains values used to create buttons on a toolbar. This structure is similar to the TBBUTTON structure discussed in the Platform SDK topics related to common controls.

typedef struct _MMCBUTTON
{
    int      nBitmap ;
    int      idCommand;
    BYTE     fsState;
    BYTE     fsType;
        LPOLESTR     lpButtonText;
    LPOLESTR     lpTooltipText;
} MMCBUTTON;
typedef MMCBUTTON* LPMMCBUTTON;

Members

nBitmap
Specifies the zero-based index of a button image.
idCommand
Specifies the command identifier returned when a button is clicked. This can be any integer value the user wants.
fsState
Specifies the button-state flags. This member can be any of the following values:
Value | Meaning
TBSTATE_CHECKED | The button has the TBSTYLE_CHECKED style and is being pressed.
TBSTATE_ENABLED | The button accepts user input. A button that does not have this state does not accept user input and is grayed.
TBSTATE_HIDDEN | The button is not visible and cannot receive user input.
TBSTATE_INDETERMINATE | The button is grayed.
TBSTATE_PRESSED | The button is being pressed.
TBSTATE_WRAP | A line break follows the button. The button must also have the TBSTATE_ENABLED.

fsType
Specifies the button style. This member can be a combination of the following values:
Value | Meaning
TBSTYLE_BUTTON | Creates a standard push button.
TBSTYLE_CHECK | Creates a button that toggles between the pressed and not-pressed states each time the user clicks it. The button has a different background color when it is in the pressed state.
TBSTYLE_CHECKGROUP | Creates a check button that stays pressed until another button in the group is pressed.
TBSTYLE_GROUP | Creates a button that stays pressed until another button in the group is pressed.
TBSTYLE_SEP | Creates a separator, providing a small gap between button groups. A button that has this style does not receive user input.

lpButtonText
Pointer to the text associated with a particular instance of the MMCBUTTON structure.
lpTooltipText
Pointer to the text for a particular tooltip.

See Also

IToolbar


PROPSHEETPAGE

The PROPSHEETPAGE structure defines a page in a property sheet. It is a Win32 structure and the following is taken from the Platform SDK documentation.

typedef struct _PROPSHEETPAGE { // psp
    DWORD     dwSize;
    DWORD     dwFlags;
    HINSTANCE hInstance;
    union {
        LPCTSTR        pszTemplate;
        LPCDLGTEMPLATE pResource;
    };
    union {
        HICON   hIcon;
        LPCTSTR pszIcon;
    };
    LPCTSTR pszTitle;
    DLGPROC pfnDlgProc;
    LPARAM  lParam;
    LPFNPSPCALLBACK pfnCallback;
    UINT FAR * pcRefParent;
} PROPSHEETPAGE, FAR *LPPROPSHEETPAGE;
typedef const PROPSHEETPAGE FAR *LPCPROPSHEETPAGE;

Members

dwSize
Size, in bytes, of the structure. The size includes any extra application-defined data at the end of the structure.
dwFlags
A set of bit flags that enable optional attributes of the property sheet page, and indicate the valid members of the PROPSHEETPAGE structure. This member can be a combination of the following values.
Value | Meaning
PSP_DEFAULT | Uses the default meaning for all structure members.
PSP_DLGINDIRECT | Creates the page from the dialog box template in memory pointed to by the pResource member. The Win32 PropertySheet function assumes that the template is in writeable memory; a read-only template will cause an exception on some versions of Windows. If this flag is not set, the page loads the dialog box template from the resource identified by the pszTemplate member.
PSP_HASHELP | Enables the property sheet Help button when this page is active.
PSP_USECALLBACK | Calls the function specified by pfnCallback when creating or destroying the property sheet page defined by this structure.
PSP_HICON | Uses hIcon as the small icon on the tab for the page.
PSP_USEICONID | Uses pszIcon as the name of the icon resource to load and use as the small icon on the tab for the page.
PSP__USEREFPARENT | Maintains the reference count specified by pcRefParent for the lifetime of the property sheet page created from this structure.
PSP_USETITLE | Uses pszTitle as the title of the property sheet dialog box instead of the title stored in the dialog box template.
PSP_RTLREADING | When this page is active, displays the text of pszTitle using right-to-left reading order on Hebrew or Arabic systems.

hInstance
Handle to the instance from which to load the dialog box template, icon, or title string resource.
pszTemplate
Dialog box template to use to create the page. This member can specify either the resource identifier of the template or the address of a string that specifies the name of the template. If dwFlags includes the PSP_DLGINDIRECT value, this member is ignored.
pResource
Pointer to a dialog box template in memory. The Win32 PropertySheet function assumes that the template is in writeable memory; a read-only template will cause an exception on some versions of Windows. If dwFlags does not include the PSP_DLGINDIRECT value, this member is ignored.
hIcon
Handle to the icon to use as the small icon in the tab for the page. If dwFlags does not include the PSP_USEHICON value, this member is ignored.
pszIcon
Icon resource to use as the small icon in the tab for the page. This member can specify either the identifier of the icon resource or the pointer to the string that specifies the name of the icon resource. If dwFlags does not include the PSP_USEICONID value, this member is ignored.
pszTitle
Title of the property sheet dialog box. This title overrides the title specified in the dialog box template. This member can specify either the identifier of a string resource or the pointer to a string that specifies the title. If dwFlags does not include the PSP_USETITLE value, this member is ignored.
pfnDlgProc
Pointer to the dialog box procedure for the page. The dialog box procedure must not call the Win32 EndDialog function.
lParam
Application-defined data.
pfnCallback
Pointer to an application-defined callback function that is called when the page is created and when it is about to be destroyed. For more information about the Win32 callback function, see PropSheetPageProc. If dwFlags does not include the PSP_USECALLBACK value, this member is ignored.
pcRefParent
Pointer to the reference count value. If dwFlags does not include the PSP_USERREFPARENT value, this member is ignored.

Remarks

When the PropertySheet function creates the page, the dialog box procedure for the page receives a WM_INITDIALOG message. The lParam parameter of this message points to the PROPSHEETPAGE structure used to create the page.

See Also

IExtendPropertySheet, IPropertySheetCallback, IPropertySheetProvider


RESULTDATAITEM

The RESULTDATAITEM structure specifies or receives the attributes of the result pane.

typedef struct _RESULTDATAITEM
{
    DWORD mask;
    BOOL bScopeItem;
    HRESULTITEM  itemID;
    int  nIndex;
    int  nCol;
    LPOLESTR  str;
    int  nImage;
    UINT nState;
    LPARAM  lParam;
    int  iIndent;
} RESULTDATAITEM;
typedef RESULTDATAITEM* LPRESULTDATAITEM;

Members

mask
A set of bit flags that specify attributes of this data structure or of an operation that is using this structure.

The following bit flags specify the members of the RESULTDATAITEM structure that contain valid data or need to be filled in. One or more of these bit flags may be set:
Value: Meaning
RDI_STR = 0x0002 | The str member is valid or needs to be filled in.
RDI_IMAGE = 0x0004 | The nImage member is valid or needs to be filled in.
RDI_STATE = 0x0008 | The nState member is valid or needs to be filled in.
RDI_PARAM = 0x0010 | The lParam member is valid or needs to be filled in.
RDI_INDEX = 0x0020 | The nIndex member is valid or needs to be filled in.
RDI_INDENT = 0x0040 | The iIndent member is valid or needs to be filled in.

bScopeItem
TRUE if the lParam member refers to a scope pane item. FALSE if the lParam member refers to a result pane item.
itemID
Specifies a unique item identifier.
nIndex
Specifies the zero-based index of the item to which this structure refers.
nCol
Specifies the column on which an operation is to be performed or zero if the operation is to be performed on an item rather than an individual column.
str
Pointer to a null-terminated string that contains the item text if the structure specifies RDI_STR item attribute. If this member is the MMC_CALLBACK value, the item is a callback item.
nImage
Virtual image index of the list view item's icon in the large icon and small icon image lists. Note that the virtual image index is internally mapped to the actual index.
nState
Specifies the state mask for the item. It can be one of the following:
Value | Meaning
LVIS_CUT | The item is marked for a cut and paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has focus and on the system colors used for the selection.

lParam
Specifies a user-supplied 32-bit value to associate with the item. This item, also called a cookie, is the value that is passed as the first parameter to IComponent::QueryDataObject.
iIndent
(reserved)

See Also

IResultData


RESULTFINDINFO

Used by IResultOwnerData::FindItem to support keyboard in virtual lists in the result pane.

typedef struct  _RESULTFINDINFO
    {
    LPOLESTR psz;
    int nStart;
    DWORD dwOptions;
    } RESULTFINDINFO;
typedef RESULTFINDINFO __RPC_FAR *LPRESULTFINDINFO;

Members

psz
Zero-terminated string to match.
nStart
Index at which to start search.
dwOptions
Combination of the following flags:
Value | Meaning
RFI_PARTIAL | Match any name that begins with psz.
RFI_WRAP | Continue search at beginning if no match is found.

Remarks

With virtual lists, also known as owner data, only the data's owner knows what is in the list. Because of this, the control itself cannot do keyboard navigation. To support keyboard navigation, the list control calls the snap-in, passing this structure, which specifies the type of match it is looking for, that is, it passes the string to match and an index of the item to start the search on. It also passes two search option flags, which by default are always set.

See Also

IResultOwnerData::FindItem


SCOPEDATAITEM

The SCOPEDATAITEM structure specifies items to be inserted into the scope pane.

typedef struct _SCOPEDATAITEM
{
    DWORD  mask;
    LPOLESTR  displayname;
    int  nImage;
    int  nOpenImage;
    UINT  nState;
    int  cChildren;
    LPARAM  lParam;
    HSCOPEITEM  relativeID;
    HSCOPEITEM  ID;
} SCOPEDATAITEM;
typedef SCOPEDATAITEM* LPSCOPEDATAITEM;

Members

mask
Specifies an array of flags that indicate which of the other structure members contain valid data. When this structure is used in the IConsoleNameSpace::GetItem, it indicates the item attributes to retrieve. This member can be one of the following:
Value | Meaning
SDI_STR = 0x00002 | The displayname member of the structure is valid or needs to be filled in.
SDI_IMAGE = 0x00004 | The nImage member of the structure is valid or needs to be filled in.
SDI_OPENIMAGE = 0x00008 | The nOpenImage member of the structure is valid or needs to be filled in.
SDI_STATE = 0x00010 | The nState member of the structure is valid or needs to be filled in.
SDI_PARAM = 0x00020 | The lParam member of the structure is valid or needs to be filled in.
SDI_CHILDREN = 0x00040 | The cChildren member of the structure is valid or needs to be filled in.
SDI_PARENT = 0x00000000 | Use only when inserting items into the scope pane. The relativeID member of the structure is the HSCOPEITEM of the parent. The item will be inserted as the last child of the item referred to by relativeID.
SDI_PREVIOUS = 0x10000000 | Use only when inserting items into the scope pane. The relativeID member of the structure is the HSCOPEITEM of the previous sibling.
SDI_NEXT = 0x20000000 | Use only when inserting items into the scope pane. The relativeID member of the structure is the HSCOPEITEM of the next sibling.
SDI_FIRST = 0x08000000 | Use only when inserting items into the scope pane. The relativeID member of the structure is the HSCOPEITEM of the parent. The item will be inserted as the first child of the item referred to by relativeID.

displayname
Pointer to a null-terminated string that contains the item text if the structure specifies the SDI_STR item attribute. If this member is the MMC_CALLBACK value, the item is a callback item. When an item is being inserted (IConsoleName::InsertItem calls), this member must be MMC_CALBACK.
nImage
Virtual image index in the image list when the item is in the non-selected state. Note that the virtual image index is mapped internally to the actual index.
nOpenImage
Virtual image index in the image list when the item is in the selected state. Note that the virtual image index is mapped internally to the actual index. The node is like a folder in the Explorer. The icon is for an open folder.
nState
Specifies the state mask for the item. It can be zero or a combination of one or more of the following values:
Value | Meaning
TVIS_BOLD | The item is bold.
TVIS_CUT | The item is selected as part of a cut-and-paste operation.
TVIS_DROPHILITED | The item is selected as a drag-and-drop target.
TVIS_EXPANDED | The item's list of child items is currently expanded; that is, the child items are visible. This value applies only to parent items.
TVIS_EXPANDEDONCE | The item's list of child items has been expanded at least once. The TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages are not sent for parent items that have specified this value. This value applies only to parent items.
TVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has focus and on whether the system colors are used for selection.

cChildren
Specifies the number of enumerated nodes.
lParam
Specifies a user-supplied 32-bit value to associate with the item. This item, also called a cookie, is the value that is passed as the first parameter to IComponentData::QueryDataObject.
relativeID
A console-supplied unique item identifier. An item is inserted at a position relative to the item specified by this member. The relative position is determined by the mask settings.

To determine how relativeID is interpreted, specify one of the following constants as the mask member:

If the mask Member is: | relativeID Values:
SDI_PARENT | relativeID is the HSCOPEITEM of the parent. The item is inserted as the last child of the parent item. The value of SDI_PARENT indicates it is a no-op because, by default, relativeID is the parent item's ID.
SDI_PREVIOUS | relativeID is the HSCOPEITEM of the previous sibling.
SDI_NEXT | relativeID is the HSCOPEITEM of the next sibling.
SDI_FIRST | Same as SDI_PARENT, except that the item is inserted as the first child.

ID
Specifies a console-supplied unique identifier for the scope-pane item. This member is used to identify an item in the scope pane by the IConsoleNameSpace methods, GetItem, SetItem, and DeleteItem.

See also

IComponentData, IComponentData::GetDisplayInfo, IConsoleNameSpace::GetItem, IConsoleNameSpace::InsertItem, IConsoleNameSpace::SetItem


SMMCDataObjects

Clipboard format for the snap in's multi selected data object types for all of the currently selected result items put by the snapin.

typedef struct  _SMMCDataObjects
    {
    DWORD count;
    LPDATAOBJECT lpDataObject[ 1 ];
    }    SMMCDataObjects;

Members

count
The number of snap-ins.
lpDataObject
Array of pointers to the data objects.

Remarks

Each data object consists of the selected item(s) associated with a given snapi-in. Data objects are passed using GlobalAlloc.

See Also

SMMCObjectTypes


SMMCObjectTypes

Clipboard format for the array of GUIDs that constitute the object.

typedef struct _SMMCObjectTypes
{
    DWORD   count;
    GUID    guid[1];

} SMMCObjectTypes;

Members

count
The count of selected items.
guid
Array of GUIDs for the selected items.

See Also

SMMCDataObjects


MMC Enumerations

The following enumerations contain values used for building MMC snap-in components.

DATA_OBJECT_TYPES

MMC_BUTTON_STATE

MMC_CONSOLE_VERB

MMC_CONTROL_TYPE

MMC_MENU_COMMAND_IDS

MMC_NOTIFY_TYPE

MMC_RESULT_VIEW_STYLE


DATA_OBJECT_TYPES

Used by the type parameter of IComponentData::QueryDataObject and IComponent::QueryDataObject to obtain context information about a specified cookie.

typedef enum _DATA_OBJECT_TYPES
{
    CCT_SCOPE            = 0x8000, //
    CCT_RESULT           = 0x8001, //
    CCT_SNAPIN_MANAGER   = 0x8002, //
    CCT_UNINITIALIZED    = 0xFFFF, //

} DATA_OBJECT_TYPES;

Members

Value | Meaning
CCT_SCOPE | Data object for scope pane context
CCT_RESULT | Data object for result pane context
CCT_SNAPIN_MANAGER | Data object for snap-in manager context
CCT_UNINITIALIZED | Data object has an invalid type


MMC_BUTTON_STATE

The MMC_BUTTON_STATE enumeration defines the possible states of buttons available in the Microsoft Management Console. These values are used in the nState parameter of IConsoleVerb::GetVerbState, IConsoleVerb::SetVerbState, IToolbar::GetButtonState, and IToolbar::SetButtonState.

typedef enum _MMC_BUTTON_STATE
{

    ENABLED,           0x1
    CHECKED,           0x2
    HIDDEN,            0x4
    INDETERMINATE,     0x8
    BUTTONPRESSED      0x10

} MMC_BUTTON_STATE;

Members

Value | Meaning
ENABLED | The button accepts user input. A button that does not have this state does not accept user input and is grayed.
CHECKED | The button has the CHECKED style and is being pressed.
HIDDEN | The button is not visible and cannot receive user input.
INDETERMINATE | The button is grayed.
BUTTONPRESSED | The button is being pressed.


MMC_CONSOLE_VERB

The MMC_CONSOLE_VERB enumeration defines the command identifiers available for MMC verbs. These values are used in the m_eCmdID parameter of IConsoleVerb::GetVerbState and IConsoleVerb::SetVerbState.

typedef enum _MMC_CONSOLE_VERB
{

    MMC_VERB_NONE            = 0,
    MMC_VERB_OPEN            = 0x8000,
    MMC_VERB_COPY           = 0x8001,
    MMC_VERB_PASTE          = 0x8002,
    MMC_VERB_DELETE         = 0x8003,
    MMC_VERB_PROPERTIES     = 0x8004,
    MMC_VERB_RENAME         = 0x8005,
    MMC_VERB_REFRESH        = 0x8006,
    MMC_VERB_PRINT          = 0x8007,

} MMC_CONSOLE_VERB;

Members

Value | Meaning
MMC_VERB_NONE | TBD
MMC_VERB_OPEN | Opens the selected folder. Implemented by the console.
MMC_VERB_COPY | Allows the selected item that can be selected to be copied to the clipboard. Implemented by the user.
MMC_VERB_PASTE | Allows the selected item that have been cut or copied to be pasted into the result pane. Implemented by the user.
MMC_VERB_DELETE | Allows the selected item to be deleted. Implemented by the console. A notification will be sent to the snap-in that owns that item.
MMC_VERB_PROPERTIES | The console asks the snap-in and all snap-in extensions to provide property pages for the currently selected item. Implemented by the console.
MMC_VERB_RENAME | Allows the selected item to be renamed. Implemented by the console.
MMC_VERB_REFRESH | Determines whether the currently selected scope item (folder) can be refreshed. Implemented by the user.
MMC_VERB_PRINT | Determines whether the currently selected item can be printed. Implemented by the user.


MMC_CONTROL_TYPE

The MMC_CONTROL_TYPE enumeration type defines the kinds of controls that can appear in the control bar. The values can be used in the nType parameter of the IControlbar::Attach and IControlbar::Create methods.

typedef enum _MMC_CONTROL_TYPE
{

    TOOLBAR,
    MENUBUTTON,
    COMBOBOXBAR  // Not implemented

} MMC_CONTROL_TYPE;

Members

TOOLBAR
The control to be associated with the control bar is a toolbar.
MENUBUTTON
The control is a dropdown menu. This is a standard Win32 menu button.
COMBOBOXBAR
Not implemented at this time. This is a standard Win 32 combo box.

See Also

IControlbar::Attach, IControlbar::Create


MMC_MENU_COMMAND_IDS

Command Identifiers that are reserved by Microsoft Management Console.

typedef enum _MMC_MENU_COMMAND_IDS
{
    MMCC_STANDARD_VIEW_SELECT = -1
} MMC_MENU_COMMAND_IDS;

Members

Value | Meaning
MMCC_STANDARD_VIEW_SELECT | Sent to a snap-in's IExtendContextMenu::Command method when the user switches from a custom result view to the standard list view.

Remarks

Typically, a snap-in's IExtendContextMenu::Command method is called only when one of its own menu items is selected. The MMCC_* codes are sent when a built-in menu item is selected but the snap-in needs to be informed of the selection. Other MMCC_* codes may be added later.

MMCC_STANDARD_VIEW_SELECT notifies the snap-in that the custom view is going away and the snap-in can do any necessary clean up. The next time the snap-in's IComponent::GetResultViewType is called, the snap-in should return S_FALSE to indicate that the default list view should be used.


MMC_NOTIFY_TYPE

The MMC_NOTIFY_TYPE enumeration type defines the notifications of user actions that can be sent to a snap-in by the console's node manager when it calls IComponentData::Notify, IComponent::Notify, or IExtendControlbar::ControlbarNotify. The following are detailed in MMC Notifications.

typedef enum _MMC_NOTIFY_TYPE
{
    MMCN_ACTIVATE          = 0x8001,
    MMCN_ADD_IMAGES            = 0x8002
    MMCN_BTN_CLICK         = 0x8003,
    MMCN_CLICK             = 0x8004,
    MMCN_DBLCLICK          = 0x8005,
    MMCN_DELETE            = 0x8006,
    MMCN_EXPAND            = 0x8007,
    MMCN_MINIMIZED         = 0x8008,
    MMCN_PROPERTY_CHANGE   = 0x8009,
    MMCN_REMOVE_CHILDREN   = 0x800A,
    MMCN_RENAME            = 0x800B,
    MMCN_SELECT            = 0x800C,
    MMCN_SHOW              = 0x800D,
    MMCN_VIEW_CHANGE       = 0x800E,
    MMCN_CONTEXTMENU       = 0X800f,
    MMCN_MENU_BTNCLICK     = 0X8010,
    MMCN_HELP              = 0X8011,
    MMCN_MULTI_SELECT      = 0X8012,
    MMCN_REFRESH           = 0X8013,

} MMC_NOTIFY_TYPE;

Members

See individual notifications.


MMC_RESULT_VIEW_STYLE

The MMC_RESULT_VIEW_STYLE enumeration type defines the Win32 list-view style (LVS_*) flags that can be used to set the view style in the MMC result view pane. They can be used in the add and remove parameters of the IResultData::ModifyViewStyle method.

typedef enum _MMC_RESULT_VIEW_STYLE
{
    MMC_SINGLESEL       = 0x0001,
    MMC_SHOWSELALWAYS   = 0x0002,
    MMC_NOSORTHEADER    = 0x0003,

} MMC_RESULT_VIEW_STYLE;

Members

Value | Meaning
MMC_SINGLESEL | Allows only one item at a time to be selected. By default, multiple items can be selected.
MMC_SHOWSELALWAYS | Always show the selection, if any, even if the control does not have the focus.
MMC_NOSORTHEADER | Specifies that column headers do not work like buttons. This style is useful if clicking on a column header in report view does not carry out an action, such as sorting.


MMC_SCOPE_ITEM_STATE

Not implemented.

typedef enum _MMC_SCOPE_ITEM_STATE
    {  MMC_SCOPE_ITEM_STATE_NORMAL        = 0x1,
       MMC_SCOPE_ITEM_STATE_BOLD          = 0x2,
       MMC_SCOPE_ITEM_STATE_EXPANDEDONCE  = 0x3
    }  MMC_SCOPE_ITEM_STATE;
Value Meaning
MMC_SCOPE_ITEM_STATE_NORMAL
 Not Bold. To set or get.
MMC_SCOPE_ITEM_STATE_BOLD
 Bold. To set or get.
MMC_SCOPE_ITEM_STATE_EXPANDEDONCE
 Only get.


MMC Notifications

Notifications are generated by events caused by user input. The console informs the node manager of an event that determines which notification to send. They can be sent to IComponentData::Notify, IComponent::Notify, or IExtendControlbar::ControlbarNotify, depending on the individual notification.

MMCN_ACTIVATE

MMCN_ADD_IMAGES

MMCN_BTN_CLICK

MMCN_CLICK

MMCN_COLUMN_CLICK

MMCN_CONTEXTHELP

MMCN_CONTEXTMENU

MMCN_CUTORMOVE

MMCN_DBLCLICK

MMCN_DELETE

MMCN_DESELECT_ALL

MMCN_EXPAND

MMCN_HELP

MMCN_INITOCX

MMCN_MENU_BTNCLICK

MMCN_MINIMIZED

MMCN_PASTE

MMCN_PROPERTY_CHANGE

MMCN_QUERY_PASTE

MMCN_REFRESH

MMCN_REMOVE_CHILDREN

MMCN_RENAME

MMCN_SELECT

MMCN_SHOW

MMCN_SNAPINHELP

MMCN_VIEW_CHANGE


MMCN_ACTIVATE

Sent to the snap-in's IComponent::Notify method when a window is being activated or deactivated.

Parameters

lpDataObject
[in] Pointer to the data object of the currently selected scope pane item.
arg
TRUE if the window is activated; otherwise, it is FALSE.
param
Not used.

Return Values

Not used.

See Also

IComponent::Notify


MMCN_ADD_IMAGES

Sent to the snap-in's IComponent implementation to add images for the result pane.

Parameters

lpDataObject
[in] Pointer to the data object of the currently selected scope pane item.
arg
Pointer to the result pane's image list (IImageList).
param
Specifies the HSCOPEITEM of the item that was selected or deselected.

Return Values

Not used.

Remarks

The primary snap-in should add images for both folders and leaf items. Extension snap-ins should add only folder images.

See Also

IComponent::Notify, IComponentData::Notify, IExtendControlbar::ControlbarNotify


MMCN_BTN_CLICK

Sent to the snap-in's IComponent, IComponentData, or IExtendControlbar implementation when a user clicks on one of the toolbar buttons.

Parameters

For IComponent::Notify or IComponentData::Notify:

lpDataObject
[in] Pointer to the data object of the currently selected scope or result pane item.
arg
Must be zero.
param
CmdID of the button equal to a value of the MMC_CONSOLE_VERB enumeration.

For IExtendControlBar::ControlbarNotify:

arg
Data object of the currently selected scope or result pane item.
param
[in] CmdID of the button equal to a value of the MMC_CONSOLE_VERB enumeration.

Return Values

Not used.

See Also

IComponent::Notify, IComponentData::Notify, IExtendControlbar::ControlbarNotify


MMCN_CLICK

Sent to IComponent when a user clicks a mouse button on a list view item.

Parameters

lpDataObject
[in] Pointer to the data object of the currently selected result pane item.
arg
Not used.
param
Not used.

Return Values

Not used.

See Also

IComponent


MMCN_COLUMN_CLICK

[This is pr69eliminary documentation and subject to change.]

Sent when the user clicks on a result-list view column header.

Parameters

pDataobject
NULL.
arg
Column number.
param
Sort option flags. By default, the sort is in ascending order. To specify descending order, use the RSI_DESCENDING (0x0001) flag.

Return Values

Not used.


MMCN_CONTEXTHELP

Sent when the user requests help about a selected item

Parameters

arg
0.
param
0.

Return Values

Not used.


MMCN_CONTEXTMENU

Not used.

Parameters

arg
TBD
param
TBD

Return Values

Not used.


MMCN_CUTORMOVE

Specifies a data object listing the items to be cut or moved.

Parameters

pDataobject
NULL.
arg
Pointer to a data object.
param
Not used.

Return Values

Not used.

Remarks

In the case of moving items from a source to a destination, a data object is passed from the source to the destination that lists the items to be moved. The destination should copy the items and then return a data object that lists the successfully copied items. That data object is then passed to the source, along with the MMCN_CUTORMOVE notification. The source should then delete the successfully copies items.


MMCN_DBLCLICK

Sent to IComponent when a user double clicks a mouse button on a list view item.

Parameters

lpDataObject
[in] Pointer to the data object of the currently selected result pane item.
arg
Not used.
param
Not used.

Return Values

Not used.

See Also

IComponent


MMCN_DELETE

Sent to the snap-in's IComponent and IComponentData implementation to inform the snap-in that the object should be deleted.

Parameters

lpDataObject
[in] Pointer to the data object of the currently selected scope or result pane item provided by the snap-in.
arg
Not used.
param
Not used.

Return Values

Not used.

Remarks

This message is generated when the user presses the delete key or uses the mouse to click on the toolbar's delete button.

See Also

IComponent::Notify, IComponentData::Notify


MMCN_DESELECT_ALL

Sent to the virtual list view when all items of an owner-data result pane are deselected.

Parameters

dataobject
NULL.
arg
0
param
0

Return Values

Not used.

Remarks

When an item is deselected in a virtual list view, unlike a regular list view, there is no way to know which item was deselected. Only -1 is passed, indicating deselect all. Because of this, this notification is not sent for virtual list views.


MMCN_EXPAND

Sent to the snap-in's IComponentData implementation when a folder needs to be expanded or contracted.

Parameters

lpDataObject
[in] Pointer to the data object of the scope pane item that needs to be expanded.
arg
[in] If TRUE, the folder needs to be expanded. If FALSE, the folder needs to be contracted.
Param
[in] The HSCOPEITEM of the item that needs to be expanded.

Return Values

Not used.

Remarks

On receipt of this notification the snap-in should enumerate the children (sub-containers only) of the specified scope item, if any, using IConsoleNameSpace methods. Subsequently, if a new item is added to or deleted from this scope object through some external means, then that item should also be added to or deleted from the console's namespace using IConsoleNameSpace methods.

See Also

IComponentData::Notify, IConsoleNameSpace


MMCN_HELP

Not used.

Sent when the user presses the F1 help key.

Parameters

arg
TBD
param
Pointer to a GUID. If NULL, the NodeType is used instead.

Return Values

Not used.

See Also

TBD


MMCN_INITOCX

Sent to snap-ins having a custom OCX as the result pane.

Parameters

arg
Not used.
param
The IUnknown to the result pane. This is the same IUnknown you would get from IConsole::QueryResultView.

Remarks

When an OCX is created for the first time, and needs to be initialized, the snap-in is sent an MMCN_INITOCX notification.

Return Values

Not used.

See Also

TBD


MMCN_MENU_BTNCLICK

Sent to the snap-in's IExtendControlbar interface when a user clicks on a menu button.

Parameters

arg
Data object of currently selected scope or result pane item.
Param
[in] Pointer to a MENUBUTTONDATA structure.

Return Values

Not Used.

See Also

IMenuButton, IMenuButton::SetButtonState


MMCN_MINIMIZED

Sent to the snap-in's IComponent implementation when a window is being minimized or maximized.

Parameters

lpDataObject
[in] Pointer to the data object of the currently selected scope pane item.
arg
TRUE if the window has been minimized; otherwise, it is FALSE.
Param
Not used.

Return Values

Not Used

See Also

IComponent::Notify


MMCN_PASTE

Called to ask the snap-ins folder to paste the selected items.

Parameters

pDataobject
The data object in which to paste the selected items provided by the snap-in.
arg
The data object of the selected item(s) provided by the source snap-in that need to be pasted.
param
NULL for move (as opposed to cut).

For a single-item paste:

BOOL* pPasted = (BOOL*)param; Set this to TRUE here if the item was successfully pasted.

For a multiitem paste:

LPDATAOBJECT* ppDataObj = (LPDATAOBJECT*)param;

Use this to return a pointer to a data object consisting of the items successfully pasted. See MMCN_CUTORMOVE.

Return Values

Not used.

See Also

MMCN_CUTORMOVE


MMCN_PROPERTY_CHANGE

When the snap-in uses the MMCPropertyChangeNotify function to notify it's views about changes, MMC_PROPERTY_CHANGE is sent to the snap-in's IComponentData and IComponent implementations.

Parameters

lpDataObject
This value is NULL because a data object is not required.
arg
[in] TRUE if the property change is for a scope pane item.
lParam
This is the param passed into MMCPropertyChangeNotify.

Return Values

Not used.

See Also

IComponent::Notify, IComponentData::Notify, MMCPropertyChangeNotify


MMCN_QUERY_PASTE

Sent to the snap-in before pasting into the snap-in's folder to determine if the snap-in can accept the data.

Parameters

pdataobject
The dataobject of the selected item provided by the snap-in.
arg
The dataobject of the item(s) provided by the source snap-in that need to be pasted.
param
Not used.

Return Values

Not used.

See Also

MMCN_PASTE


MMCN_REMOVE_CHILDREN

Sent to the snap-in's IComponentData implementation to inform the snap-in that it must delete all the cookies (the entire subtree) it has added below the specified node.

Parameters

lpDataObject
[in] Pointer to the data object of the scope pane node whose children need to be removed.
arg
Specifies the HSCOPEITEM of the node whose children need to be deleted.
param
Not used.

Return Values

Not used.

Remarks

Use IConsoleNameSpace methods GetChildItem and GetNextItem to traverse the tree and determine the cookies to be deleted.

See Also

IComponent::Notify, IComponentData::Notify


MMCN_REFRESH

TBD

Parameters

Return Values

Not used.

See Also


MMCN_RENAME

Called the first time to query for a rename and the second time to do the rename.

Parameters

arg
Not used.
param
LPOLESTR for containing the new name.

Return Values

S_OK
Allows the rename.
S_FALSE
Disallows the rename.

See Also

TBD


MMCN_SELECT

Sent to the snap-in's IComponent::Notify or IExtendControlbar::ControlbarNotify when an item in either the scope pane or result view pane is selected.

Parameters

For IComponent::Notify:

lpDataObject
[in] Pointer to the data object of the currently selected scope pane item.
arg
BOOL bScope = (BOOL) LOWORD(arg);

BOOL bSelec = (BOOL) HIWORD(arg);

bScope

TRUE if an item in the scope pane is selected.

FALSE if an item in the result view pane is selected.

bSelect

TRUE if the item is selected.

FALSE if the item is deselected.

param
This parameter is ignored.

For IExtendControlbar::ControlbarNotify:

arg
BOOL bScope = (BOOL) LOWORD(arg);

BOOL bSelect = (BOOL) HIWORD(arg);

bScope:

TRUE if an item in the scope pane is selected.

FALSE if an item in the result pane is selected.

bSelect:

TRUE if the item is selected.

FALSE if the item is deselected.

param
LPDATAOBJECT pDataobject = (LPDATAOBJECT)param;

pDataobject data object of the item being selected or deselected.

Return Values

Not used.

Remarks

When an IComponent::Notify method receives the MMCN_SELECT notification it should update the standard verbs.

When an IExtendControlbar::ControlbarNotify method receives the MMCN_SELECT notification it should update the custom toolbars. On select, it should detach unused toolbars and attach new ones as needed. On deselect, to minimize flashing, it should not detach toolbars; it is best to disable them, but doing nothing on deselect is also acceptable.

Snap-ins should have the ability to create and attach toolbars when they receive a selection notification, regardless of whether the item is in the scope pane or result pane.

See Also

IComponent::Notify, IExtendControlbar::ControlbarNotify


MMCN_SHOW

Sent when a scope item is selected or deselected for the first time.

Parameters

arg
TRUE (<>0 ) if selecting; True indicates that the snap-in should set up the result pane and add the enumerated items.

FALSE (0) if deselecting. indicates that the snap-in is going out of focus and that it should clean up all cookies the right hand side (the result pane), because current result pane will be replaced by a new one.

param
The HSCOPEITEM of the selected or deselected item.

Return Values

Not used.

See Also

TBD


MMCN_SNAPINHELP

Sent when the user requests help about the snap-in.

Parameters

dataObject
NULL
arg
0
param
0

Return Values

Not used.


MMCN_VIEW_CHANGE

Sent to the snap-in's IComponent implementation so it can update all views when a change occurs.

Parameters

lpDataObject
[in] Pointer to the data object passed to IConsole::UpdateAllViews.
arg
[in] The data parameter passed to IConsole::UpdateAllViews.
param
[in] The hint parameter passed to IConsole::UpdateAllViews.

Return Values

Not used.

Remarks

This notification is generated when the snap-in (IComponent or IComponentData) calls IConsole::UpdateAllViews.

See Also

IComponent::Notify, IConsole::UpdateAllViews


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.