Sharing Data with the SMS Administrator Console

You can extend the SMS Administrator Console by writing extension snap-ins. This guide addresses Microsoft® Systems Management Server (SMS) -specific snap-in issues only. You must already be familiar with COM programming, the MMC COM interfaces, and C++ application programming.

Extension snap-ins typically use the clipboard to share data. The SMS Administrator Console does not use the clipboard, but instead uses its own mechanism called named values. The node's data is made available to extensions through these named values, which can be accessed from the IDataObject interface.

Most nodes in the SMS Administrator Console contain node-specific WMI data. In addition to a node's instance data, each node contains other related data items, some of which may be of interest to extension snap-ins.

Determining the Named Values for a Node

To determine the named values for a node, you must start the SMS Administrator Console using the /SMS:NodeInfo=2 command-line option. This option adds the Node Information tab to the property sheet. The Node Information tab contains the GUID and instance data for the node. The named values can be seen by clicking the Named Values button at the bottom of the property sheet.

Typically, you will use the IWbemClassObject and IWbemServices named values. The IWbemClassObject named value contains the pointer to the instance data for the node. It is up to you to save your changes to the instance data.

For a complete list of named values and their descriptions, see SMS Named Values.

Preventing a Race Condition

It is possible to create a race condition when updating an instance. A race condition occurs when two snap-ins try to update the same instance. The provider reflects the changes of the last called snap-in. This is why it is important to ensure that the functionality you are adding does not conflict with existing functionality that currently modifies the instance data.

The property sheet presents the greatest opportunity for developing a race condition. This is why you are discouraged from extending a node's property sheet, unless it is for read-only purposes or provides updates to unrelated data.

Accessing the Named Values

To get access to the named values, you need to get the IDataObject interface for the node. The ATL Wizard in Microsoft® Visual C++® version 6.0 makes this easy for you. The wizard creates the IDataObject member variable for you and assigns its value as shown in the following code fragment:

IDataObject* m_pDataObject;
virtual void InitDataClass(IDataObject* pDataObject,
                           CSnapInItem* pDefault)
{
m_pDataObject = pDataObject;
}

If you do not have access to the ATL Wizard, you must implement the appropriate IExtend and IComponent interface methods for the type of extension snap-in you are creating. The methods pass IDataObject as one of their parameters or as an event parameter in the case of the toolbar extension. After you have IDataObject, you use its QueryInterface method to get the IMmfNode interface (using the IID_IMmfNode parameter). The IMmfNode interface contains the methods for reading, modifying, and deleting named values. Typically, it is not appropriate to modify or delete named values created by another extension — doing so could break those extensions.

If you defined your variable as a "smart" pointer, IMmfNodePtr, you could simply assign the IDataObject pointer to your variable without performing the QueryInterface method. The "smart" pointer performs the QueryInterface, increments the reference, and releases the pointer for you when it goes out-of-scope.

The following code fragment shows you how to get the IWbemClassObject named value for the node. After you have the WMI object pointer, you can use it to call any of the WMI API methods.

IMmfNodePtr          pMmfNode = m_pDataObject
IWbemClassObjectPtr  pClassObject;
BSTR                 bstrText;

pClassObject = pMmfNode->GetNamedValue("IWbemClassObject");
pClassObject->GetObjectText(0, &bstrText);

Persisting Named Value Data

Named values are only available for the lifetime of the node. After the node becomes inactive, the data items are unavailable. The exception is if you set the persist flag when you add a named value. This ensures that the named value is written to the .msc file.

You must set the MMF_PERSIST_VALUE if you want your named value to be saved to the .msc file. If you do not include this flag, your named value is deleted after the node is out-of-scope.

The following code fragment shows you how to use the AddNamedValue method to persist a named value for the node.

// Get IMmfNode from the IDataObject of the node being extended
IMmfNodePtr pMmfNode = pDataObject;

_bstr_t sComment;
_variant_t vComment;

// Get current value of named value called "comment"
vComment = pMmfNode->GetNamedValue("comment");
sComment = vComment;

// Initialize editbox with value extracted from "comment" named value
dlg.m_edit = (LPCSTR)sComment;
if (dlg.DoModal() == IDOK)
{
   // Get new comment
   sComment = dlg.m_edit;

   // Save the new comment into a named vValue called "comment". Set the
   // flags to persist the named value in the .msc file
   pMmfNode->AddNamedValue("comment",
                          _variant_t(_bstr_t(sComment)),
                          MMF_PERSIST_VALUE);
}