MMC Snap-In Class CSnapInItemImpl

Introduction

The Snap-In classes allow you to develop Microsoft Management Console (MMC) snap-in components. There are two MMC Snap-In classes: CSnapInItemImpl and CSnapInPropertyPageImpl. CSnapInItemImpl helps to implement a snap-in node object, while CSnapInPropertyPageImpl implements the snap-in property page object.

In this article, we will learn about the class CSnapInItemImpl, its syntax, constructor, methods, and data members.

Let’s get started.

CSnapInItemImpl Class

CSnapInItemImpl provides methods to implement a snap-in node object.

It's important to note that you can't use this class and its members in applications that run in windows runtime.

You need to include the header file atlsnap.h to use this class.

Syntax

template <class T, BOOL bIsExtension = FALSE>
class ATL_NO_VTABLE CSnapInItemImpl : public CSnapInItem

Parameters

T
It refers to the class you derive from CSnapInItemImpl.
bIsExtension
It determines whether the object is a snap-in extension or not. Its value is TRUE if the object is a snap-in extension or else FALSE.

Remarks

The CSnapInItemImpl class helps implement a snap-in node object through various interfaces and map types. It allows adding menu items and toolbars and forwarding commands to suitable handler functions. The default implementation of the node object handles notifications sent to the node by finding the right instance of the derived class and then forwarding them to the correct instance.

Members

CSnapInItemImpl class consists of public constructors, public methods, and public data members.

See the table below, which summarizes all the members and their descriptions.

Public Constructors
Name	Description
CSnapInItemImpl::CSnapInItemImpl	It is the constructor for the class CSnapInItemImpl.

Public Methods
Name	Description
CSnapInItemImpl::AddMenuItems	It adds menu items to a context menu.
CSnapInItemImpl::Command	It gets called by the console when a custom menu item is selected.
CSnapInItemImpl::CreatePropertyPages	It adds pages to the property sheet of the snap-in.
CSnapInItemImpl::FillData	It copies the information on the snap-in object into a specified stream.
CSnapInItemImpl::GetResultPaneInfo	It retrieves the RESULTDATAITEM structure of the snap-in.
CSnapInItemImpl::GetResultViewType	It determines the type of view used by the result pane.
CSnapInItemImpl::GetScopePaneInfo	It retrieves the SCOPEDATAITEM structure of the snap-in.
CSnapInItemImpl::Notify	The console calls this function for notifying the snap-in of actions taken by the user.
CSnapInItemImpl::QueryPagesFor	The console calls this function for checking if the snap-in node supports property pages.
CSnapInItemImpl::SetMenuInsertionFlags	It modifies the menu insertion flags for a snap-in object.
CSnapInItemImpl::SetToolbarButtonInfo	It sets the information of the specified toolbar button.
CSnapInItemImpl::UpdateMenuState	It updates the state of a context menu item.
CSnapInItemImpl::UpdateToolbarButton	It updates the state of the specified toolbar button.

Public Data Members
Name	Description
CSnapInItemImpl::m_bstrDisplayName	It specifies the name of the snap-in object.
CSnapInItemImpl::m_resultDataItem	It refers to the Windows RESULTDATAITEM structure used by the CSnapInItemImpl object.
CSnapInItemImpl::m_scopeDataItem	It refers to the Windows SCOPEDATAITEM structure used by the CSnapInItemImpl object.

Let’s see all the class members in detail in the upcoming sections.

Public Constructors

CSnapInItemImpl::CSnapInItemImpl

It is the constructor invoked every time a new object is created.

Syntax

CSnapInItemImpl();

Public Methods

In this section, we will see the various public methods in the class CSnapInItemImpl, their syntax, and their functionalities.

CSnapInItemImpl::AddMenuItems

The function AddMenuItems adds menu times to a context menu and implements the Win32 function IExtendContextMenu::AddMenuItems.

Syntax

AddMenuItems(
    LPCONTEXTMENUCALLBACK piCallback,
    long* pInsertionAllowed,
    DATA_OBJECT_TYPES type);

Parameters

piCallback
It is an input parameter that points to the IContextMenuCallback for adding items to the context menu.
pInsertionAllowed
It identifies the Microsoft Management Console (MMC)-defined menu-item insertion points that can be used. It can be a combination of the following flags:
- CCM_INSERTIONALLOWED_TOP
  It implies that the items can be inserted at the top of a context menu.
- CCM_INSERTIONALLOWED_NEW
  It implies that the items can be inserted in the Create New submenu.
- CCM_INSERTIONALLOWED_TASK
  It implies that the items can be inserted in the Task submenu.
- CCM_INSERTIONALLOWED_VIEW
  It implies that the items can be inserted in the toolbar view menu or the View submenu of the result pane context menu.
type
It specifies the type of the object and can take one of the following values:
- CCT_SCOPE
  It refers to the data object for the scope pane context.
- CCT_RESULT
  It refers to the data object for the result pane context.
- CCT_SNAPIN_MANAGER
  It refers to the data object for the snap-in manager context.
- CCT_UNINITIALIZED
  It refers to the data object having an invalid type.

CSnapInItemImpl::Command

The console calls the function CSnapInItemImpl::Command when you select a custom menu item. It implements the Win32 function IExtendContextMenu::Command.

Syntax

Command(long lCommandID, DATA_OBJECT_TYPES type);

Parameters

lCommandID
It is an input parameter specifying the command identifier of the menu item.
type
It specifies the object type and can take one of the following values:
- CCT_SCOPE
  It refers to the data object for scope pane context.
- CCT_RESULT
  It refers to the data object for the result pane context.
- CCT_SNAPIN_MANAGER
  It refers to the data object for the snap-in manager context.
- CCT_UNINITIALIZED
  It refers to the data object having an invalid type.

CSnapInItemImpl::CreatePropertyPages

The function CSnapInItemImpl::CreatePropertyPages adds pages to the property sheet of the snap-in by implementing the Win32 function IExtendPropertySheet::CreatePropertyPages.

Syntax

CreatePropertyPages(
    LPPROPERTYSHEETCALLBACK lpProvider,
    long handle,
    IUnknown* pUnk,
    DATA_OBJECT_TYPES type);

Parameters

lpProvider
It points to the IPropertySheetCallback interface.
handle
It is an input parameter specifying the handle used for routing the MMCN_PROPERTY_CHANGE notification message to the appropriate data class.
pUnk
It is an input parameter pointing to the IExtendPropertySheet interface on the object that contains contextual information about the node.
type
It specifies the object type and can take one of the following values:
- CCT_SCOPE
  It refers to the data object for the scope pane context.
- CCT_RESULT
  It refers to the data object for the result pane context.
- CCT_SNAPIN_MANAGER
  It refers to the data object for the snap-in manager context.
- CCT_UNINITIALIZED
  It refers to the data object having an invalid type.

CSnapInItemImpl::FillData

The function CSnapInItemImpl::FillData copies the information on the snap-in object into a specified stream. We call this function to retrieve information about the item.

Syntax

FillData(CLIPFORMAT cf, LPSTREAM pStream);

Parameters

cf
It is an input parameter specifying the clipboard format (text, rich text, or rich text with OLE items).
pStream
It points to the stream containing the object data.

Remarks

You can implement this function properly by copying the correct information into the stream (pStream), depending on the Clipboard format indicated by cf.

CSnapInItemImpl::GetResultPaneInfo

The function CSnapInItemImpl::GetResultPaneInfo retrieves the snap-in’s RESULTDATAITEM structure.

Syntax

GetResultPaneInfo (RESULTDATAITEM* pResultDataItem);

Parameters

pResultDataItem
It points to the RESULTDATAITEM structure of the CSnapInItemImpl object.

CSnapInItemImpl::GetResultViewType

The function CSnapInItemImpl::GetResultViewType specifies the view type used by the result pane of the snap-in object.

Syntax

GetResultViewType(
    LPOLESTR* ppViewType,
    long* pViewOptions);

Parameters

ppViewType
It points to the address of the returned view type.
pViewOptions
It points to the MMC_VIEW_OPTIONS enumeration that provides the console with options specified by the owning snap-in. It can take one of the following values:
- MMC_VIEW_OPTIONS_NOLISTVIEWS = 0x00000001
  It refrains the console from presenting standard list view choices in the View menu and allows the snap-in to display its own custom views only in the result view pane.
- MMC_VIEW_OPTIONS_NONE = 0
  It allows the default view options.

CSnapInItemImpl::GetScopePaneInfo

The function CSnapInItemImpl::GetScopePaneInfo retrieves the SCOPEDATAITEM structure of the snap-in.

Syntax

GetScopePaneInfo (SCOPEDATAITEM* pScopeDataItem);

Parameters

pScopeDataItem
It points to the CSnapInItemImpl object’s SCOPEDATAITEM structure.

CSnapInItemImpl::Notify

The console calls the function CSnapInItemImpl::Notify to notify the snap-in of actions taken by the user.

Syntax

STDMETHOD(Notify)(
    MMC_NOTIFY_TYPE event,
    long arg,
    long param,
    IComponentData* pComponentData,
    IComponent* pComponent,
    DATA_OBJECT_TYPES type) = 0;

Parameters

event
It specifies the action user takes and the possible notifications are:
- MMCN_ACTIVATE
  It is sent when a window is being activated and deactivated.
- MMCN_ADD_IMAGES
  It is sent to add images to the result pane.
- MMCN_BTN_CLICK
  It is sent when the user clicks one of the toolbar buttons.
- MMCN_CLICK
  It is sent when a user clicks a mouse button on a list view item.
- MMCN_DBLCLICK
  It is sent when a user double-clicks a mouse button on a list view item.
- MMCN_DELETE
  It is sent to inform the snap-in that the object should be deleted.
- MMCN_EXPAND
  It is sent when a folder needs to be expanded or contracted.
- MMCN_MINIMIZED
  It is sent when a window is minimized or maximized.
- MMCN_PROPERTY_CHANGE
  It is sent to notify a snap-in object that the snap-in object's view is about to change.
- MMCN_REMOVE_CHILDREN
  It is sent when the snap-in must delete the subtree it has added below the specified node.
- MMCN_RENAME
  It is sent the first time to query for a rename and the second time to do the rename.
- MMCN_SELECT
  It is sent when an item in the scope or result view pane is selected.
- MMCN_SHOW
  It is sent when a scope item is selected or deselected for the first time.
- MMCN_VIEW_CHANGE
  It is sent when the snap-in can update all views when a change occurs.
arg
Its value depends upon the notification type.
param
Its value also depends upon the notification type.
pComponentData
It points to the object implementing IComponentData. It's NULL if IComponentData::Notify does not forward the notification.
pComponent
It points to the object implementing IComponent. It's NULL if IComponentData::Notify does not forward the notification.
type
It specifies the type of object and can take one of the following values:
- 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
  The data object has an invalid type.

CSnapInItemImpl::QueryPagesFor

The function CSnapInItemImpl::QueryPagesFor shows whether a snap-in node supports property pages or not.

Syntax

QueryPagesFor(DATA_OBJECT_TYPES type);

CSnapInItemImpl::SetMenuInsertionFlags

The function CSnapInItemImpl::SetMenuInsertionFlags modifies the menu insertion flags, specified by pInsertionAllowed, for the snap-in object.

Syntax

void SetMenuInsertionFlags(
    bool bBeforeInsertion,
    long* pInsertionAllowed);

Parameters

bBeforeInsertion
Its value is non-zero if you need to call the function before items are added to the context menu, else it is 0.
pInsertionAllowed
It identifies Microsoft Management Console (MMC)-defined, menu-item insertion points that can be used. It can be a combination of the following flags:
- CCM_INSERTIONALLOWED_TOP
  It implies that the items can be inserted at the top of a context menu.
- CCM_INSERTIONALLOWED_NEW
  It implies that the items can be inserted in the Create New submenu.
- CCM_INSERTIONALLOWED_TASK
  It implies that the items can be inserted in the Task submenu.
- CCM_INSERTIONALLOWED_VIEW
  It implies that the items can be inserted in the toolbar view menu or in the View submenu of the result pane context menu.

Remarks

You can reset any of the insertion flags while developing a primary snap-in for restricting the menu type 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.

Also, you should not set the bits in pInsertionAllowed that were cleared originally.

CSnapInItemImpl::SetToolbarButtonInfo

The function CSnapInItemImpl::SetToolbarButtonInfo modifies toolbar button styles, of the snap-in object, before the toolbar is created.

Syntax

void SetToolbarButtonInfo(
    UINT id,
    BYTE* fsState,
    BYTE* fsType);

Parameters

id
It is the ID of the toolbar button which you want to set.
fsState
It refers to the button’s state flag. It can take one or more of the following values:
- TBSTATE_CHECKED
  The button has the TBSTYLE_CHECKED style and is being pressed.
- TBSTATE_ENABLED
  The button accepts user input. A button not having this state does not accept user input and is grayed.
- TBSTATE_HIDDEN
  The button is not visible and can’t 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 should have the flag TBSTATE_ENABLED.
fsType
It refers to the button’s state flag. It can take one or more of the following values:
- TBSTYLE_BUTTON
  It creates a standard push button.
- TBSTYLE_CHECK
  It creates a button that toggles between the pressed and not-pressed states each time the user clicks it.
- TBSTYLE_CHECKGROUP
  It creates a check button that stays pressed until another button in the group is pressed.
- TBSTYLE_GROUP
  It creates a button that stays pressed until another button in the group is pressed.
- TBSTYLE_SEP
  It creates a separator, providing a small gap between button groups. A button that has this style does not receive user input.

CSnapInItemImpl::UpdateMenuState

The function CSnapInItemImpl::UpdateMenuState modifies a menu item before it is inserted into the context menu of the snap-in object.

Syntax

void UpdateMenuState(
    UINT id,
    LPTSTR pBuf,
    UINT* flags);

Parameters

id
It stores the ID of the menu item you want to set.
pBuf
It points to the string for the menu item you want to update.
flags
It specifies the new state flags and can be a combination of the following flags:
- MF_POPUP
  This flag indicates that this is a submenu within the context menu. You can add the menu items, insertion points, and further submenus to this submenu using its lCommandID as their IInsertionPointID.
- MF_BITMAP and MF_OWNERDRAW
  These flags are not permitted and will return a value of E_INVALIDARG.
- MF_SEPARATOR
  This flag draws a horizontal dividing line. IContextMenuProvider can add the menu items with the MF_SEPARATOR set.
- MF_CHECKED
  It adds a checkmark next to the menu item.
- MF_DISABLED
  It disables the menu item, so you cannot select it, but the flag does not gray it.
- MF_ENABLED
  It enables the menu item so you can select it, and restore it from its grayed state.
- MF_GRAYED
  It disables the menu item, graying it so you cannot select it.
- MF_MENUBARBREAK
  It functions the same as the MF_MENUBREAK flag for a menu bar. The new column gets separated from the old column by a vertical line for a drop-down menu, submenu, or shortcut menu.
- MF_MENUBREAK
  It 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
  It does not place a checkmark next to the item by default.

It is important to note that you can’t use the following group of flags together:

MF_DISABLED, MF_ENABLED, and MF_GRAYED.
MF_MENUBARBREAK and MF_MENUBREAK.
MF_CHECKED and MF_UNCHECKED.

CSnapInItemImpl::UpdateToolbarButton

The function CSnapInItemImpl::UpdateToolbarButton modifies a toolbar button, of the snap-in object, before it is displayed.

Syntax

BOOL UpdateToolbarButton(UINT id, BYTE fsState);

Parameters

id
It is the button of the toolbar button which you want to update.
fsState
It specifies the button state. If you want to set the state, return TRUE. fsState can be a combination of the following possible flags:
- ENABLED
  It enables a button allowing it to accept user input. If a button does not have this state, then it's grayed and can't accept the user’s input.
- CHECKED
  It means the button has a CHECKED style and is being pressed.
- HIDDEN
  It implies that the button is not visible and cannot receive user input.
- INDETERMINATE
  It makes the button gray.
- BUTTONPRESSED
  It implies that the button is being pressed.

Public Data Members

In this section, we will see the public data members present in the class CSnapInItemImpl.

CSnapInItemImpl::m_bstrDisplayName

It refers to the name of the snap-in object and stores the string for the node item.

Syntax

CComBSTR m_bstrDisplayName;

CSnapInItemImpl::m_resultDataItem

It refers to the RESULTDATAITEM structure of the snap-in data object.

Syntax

RESULTDATAITEM m_resultDataItem;

CSnapInItemImpl::m_scopeDataItem

It refers to the SCOPEDATAITEM structure of the snap-in data object.

Syntax

SCOPEDATAITEM m_scopeDataItem;

Inheritance Hierarchy

The class CSnapInItemImpl inherits the class CSnapInItem.

Frequently Asked Questions

What is MMC?

MMC stands for Microsoft Management Console. It offers a common framework for running various snap-ins, which allows the management of several services through a single interface.

What is an MMC event viewer?

An MMC Event Viewer is a Microsoft Management Console (MMC) snap-in that enables us to browse and manage event logs.

What is COM?

COM stands for Component Object Model, which is a platform-independent and object-oriented system that enables us to create binary software components that can interact.

Conclusion

In this article, we learned about the MMC snap-in class CSnapInItemImpl, its syntax, constructor, methods, and data members.

We hope this blog has helped you enhance your knowledge of the MMC snap-in class CSnapInItemImpl.

Check out these useful blogs on windows support classes:

Refer to our guided paths on Coding Ninjas Studio to learn more about DSA, Competitive Programming, JavaScript, System Design, etc. Enroll in our courses and refer to the mock test and problems available, interview puzzles, take a look at the interview experiences, and interview bundle for placement preparations.

Do upvote our blog to help other ninjas grow

Happy Reading!!‍