sipxportlib  Version 3.3
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Plugin Class Referenceabstract

#include <Plugin.h>

Collaboration diagram for Plugin:
Collaboration graph
[legend]

Public Types

typedef Plugin *(* Factory) (const UtlString &pluginName)
 

Public Member Functions

virtual ~Plugin ()
 The plugin destructor must be virtual. More...
 
virtual void readConfig (OsConfigDb &configDb)=0
 Read (or re-read) whatever configuration the plugin requires. More...
 

Protected Member Functions

 Plugin (const UtlString &instanceName)
 Derived constructors should be private so that only the Factory can call them. More...
 

Protected Attributes

UtlString mInstanceName
 The instance name from the configuration directive - for logging and other identification. More...
 

Detailed Description

A Plugin is a dynamically loaded object that is invoked by some component at some well defined time (it's an abstract class - how specific can the description be?).

This class is the abstract base from which all plugins must inherit; it decouples the configuration of what plugins should be invoked and the configuration parameters specific to each plugin from the program that uses them.

The following UML shows the relationships between the classes used to implement a plugin interface.

To define a plugin interface, a component creates a class derived from Plugin. This defines the interface(s) specific to the plugin; for example, in RegisterPlugin it defines a takeAction interface that allows each plugin to take some action when a REGISTER request is accepted.

The PluginHooks class is instantiated and its readConfig interface called by a the component to actually read what plugins have been configured for each class it defines that is derived from Plugin.

To actually invoke each configured plugin, the component instantiates a PluginIterator object on the PluginHooks object it configured, and then invokes the action interface using each Plugin object that it returns.

All Plugin classes must implement three methods to configure the plugin into the component:

Each class derived from Plugin should also define the method(s) that the program should invoke on the plugin, and all those methods must be virtual.

See also
PluginHooks for details of how a plugin is configured into a program, and PluginIterator for how plugins are invoked by the calling component.

Member Typedef Documentation

typedef Plugin*(* Factory) (const UtlString &pluginName)

The Factory uses external C linkage to support dynamic loading of Plugin objects.

In addition to the class derived from this base, a plugin must implement a Factory routine with extern "C" linkage so that the OsSharedLib mechanism can look it up in the dynamically loaded library (looking up C++ symbols is problematic because of name mangling). The Factory routine looks like:

class ExamplePlugin;
extern "C" ExamplePlugin* getExamplePlugin(const UtlString& name)
{
return new ExamplePlugin;
}
class ExamplePlugin : public Plugin
{
friend ExamplePlugin* getExamplePlugin(const UtlString& name);
...
private:
ExamplePlugin(const UtlString& name);
}

Constructor & Destructor Documentation

virtual ~Plugin ( )
inlinevirtual

The plugin destructor must be virtual.

Plugin ( const UtlString instanceName)
inlineprotected

Derived constructors should be private so that only the Factory can call them.

Member Function Documentation

virtual void readConfig ( OsConfigDb configDb)
pure virtual

Read (or re-read) whatever configuration the plugin requires.

Note
The parent service may call the readConfig method at any time to indicate that the configuration may have changed. The plugin should reinitialize itself based on the configuration that exists when this is called. The fact that it is a subhash means that whatever prefix is used to identify the plugin (see PluginHooks) has been removed (see the examples in PluginHooks::readConfig).
Parameters
configDba subhash of the individual configuration parameters for this instance of this plugin.

Member Data Documentation

UtlString mInstanceName
protected

The instance name from the configuration directive - for logging and other identification.