sipxportlib  Version 3.3
Public Member Functions | Protected Attributes | Friends | List of all members
PluginHooks Class Reference

#include <PluginHooks.h>

Collaboration diagram for PluginHooks:
Collaboration graph
[legend]

Public Member Functions

 PluginHooks (const char *hookFactoryName, const char *hookPrefix)
 Construct a manager for a set of hooks. More...
 
 ~PluginHooks ()
 
void readConfig (OsConfigDb &configDb)
 Read what hooks are configured, and instantiate and configure each hook. More...
 
size_t entries () const
 Return the total number of plugins within. More...
 

Protected Attributes

UtlString mFactory
 The factory routine name for this hook class. More...
 
UtlString mPrefix
 The prefix name for the OsConfigDb values. More...
 
UtlSortedList mConfiguredHooks
 The list of configured hooks. More...
 

Friends

class PluginIterator
 

Detailed Description

A PluginHooks object is used to add dynamically loaded libraries (a "plugin") to a program at run time. The module to be loaded must implement a class derived from the Plugin abstract class.

An object of this class manages all the configured plugin hooks for a program. A class of plugin hooks is identified by a factory routine name used to obtain a hook instance from the dynamic library, and an OsConfigDb prefix string:

// to be called for each Action
PluginHooks ActionEventHooks("getFooAction", "ACTION_EVENT");

The libraries are loaded and configured by the readConfig method:

ActionEventHooks.readConfig(configDb);

To invoke the plugins, see PluginIterator.

Constructor & Destructor Documentation

PluginHooks ( const char *  hookFactoryName,
const char *  hookPrefix 
)

Construct a manager for a set of hooks.

Parameters
hookFactoryNameThe factory routine name for this hook class.
hookPrefixThe prefix name for the OsConfigDb values.

Member Function Documentation

void readConfig ( OsConfigDb configDb)

Read what hooks are configured, and instantiate and configure each hook.

This method actually reads the program configuration from the configDb passed in. Each entry that has the prefix followed by "_HOOK_LIBRARY" configures a plugin library.

[prefix]_HOOK_LIBRARY.[instance] : [path to libexamplereghook.so]

For the example code above, it would look for entries like:

ACTION_EVENT_HOOK_LIBRARY.RecordAction : /usr/local/lib/sipxpbx/librecordaction.so
ACTION_EVENT_HOOK_LIBRARY.CopyAction : /usr/local/lib/sipxpbx/libcopyaction.so

The readConfig method:

  • dynamically loads each library
  • for each value of [instance]
    • calls the factory method provided by the hook to instantiate a hook object, passing its instance name to it (so that it can be used in logging).
    • passes the new hook object a configuration subhash of its configuration entries (if any).

Configuration entries for each hook instance are made with entries like:

[prefix].[instance].FOO : foovalue
[prefix].[instance].BAR : barvalue

Each instance has its own set of configuration entries:

ACTION_EVENT.RecordAction.FOO : foovalue1
ACTION_EVENT.RecordAction.BAR : barvalue1
ACTION_EVENT.CopyAction.FOO : foovalue2
ACTION_EVENT.CopyAction.BAR : barvalue2

The readConfig method in the hook (which must inherit from Plugin) is passed its own subhash of the configuration data, stripping everything through the '.' following the instance name, so in the example above, the CopyAction hook would be passed the equivalent of this configuration:

FOO : foovalue2
BAR : barvalue2

readConfig can be called more than once.

  • New plugin instances are instantiated as described above.
  • Existing plugin instances that are no longer in the configuration are deleted (their destructor is invoked).
  • Existing plugin instances that are still in the configuration are reconfigured (their Plugin::readConfig method is called).
size_t entries ( ) const

Return the total number of plugins within.

Friends And Related Function Documentation

friend class PluginIterator
friend

Member Data Documentation

UtlString mFactory
protected

The factory routine name for this hook class.

UtlString mPrefix
protected

The prefix name for the OsConfigDb values.

UtlSortedList mConfiguredHooks
protected

The list of configured hooks.