Guest

Cisco Remote Monitoring Suite Option

Implementing the WantHelp Interface (Release 4.6)

  • Viewing Options

  • PDF (102.3 KB)
  • Feedback
Implementing the IWantHelp Interface

Table Of Contents

Implementing the IWantHelp Interface

Overview

How to Implement IWantHelp

Interface Definition

Implementing IWantHelp

Sample Implementation

Installation and Setup


Implementing the IWantHelp Interface


Overview

The AlarmTracker Client software contains support for an external COM interface called IWantHelp. If implemented, the IWantHelp interface provides the customer with a hook into building a custom help and guidance system, and integrating it with AlarmTracker. If the component is properly registered, it is accessed from the Event Details dialog as a custom button. When clicked, the AlarmTracker code calls a method in IWantHelp which presents custom help information based on the context of the displayed event.

A standard implementation is building troubleshooting wizards for specific Alarms via a web-based solution. When the custom IWantHelp button is clicked, the IWantHelp::OnHelp method is called along with the AlarmID, Class, MsgID, and MsgText fields of the event. This information is then used to present a troubleshooting wizard on how to fix a particular problem.

How to Implement IWantHelp

Interface Definition

The IWantHelp interface is defined by the following IDL:

// WantHelp.idl : IDL source for IWantHelp.tlb
//

// This file will be processed by the MIDL tool to
// produce the type library (IWantHelp.tlb)

import "oaidl.idl";

[
uuid(BAA31F1A-1E9F-4876-A99F-E9AF2FEEBBA5),
version(1.0),
helpstring("IWantHelp 1.0 Type Library")
]
library IWantHelpLib
{
importlib("stdole2.tlb");

[
object,
uuid(54D8196C-CDF4-406A-9E65-40B97336137D),
dual,
helpstring("IWantHelp Interface"),
pointer_default(unique)
]
interface IWantHelp : IDispatch
{

[id(1), helpstring("Notification that an Active Connection has been established with an LGMapper Server")] HRESULT ActiveConnectionEstablished([in] BSTR strHostName, [in] BSTR strCatalog);

[id(2), helpstring("Notification that an Active Connection with an LGMapper Server has been terminated")] HRESULT ActiveConnectionTerminated();

[id(3), helpstring("Help has been requested by user")] HRESULT OnHelp([in] long nAlarmID, [in] long nClass, [in] long nMsgID, [in] BSTR strMsgText);

[propget, id(4), helpstring("Button text in AlarmTracker Event Detail dialog")] HRESULT ButtonText([out, retval] BSTR *pVal);

[propput, id(4), helpstring("Button text in AlarmTracker Event Detail dialog")] HRESULT ButtonText([in] BSTR newVal);
};

};

This IDL file is named IWantHelp.idl and is included in the bin folder of the LGMapper installation directory along with its corresponding IWantHelp.tlb file.

The following properties and methods are defined.

Property: ButtonText

Type: BSTR

Description: Button text displayed in the AlarmTracker Event detail dialog.

Property: ButtonText

Type: BSTR

Description: Button text displayed in the AlarmTracker Event detail dialog.

Method: ActiveConnectionEstablished

Args:

[in] BSTR strHostName - Name of the machine where the SQL Server Alarms database is running.

[in] BSTR strCatalog - Name of the SQL Server Alarms database.

Description: Notification that an Active Connection has been established with an LGMapper Server. The information in this method can be used if you want to create a connection to the Alarms database that the AlarmTracker is connected to.

Method: ActiveConnectionTerminated

Args: None

Description: Notification that an Active Connection with an LGMapper Server has been terminated.

Method: OnHelp

Args:

[in] long nAlarmID - AlarmID in the Alarms database of the Event being viewed in the Event Details dialog.

[in] long nClass - Class of the Event being viewed in the Event Details dialog.

[in] long nMsgID - EMS Message ID of the Event being viewed in the Event Details dialog.

[in] BSTR strMsgText - Message text of the Event being viewed in the Event Details dialog.

Description: Help has been requested by the user. You can implement this method to use the arguments to present custom context-dependent help information.

Implementing IWantHelp

Implement the IWantHelp interface using any programming language that supports COM (e.g., C++, Visual Basic, Java). The interface should be implemented as an in-proc COM server.

Once built, the DLL must be copied to all AlarmTracker client machines and registered. More details on this can be found in Installation and Setup.

Sample Implementation

A sample implementation of the IWantHelp interface is included in the HelpSample directory of the LGMapper installation directory. This is an C++ ATL implementation which simply displays the Microsoft home page in a browser window in a separate process.

Installation and Setup

Once you implement your custom implementation, it can be deployed to AlarmTracker Client systems. Three things need to be done in order for the implementation to be integrated with AlarmTracker:

The DLL must be copied to each AlarmTracker Client machine.

The location is not important since it is a COM DLL and the registry contains the right information on how to load it.

The DLL must be properly registered on each AlarmTracker Client machine.

This is done by running RegSvr32 with the full path name of the DLL as an argument.

You must add the following registry key to each AlarmTracker Client's machine:

HKEY_LOCAL_MACHINE\SOFTWARE\CiscoSystems\AlarmTracker\ProgIDs

and add the string (REG_SZ) value IWantHelp.

The value of IWantHelp should be the ProgID of the IWantHelp implementation, e.g., "HelpSample5.WantHelp".

When AlarmTracker starts, it looks for this registry value, and, if it exists, the DLL is loaded and used.