Emergency 2017 Dokumentation  v3.0.1
qsf::PluginSystem Class Reference

Plugin system class. More...

#include <PluginSystem.h>

Public Member Functions

 PluginSystem ()
 Default constructor. More...
 
virtual ~PluginSystem ()
 Destructor. More...
 
const std::vector< Plugin * > & getPlugins () const
 Return the list of currently loaded plugins. More...
 
void addPlugin (Plugin &plugin)
 Add a plugin. More...
 
bool loadPlugin (const std::string &pluginName, const std::string &filename)
 Load a plugin. More...
 
void unloadAllPlugins ()
 Unload all plugins. More...
 
void addPluginSearchDirectory (const std::string &path)
 Add a search directory to look for plugin dependencies. More...
 
std::string getSharedLibraryFilename (const std::string &pluginName) const
 Get the platform and build configuration depended plugin filename. More...
 
virtual const char * getName () const override
 Get the name of the system. More...
 
virtual bool onStartup (bool serverMode) override
 Startup the plugin system. More...
 
virtual void onShutdown () override
 Shutdown the plugin system. More...
 
- Public Member Functions inherited from qsf::System
virtual ~System ()
 Destructor. More...
 

Static Public Attributes

static const char * DEBUG_POSTFIX
 "d" UTF-8 QSF debug postfix, used e.g. when loading debug versions of shared libraries More...
 

Additional Inherited Members

- Protected Member Functions inherited from qsf::System
 System ()
 Default constructor. More...
 

Detailed Description

Plugin system class.

Todo:
  • TODO(co) Set plugin filename of plugins not loaded dynamically via "qsf::PluginSystem::loadPlugin()"

Definition at line 45 of file PluginSystem.h.

Constructor & Destructor Documentation

qsf::PluginSystem::PluginSystem ( )
inline

Default constructor.

Definition at line 14 of file PluginSystem-inl.h.

qsf::PluginSystem::~PluginSystem ( )
inlinevirtual

Destructor.

Definition at line 20 of file PluginSystem-inl.h.

Member Function Documentation

void qsf::PluginSystem::addPlugin ( Plugin plugin)

Add a plugin.

Parameters
[in]pluginReference to the plugin instance to add to this plugin system
Remarks
The plugin system will take over the control of the provided plugin instance and will destroy it in case it's no longer required. The plugin system will also handle the plugin lifecycle by calling "onInstall()", "onStartup()", "onShutdown()" and "onUninstall()" at the appropriate time.
void qsf::PluginSystem::addPluginSearchDirectory ( const std::string &  path)

Add a search directory to look for plugin dependencies.

Parameters
[in]pathUTF-8 absolute path in platform-independent notation of the directory to search in (e.g. "D:/sample_project/bin")
const char * qsf::PluginSystem::getName ( ) const
inlineoverridevirtual

Get the name of the system.

Returns
Null terminated ASCII name of the system, never a null pointer, do not manipulate or destroy the returned name

Implements qsf::System.

Definition at line 34 of file PluginSystem-inl.h.

const std::vector< Plugin * > & qsf::PluginSystem::getPlugins ( ) const
inline

Return the list of currently loaded plugins.

Returns
Reference to the internal list of currently loaded plugins, do not manipulate the list or destroy the plugins

Definition at line 25 of file PluginSystem-inl.h.

std::string qsf::PluginSystem::getSharedLibraryFilename ( const std::string &  pluginName) const

Get the platform and build configuration depended plugin filename.

Parameters
[in]pluginNameUTF-8 QSF plugin name (example: "editor", "sample", "sample_editor"), plugin filenames are automatically derived from those names (example: "editor.dll", "sample.dll", "sample_editor.dll")
Returns
The UTF-8 plugin filename (example when using "editor" as plugin name: "editor.dll" for MS Windows release, "editord.dll" for MS Windows debug, "libeditor.so" for Linux release, "libeditord.so" for Linug debug)
bool qsf::PluginSystem::loadPlugin ( const std::string &  pluginName,
const std::string &  filename 
)

Load a plugin.

Parameters
[in]pluginNameASCII plugin name (e.g. "sample")
[in]filenameUTF-8 filename in platform-independent notation of the plugin to load in (e.g. "sample.dll")
Returns
"true" if all went fine or the plugin is already loaded, else "false"
Remarks
Inside the plugin file, the plugin function entry point is named "CreatePluginInstance_<plugin name>()" (e.g. "CreatePluginInstance_sample()" if the plugin name is "sample"). Sadly, we can't give each plugin the same plugin function entry point name. While this would work on MS Windows, it would not work on Mac OS X due to the dylib behaviour there: https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man3/dlsym.3.html "If dlsym() is called with a handle, returned by dlopen() then only that image and any libraries it depends on are searched for symbol."
virtual void qsf::PluginSystem::onShutdown ( )
overridevirtual

Shutdown the plugin system.

Remarks
The implementation does the following tasks:
  • Unload all plugins
Note
  • This method is only called case "onStartup()" returned successfully

Implements qsf::System.

virtual bool qsf::PluginSystem::onStartup ( bool  serverMode)
overridevirtual

Startup the plugin system.

Returns
"true" if all went fine, else "false"
Remarks
The implementation does the following tasks:
  • Create the QSF core plugin ("qsf::QsfPlugin()") instance and add it to this plugin system

Implements qsf::System.

void qsf::PluginSystem::unloadAllPlugins ( )

Unload all plugins.

Note
  • The plugins are unloaded in reversed order in case there's a dependency between plugins (which should be avoided whenever possible!)

Member Data Documentation

const char* qsf::PluginSystem::DEBUG_POSTFIX
static

"d" UTF-8 QSF debug postfix, used e.g. when loading debug versions of shared libraries

Definition at line 53 of file PluginSystem.h.


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