#include <plugins.h>

Public Types
enum	ErrorCode { AlreadyLoaded, LibraryError, InvalidFile, CantGetFiles, LibraryInUse, EraseFailed, InvalidPlugin }

typedef void (	PluginCreator )(void)

Public Member Functions
	Plugins (void)

	~Plugins (void)

Static Public Member Functions
static int	open (const string &file)

static int	open (int id)

static int	openPath (const string &path, const string &relativepath, const StrQueue &pluginhomes)

static int	openFile (const string &file)

static int	close (int id)

static int	close (const string &file)

static int	close (void)

static int	erase (int id)

static int	erase (const string &file)

static int	clear (void)

static int	reopen (int id)

static int	reopen (const string &file)

static int	size (void)

static bool	empty (void)

static int	plugins (void)

static int	plugins (int type)

static string	ident (int index)

static string	first (int type=0)

static int	index (const string &plugin, int type=-1)

static int	type (int index)

static int	type (const string &plugin)

static int	fileID (int index)

static int	fileID (const string &plugin)

static void *	create (int index)

static void *	create (const string &plugin, int type)

static int	destroy (int index)

static int	destroy (const string &plugin, int type)

static void	add (const string &ident, int type, PluginCreator create, const string &version)

static void	erase (const string &ident, int type)

static const string &	libraryErrors (void)

static void	clearLibraryErrors (void)

static const string &	classErrors (void)

static void	clearClassErrors (void)

Friends
ostream &	operator<< (ostream &str, const Plugins &plugins)

Detailed Description

Dynamically load plugins (libraries) into the running program.

Author: Jan Benda

Plugins has a file list with all library files that are opened and a plugins list containing the plugins (a library can contain more than one plugin).

With the open(), openPath(), and OpenFile() functions you can add files to the file list and load the libraries into the program. The plugins in the library automatically add themselves to the plugins list. The close() functions remove the libraries from the program but keep the filenames in the list. The plugins of a closed library are removed from the plugins list. To close the libraries and remove them from the file list use the erase() functions. The clear() function tries to erase all libraries. With reopen() a library can be first closed and than opened again. The number of library files in the list is returned by size(), the list can alos be empty().

Each plugin has an identifier string ident(), an index(), a type(), and is contained by the library file with file id fileID(). The type() of a plugin is used to group plugins of different type together, i.e. classes with the same base class. The identifier string of the first plugin in the list with a given type is returned by first(). The number of loaded plugins is plugins().

An instance of a plugin is created by create() and destroyed by destroy().

Errors concerning the library files are retuned by libraryErrors(). Errors concerning the plugin classes are retuned by classErrors().

In order to make a class a plugin that is managed by Plugins addPlugin() must be "called", i.e. it must be added to the end of the source file. A class can be added to or removed from the plugins explicitely by calling add() and erase(const string&,const string&,int), respectively.

Member Typedef Documentation

typedef void*(* PluginCreator)(void)

Returns: a pointer to a new instance of the plugin.

Member Enumeration Documentation

enum ErrorCode

Error codes for handling plugins.

Enumerator
AlreadyLoaded	The library is already loaded.
LibraryError	Error in loading the library.
InvalidFile	The requested file does not exist.
CantGetFiles	Can't read files of a directory or from file.
LibraryInUse	Some plugins of the library are still in use.
EraseFailed	The requested plugin does not exist.
InvalidPlugin	The file cannot be erased from the list.

Constructor & Destructor Documentation

Plugins ( void )

Constructor. Does nothing.

Note: You should never construct a Plugins class. Plugins construct themselfes when their library file is opened.

~Plugins ( void )

Destructor. Does nothing.

Member Function Documentation

int open ( const string & file )

static

Load the library with file name file into the program if it is not already loaded (it may, however, be already in the list of library files).

Parameters

[in] file the file name of the library to be loaded.

Returns: the id of the library on success. If the library is already loaded, -AlreadyLoaded is returned. If the library cannot be loaded, -LibraryError is returned and a string explaining the reason is added to the library errors which can be read using libraryErrors().

See Also: openPath(), openFile(), close(), erase(), clear(), reopen()

int open ( int id )

static

Load the library with id id into the program if it is not already loaded.

Parameters

[in] id the identification number of the library to be loaded.

Returns: the id of the library on success. If id is invalid, -InvalidFile is returned. If the library is already loaded, -AlreadyLoaded is returned. If the library cannot be loaded, -LibraryError is returned and a string explaining the reason is added to the library errors which can be read using libraryErrors().

See Also: openPath(), openFile(), close(), erase(), clear(), reopen()

int openPath	(	const string &	path,
		const string &	relativepath,
		const StrQueue &	pluginhomes
	)

static

Load all libraries specified by the path path into the program. Relative pathes (not starting with a slash) are interpreted relative to relativepath, provided relativepath is not empty. If path is a pure filename (no directory, but may contain wildcards) then it is assumed to be found in one of the pluginhomes directories. If pluginhomes is an empty string, then pure filenames are also interpreted relative to relativepath, provided relativepath is not empty.

Parameters

[in]	path	the file pattern (can include wildcard characters) selecting the libraries to be loaded. If path ends with a slash, "" is added first. If path* has no file extension, the appropriate extension (".so") is added. If the filename of path does not start with "lib", the filename is prefixed with "lib".
[in]	relativepath	the path to be used for relative pathes.
[in]	pluginhomes	default pathes for the plugin files.

Returns: the number of the successfully loaded libraries.

See Also: open(), openFile(), close(), erase(), clear(), reopen()

References Str::dir(), Str::empty(), StrQueue::empty(), Str::extension(), Str::find(), Str::notdir(), Str::providePeriod(), Str::size(), StrQueue::size(), and Str::strip().

Referenced by RELACSWidget::RELACSWidget().

int openFile ( const string & file )

static

Load all libraries listed in the file file into the program.

Parameters

[in] file the name of a text file that contains in each line the file name of a library that is to be loaded.

Returns: the number of the successfully loaded libraries. If file is invalid, -CantGetFiles is returned.

See Also: open(), openPath(), close(), erase(), clear(), reopen()

int close ( int id )

static

Close library specified by its id id. The library is not removed from the list. You can open the library again with the open() functions. Use erase() to close the library and remove it from the list.

Parameters

[in] id the identification number of the library to be closed.

Returns: the id of the library on success. If id is invalid, -InvalidFile is returned. If still some plugins of the libraries are used, -LibraryInUse is returned.

See Also: open(), openPath(), openFile(), erase(), clear(), reopen()

int close ( const string & file )

static

Close library specified by its file name file. The library is not removed from the list. You can open the library again with the open() functions. Use erase() to close the library and remove it from the list.

Parameters

[in] file the file name of the library to be closed.

Returns: the id of the library on success. If file is not found in the list of opened libraries, -InvalidFile is returned. If still some plugins of the libraries are used, -LibraryInUse is returned.

See Also: open(), openPath(), openFile(), erase(), clear(), reopen()

int close ( void )

static

Close all libraries. The libraries are not removed from the list. You can open the libraries again with the open() functions. Use clear() to close the libraries and remove them from the list.

Returns: 0 if all libraries were closed successfully. If some libraries cannot be closed, since some plugins are still used, the negative of the number of these libraries is returned.

See Also: open(), openPath(), openFile(), erase(), clear(), reopen()

Referenced by RELACSWidget::~RELACSWidget().

int erase ( int id )

static

Close library specified by its id id and remove it form the list.

Parameters

[in] id the identification number of the library to be erased.

Returns: the id of the library on success. If id is invalid, -InvalidFile is returned. If still some plugins of the libraries are used, -LibraryInUse is returned.

See Also: open(), openPath(), openFile(), close(), clear(), reopen()

int erase ( const string & file )

static

Close library specified by its file name file and remove it form the list.

Parameters

[in] file the file name of the library to be erased.

Returns: the id of the library on success. If file is not found in the list of opened libraries, -InvalidFile is returned. If still some plugins of the libraries are used, -LibraryInUse is returned.

See Also: open(), openPath(), openFile(), close(), clear(), reopen()

int clear ( void )

static

Close all libraries and remove them from the list.

Returns: 0 if all libraries were closed successfully. If some libraries cannot be closed and removed, since some plugins are still used, the negative of the number of these libraries is returned.

See Also: open(), openPath(), openFile(), close(), erase(), reopen()

int reopen ( int id )

static

Load the library with id id into the program after closing it.

Parameters

[in] id the identification number of the library to be reopened.

Returns: the id of the library.

See Also: open(), openPath(), openFile(), close(), erase(), clear()

Referenced by ReProData::reload().

int reopen ( const string & file )

static

Load the library with file name file into the program after closing it.

Parameters

[in] file the file name of the library to be reopened.

Returns: the id of the library.

See Also: open(), openPath(), openFile(), close(), erase(), clear()

int size ( void )

static

Returns: the number of libraries in the list.

See Also: empty(), open(), erase()

bool empty ( void )

static

Returns: true if no libraries are contained in the list.

See Also: size(), open(), erase()

Referenced by RELACSWidget::RELACSWidget().

int plugins ( void )

static

Returns: the number of plugins in the plugins list.

Referenced by RePros::RePros().

int plugins ( int type )

static

Returns: the number of plugins in the plugins list of type type.

Parameters

[in] type the type of the plugins.

string ident ( int index )

static

Returns: the identfier string of the plugin specified by its index index.

Parameters

[in] index the index of the plugin.

See Also: first(), index()

Referenced by RePros::RePros().

string first ( int type = 0 )

static

Returns: the identifier string of the first plugin which is of type type.

Parameters

[in] type the type of the plugin.

See Also: ident(), index()

int index	(	const string &	plugin,
		int	type = `-1`
	)

static

Returns: the index of a plugin which is specified by its identifier string plugin and its type type. -InvalidPlugin is returned if the plugin was not found.

Parameters

[in]	plugin	the name of the plugin.
[in]	type	the type of the plugins. If negative, the type is not used to identify the plugin.

See Also: ident()

Referenced by DeviceList< T, PluginID >::create().

int type ( int index )

static

Returns: the type of the plugin specified by its index index.

Parameters

[in] index the index of the plugin.

See Also: ident(), fileID()

Referenced by RePros::RePros().

int type ( const string & plugin )

static

Returns: the type of the plugin specified by its identifier string plugin.

Parameters

[in] plugin the name of the plugin.

See Also: index(), fileID()

int fileID ( int index )

static

Returns: the file id of the library which contains the plugin specified by its index index.

Parameters

[in] index the index of the plugin.

See Also: ident(), type()

Referenced by ReProData::reload().

int fileID ( const string & plugin )

static

Returns: the file id of the library which contains the plugin specified by its identifier string plugin.

Parameters

[in] plugin the name of the plugin.

See Also: index(), type()

void * create ( int index )

static

Constructs a new instance of the plugin specified by its index index.

Returns: a pointer to that plugin.

Parameters

[in] index the index of the plugin to be created.

See Also: destroy(), plugins()

Referenced by DeviceList< T, PluginID >::create(), ControlTabs::createControls(), FilterDetectors::createFilters(), RELACSWidget::RELACSWidget(), ReProData::reload(), and RePros::RePros().

void * create	(	const string &	plugin,
		int	type
	)

static

Constructs a new instance of the plugin specified by its identifier string plugin and its type type.

Returns: a pointer to the new instance of the plugin.

Parameters

[in]	plugin	the name of the plugin to be created.
[in]	type	the type of the plugin.

See Also: destroy(), plugins()

int destroy ( int index )

static

If you delete a plugin which has been created by one of the create functions, call this function to decrement its use count.

Note: the plugin is not removed from the list of plugins.

Returns: the number of still existing instances of the specified plugin.

Parameters

[in] index the index of the plugin to be destroyed.

See Also: create(), plugins()

Referenced by AllDevices::clear(), FilterDetectors::clear(), FilterDetectors::createFilters(), ReProData::reload(), ControlTabs::~ControlTabs(), RELACSWidget::~RELACSWidget(), and RePros::~RePros().

int destroy	(	const string &	plugin,
		int	type
	)

static

If you delete a plugin which has been created by one of the create functions, call this function to decrement its use count.

Note: the plugin is not removed from the list of plugins.

Returns: the number of still existing instances of the specified plugin.

Parameters

[in]	plugin	the identifier string of the plugin to be destroyed.
[in]	type	the type of the plugin

See Also: create(), plugins()

void add	(	const string &	ident,
		int	type,
		PluginCreator	create,
		const string &	version
	)

static

Add a plugin with identifier string ident and plugin type type to the plugin list. The plugin can be created by calling create(). The plugin was compiled with version number version. If the version number does not match the one of the Plugins class, an error string is appened to the class errors which can be read using classErrors().

Referenced by RELACSWidget::RELACSWidget().