Share via

DWMSNamedValuesEvents::OnValueChanged

  • Article

banner art

Previous Next

DWMSNamedValuesEvents::OnValueChanged

You can implement the OnValueChanged method to handle event notices raised by the server when a property on your plug-in is added, removed, or modified.

Syntax

  void OnValueChanged();

Parameters

This method has no parameters.

Return Values

This method does not return a value

Remarks

You must implement the OnValueChanged method in your plug-in. This method handles event notices raised by the server when your plug-in calls any of the following methods:

You typically initialize plug-in properties when you register a plug-in, but you can add, remove, or modify them after they are initialized. Common properties include copyright information, the name of the author, descriptive text about the plug-in, property page monikers, and more. For more information, see Registering Plug-in Properties.

The OnValueChanged method cannot handle changes to properties made by using the server object model outside of your plug-in. The event sink can only handle changes made by your plug-in.

Example Code

To create an event sink, you must define a class that implements the OnValueChanged method. This example defines the CEventSink class and uses the IDispEventImpl interface from the Active Template Library (ATL) to simplify implementation.

#include "stdafx.h"
#include "wmsserver.h"

#define EVENT_ID       1000    // Arbitrary ID of the source object.
#define LIB_VERMAJOR   9       // Major version of the type library.
#define LIB_VERMINOR   0       // Minor version of the type library.
#define DISPID         1       // Dispid of the OnValueChanged method.

// Declare the CEventSink class.
class CEventSink : public IDispEventImpl<EVENT_ID,
                                         CEventSink,
                                         &DIID_DWMSNamedValuesEvents,
                                         &LIBID_WMSServerLib,
                                         LIB_VERMAJOR,
                                         LIB_VERMINOR>
{
  public:

  // Declare an ATL_FUNC_INFO structure. The structure is used to
  // describe the OnValuChanged method on the DWMSNamedValuesEvents
  // dispinterface.
  static _ATL_FUNC_INFO ValueInfo;

  // Define the event sink map used by the IDispEventImpl template to
  // route event notices to the appropriate handler function.
  BEGIN_SINK_MAP(CEventSink)
    SINK_ENTRY_EX(EVENT_ID, DIID_DWMSNamedValuesEvents, DISPID, OnValueChanged)
  END_SINK_MAP()

  // Declare the OnValueChanged method.
  HRESULT OnValueChanged();

};

// Define the _ATL_FUNC_INFO structure.
_ATL_FUNC_INFO CEventSink::ValueInfo = {CC_STDCALL, VT_ERROR, 0, 0, 0, 0, 0, 0, 0, 0, 0 };

// Implement the OnValueChanged method.
HRESULT CEventSink::OnValueChanged()
{

    // TODO: Handle the event notice raised when a plug-in
    // property is added, removed, or modified.

}

It is recommended that you create the event sink object in the InitializePlugin method and establish a connection between the event sink and the server in the EnablePlugin method as illustrated by the following example. The InitializePlugin and the EnablePlugin methods are on the IWMSBasicPlugin interface.

STDMETHODIMP CSamplePlugin::InitializePlugin
(
    IWMSContext *pServerContext, 
    IWMSNamedValues *pNamedValues,
    IWMSClassObject *pClassFactory
)
{
    HRESULT hr = S_OK;
    if ( ( NULL == pServerContext )
        || ( NULL == pNamedValues )
        || ( NULL == pClassFactory ) )
    {
        return( E_INVALIDARG );
    }

    // Create the event sink.
    pSink = new CEventSink;

    // Save a pointer to the IWMSNamedValues interface
    // locally. You can use the IWMSNamedValues collection
    // and the IWMSNamedValue interface to add, remove, or
    // modify plug-in properties.
    m_pNamedValues = pNamedValues;
    m_pNamedValues->AddRef();

    return( hr );
}

STDMETHODIMP CSmapletPlugin::EnablePlugin( long *pdwFlags, 
                                           long *pdwHeartbeatPeriod )
{
    HRESULT hr = S_OK;
    if ( ( NULL == pdwFlags ) || ( NULL == pdwHeartbeatPeriod ) )
    {
        return ( E_POINTER );
    }

    // Set the heartbeat period in milliseconds.
    *pdwHeartbeatPeriod = 5000;

    // Use the IDispEventImpl::DispEventAdvise method to
    // establish a connection between the event sink and
    // the server.
    hr = pSink->DispEventAdvise(m_pNamedValues);

    return ( S_OK );
}

Your plug-in can use code similar to the following to retrieve and modify a plug-in property.

// Retrieve the default name-value pair identifying the 
// copyright of the plug-in.
CComVariant varIndex = "Copyright";
hr = m_pNamedValues->get_Item(varIndex, &pNamedValue);

// Retrieve the value associated with this pair.
hr = pNamedValue->get_Value(&varValue);

// Update the copyright value.
varValue.bstrVal = L"New CopyRight";
m_pNamedValues->put_Item(varIndex,varValue);

Requirements

Header: Include wmsbasicplugin.h, wmsserver.h.

Library: WMSServerTypeLib.dll.

Platform: Windows Server 2003, Enterprise Edition; Windows Server 2003, Datacenter Edition; Windows Server 2008.

See Also

Previous Next