tlp::Plugin Class Reference

#include <telPlugin.h>

Inheritance diagram for tlp::Plugin:

Public Member Functions
	Plugin (const string &name=gEmptyString, const string &cat=gNoneString, RoadRunner *aRR=NULL, const string &language=gNoneString, const PluginManager *pm=NULL)
virtual	~Plugin ()
string	getName ()
string	getLibraryName ()
string	getAuthor ()
string	getCategory ()
string	getDescription ()
string	getHint ()
string	getVersion ()
string	getCopyright ()
RoadRunner *	getRoadRunnerInstance ()
virtual string	getInfo ()
virtual string	getExtendedInfo ()
virtual unsigned char *	getManualAsPDF () const
virtual unsigned int	getPDFManualByteSize ()
virtual Properties *	getProperties ()
virtual tlp::StringList	getPropertyNames ()
string	getPluginPropertiesAsXML ()
virtual PropertyBase *	getProperty (const string &param)
string	getPropertyValueAsString (const string &param)
void *	getPropertyValueHandle (const string &param)
void	setPropertyByString (const string &nameOf, const char *value)
void	setPropertyValue (const string &nameOf, const void *value)
void	terminate ()
bool	isBeingTerminated () const
bool	wasTerminated () const
	check if the plugin was terminated
virtual bool	isWorking () const
	check if the plugin is working
virtual bool	assignRoadRunnerInstance (RoadRunner *rr)
	Assign a roadrunner instance for the plugin to use.
virtual bool	assignOnStartedEvent (PluginEvent pluginStarted, void *userData1=NULL, void *userData2=NULL)
virtual bool	assignOnProgressEvent (PluginEvent pluginsProgress, void *userData1=NULL, void *userData2=NULL)
virtual bool	assignOnFinishedEvent (PluginEvent pluginsFinished, void *userData1=NULL, void *userData2=NULL)
virtual string	getResult ()
virtual bool	resetPlugin ()
virtual string	getStatus ()
virtual string	getImplementationLanguage ()=0
bool	hasStartedEvent () const
bool	hasProgressEvent () const
bool	hasFinishedEvent () const
void	WorkStartedEvent (void *data1, void *data2)
void	WorkProgressEvent (void *data1, void *data2)
void	WorkFinishedEvent (void *data1, void *data2)
pair< void *, void * >	getWorkStartedData ()
pair< void *, void * >	getWorkProgressData ()
pair< void *, void * >	getWorkFinishedData ()
virtual bool	execute (bool inAThread=false)=0
const PluginManager *	getPluginManager ()

Protected Member Functions
void	setLibraryName (const string &libName)

Protected Attributes
string	mName
	Name of Plugin.
string	mLibraryName
	Name of compiled shared library implementing the Plugin.
string	mAuthor
	Name of plugin author(s)
string	mCategory
	Plugin category.
string	mDescription
	Plugin description.
string	mHint
	Plugin Hint.
string	mVersion
	Plugin version.
string	mCopyright
	Plugin copyright language.
string	mImplementationLanguage
	Plugin implementation language.
bool	mTerminate
	Boolean flag indicating if a user wants to terminate the work in a plugin.
bool	mIsWorking
	Boolean flag indicating if the plugin is working.
RoadRunner *	mRR
const PluginManager *	mPM
PluginEvent	mWorkStartedEvent
PluginEvent	mWorkProgressEvent
PluginEvent	mWorkFinishedEvent
void *	mWorkStartedData1
void *	mWorkStartedData2
void *	mWorkProgressData1
void *	mWorkProgressData2
void *	mWorkFinishedData1
void *	mWorkFinishedData2
Properties	mProperties

Detailed Description

The Plugin class is a base class for all RoadRunner plugins. A Plugin is implemented in a shared library, e.g. a DLL on Windows, and loaded at runtime by a PluginManager. Any RoadRunner Plugin need to inherit from the Plugin class or any of its descendants. Here are the main characteristics of a Plugin:

1. The Plugin class do contain the bulk of how a Plugin is handled by the Plugin manager and any clients of the plugin, while the atcual custom functionality is implmemented in a descendant Plugin.
2. A plugin may belong to a category and is identified by a name. It has properties like Author, Version, Copyright etc.
3. A Plugin typically expose various Properties, available to a client of a plugin trough the Properties conatiner.
4. The internal work a plugin is designed to do may be executed in a separate thread, and various functions to monitor and manage the work of a Plugin is exposed, e.g. isWorking(), terminate(), isBeingTerminated() etc.
5. A Plugin may implement various event functions in order to communicate data or progress to a client. The Plugin class exposes three events, PluginStarted, PluginProgress and a PluginFinish event. Each event may communicate two opaque data parameters. Its up to the plugin implementor to make use of these events and what data to pass.
6. A plugin have access to other plugins through the PluginManager. Thus, a plugin may depend on other plugins.
7. A plugin may embed documentation in various forms, e.g. PDF (getPDFManual(), or simple text getExtendedInfo().

Constructor & Destructor Documentation

tlp::Plugin::Plugin	(	const string &	name = gEmptyString,
		const string &	cat = gNoneString,
		RoadRunner *	aRR = NULL,
		const string &	language = gNoneString,
		const PluginManager *	pm = NULL
	)

Create a plugin

tlp::Plugin::~Plugin ( )

virtual

Destroy the plugin.

Member Function Documentation

bool tlp::Plugin::assignOnFinishedEvent ( PluginEvent  pluginsFinished, void *  userData1 = NULL, void *  userData2 = NULL  )

virtual

Assign function pointer and data the event

bool tlp::Plugin::assignOnProgressEvent ( PluginEvent  pluginsProgress, void *  userData1 = NULL, void *  userData2 = NULL  )

virtual

Assign function pointer and data the event

bool tlp::Plugin::assignOnStartedEvent ( PluginEvent  pluginStarted, void *  userData1 = NULL, void *  userData2 = NULL  )

virtual

Assign function pointer and data the event

virtual bool tlp::Plugin::execute ( bool  inAThread = false)

pure virtual

Execute the plugin

Implemented in tlp::CPlugin.

string tlp::Plugin::getAuthor

(

)

Get the name of plugin author(s)

string tlp::Plugin::getCategory

(

)

Get plugin category

string tlp::Plugin::getCopyright

(

)

Get plugin copyright text

string tlp::Plugin::getDescription

(

)

Get plugin description

string tlp::Plugin::getExtendedInfo ( )

virtual

Retrieve more information than getInfo()

string tlp::Plugin::getHint

(

)

Get plugin Hint

virtual string tlp::Plugin::getImplementationLanguage ( )

pure virtual

Retrieve the implementation language of the plugin.

Implemented in tlp::CPlugin, and tlp::CPPPlugin.

string tlp::Plugin::getInfo ( )

virtual

Retrieves various plugin information

string tlp::Plugin::getLibraryName

(

)

Get the name of the compiled shared library that implemements the plugin.

unsigned char * tlp::Plugin::getManualAsPDF ( ) const

virtual

Retrieve a plugins documentation embedded as PDF. May be NULL

string tlp::Plugin::getName

(

)

Get the name of the plugin.

unsigned int tlp::Plugin::getPDFManualByteSize ( )

virtual

Retrieve the size in bytes of the PDF string.

const PluginManager * tlp::Plugin::getPluginManager

(

)

Get a pointer to the plugins manager

string tlp::Plugin::getPluginPropertiesAsXML

(

)

Retieves a plugin properties, as XML

Properties * tlp::Plugin::getProperties ( )

virtual

Retieves the propertys

PropertyBase * tlp::Plugin::getProperty ( const string &  param)

virtual

Retieves a specific property

Reimplemented in tlp::CPlugin.

tlp::StringList tlp::Plugin::getPropertyNames ( )

virtual

Retieves the names of the propertys

Reimplemented in tlp::CPlugin.

string tlp::Plugin::getPropertyValueAsString

(

const string &

param)

Return a property value as a string

void * tlp::Plugin::getPropertyValueHandle

(

const string &

param)

Return a handle to a properties value

string tlp::Plugin::getResult ( )

virtual

Function returnin a plugins "result", as a string

RoadRunner * tlp::Plugin::getRoadRunnerInstance

(

)

Retrieves the RoadRunner instance the plugin is using. Can be NULL.

string tlp::Plugin::getStatus ( )

virtual

Retrieve the status of the plugin.

string tlp::Plugin::getVersion

(

)

Get plugin version information

pair< void *, void * > tlp::Plugin::getWorkFinishedData

(

)

get WorkFinished event data variables

pair< void *, void * > tlp::Plugin::getWorkProgressData

(

)

get WorkProgress event data variables

pair< void *, void * > tlp::Plugin::getWorkStartedData

(

)

get WorkStarted event data variables

bool tlp::Plugin::hasFinishedEvent

(

)

const

Check if the plugin as an assigned WorkerFinishedEvent

bool tlp::Plugin::hasProgressEvent

(

)

const

Check if the plugin as an assigned WorkerProgressEvent

bool tlp::Plugin::hasStartedEvent

(

)

const

Check if the plugin as an assigned WorkerStartedEvent

bool tlp::Plugin::isBeingTerminated

(

)

const

Check if the plugin worker is in the process of being terminated

bool tlp::Plugin::resetPlugin ( )

virtual

Reset the plugin.

void tlp::Plugin::setLibraryName ( const string &  libName)

protected

Set the name of the shared library

void tlp::Plugin::setPropertyByString	(	const string &	nameOf,
		const char *	value
	)

Sets the value of specified Property with value as specified

void tlp::Plugin::setPropertyValue	(	const string &	nameOf,
		const void *	value
	)

Sets the value of specified Property with value as specified

void tlp::Plugin::terminate

(

)

If the work of the plugin is carried out in a separate thread, terminate() will signal termination of such work.

void tlp::Plugin::WorkFinishedEvent	(	void *	data1,
		void *	data2
	)

Call WorkFinished event function

void tlp::Plugin::WorkProgressEvent	(	void *	data1,
		void *	data2
	)

Call WorkProgress event function

void tlp::Plugin::WorkStartedEvent	(	void *	data1,
		void *	data2
	)

Call WorkStarted event function

Member Data Documentation

const PluginManager* tlp::Plugin::mPM

protected

A pointer to the PluginManager that loaded the Plugin uses.

Properties tlp::Plugin::mProperties

protected

Properties container. Descendant add properties to this container, as they wish. Property data values can be exchanged to/from the plugin by accessing individual properties.

RoadRunner* tlp::Plugin::mRR

protected

A pointer to a RoadRunner instance which the plugin uses.

void* tlp::Plugin::mWorkFinishedData1

protected

Opaque data parameter 1 passed in the WorkFinished event function

void* tlp::Plugin::mWorkFinishedData2

protected

Opaque data parameter 2 passed in the WorkFinished event function

PluginEvent tlp::Plugin::mWorkFinishedEvent

protected

WorkFinished event function pointer

void* tlp::Plugin::mWorkProgressData1

protected

Opaque data parameter 1 passed in the WorkProgress event function

void* tlp::Plugin::mWorkProgressData2

protected

Opaque data parameter 2 passed in the WorkProgress event function

PluginEvent tlp::Plugin::mWorkProgressEvent

protected

Work In progress event function pointer

void* tlp::Plugin::mWorkStartedData1

protected

Opaque data parameter 1 passed in the WorkStarted event function

void* tlp::Plugin::mWorkStartedData2

protected

Opaque data parameter 2 passed in the WorkStarted event function

PluginEvent tlp::Plugin::mWorkStartedEvent

protected

WorkStarted event function pointer

---

The documentation for this class was generated from the following files:

• core/telPlugin.h
• core/telPlugin.cpp