OBT::Plugin Class Reference

#include <OBTPlugin.h>

Collaboration diagram for OBT::Plugin:

[legend]

List of all members.

Public Types
typedef bool(*	InitFunc )(const char *configurationFile)
	Initialization function implemented by the plugin.
typedef bool(*	DeInitFunc )()
	De-initialization function implemented by the plugin.
typedef const PluginInformation &(*	PluginInformationFunc )()
	Plugin information function implemented by the plugin.
Public Member Functions
	Plugin (const char *path, const char *name, const char *configurationFile=0)
virtual	~Plugin ()
bool	load ()
bool	unload ()
bool	isLoaded () const
const PluginInformation &	getInformation () const
const char *	getPath () const
const char *	getConfigurationFile () const
Private Member Functions
	Plugin (const Plugin &)
	No copy.
Plugin &	operator= (const Plugin &)
	No copy.
Private Attributes
void *	_pluginHandle
	OBTPlugin.handle.
bool	_initialised
	initialised state (set by a call to initPlugin)
std::string	_path
	plugin path
std::string	_configurationFile
	plugin configuration file path

---

Detailed Description

This class permits to load / unload a plugin (a cross-platform dynamically linked library).

Definition at line 20 of file OBTPlugin.h.

---

Member Typedef Documentation

typedef bool( * OBT::Plugin::InitFunc)(const char *configurationFile)

Initialization function implemented by the plugin.

Definition at line 25 of file OBTPlugin.h.

typedef bool( * OBT::Plugin::DeInitFunc)()

De-initialization function implemented by the plugin.

Definition at line 28 of file OBTPlugin.h.

typedef const PluginInformation&( * OBT::Plugin::PluginInformationFunc)()

Plugin information function implemented by the plugin.

Definition at line 31 of file OBTPlugin.h.

---

Constructor & Destructor Documentation

Plugin::Plugin	(	const char *	path,
		const char *	name,
		const char *	configurationFile = 0
	)

Constructor.

Parameters:

[in]	path	of the plugin file.
[in]	name	of the plugin file. Can be null.
[in]	configurationFile	of the plugin. Null by default.

If the name is null the path must include the complete name an path of the plugin library. If the name is defined the plugin library is:

• for Windows in debug : {path}/debug/{name}_d.dll or {path}/{name}_d.dll
• for Windows in release : {path}/release/{name}.dll or {path}//{name}.dll
• for Linux in debug : {path}/lib{name}.so or lib{name}.so if {path} is null, in that case the library must be in the LD_LIBRARY_PATH
• for Linux in release : {path}/release/lib{name}.so

Definition at line 15 of file OBTPlugin.cpp.

References _configurationFile, _path, and OBT_ASSERT.

:
_pluginHandle( 0 ),
_initialised( false )
{
  OBT_ASSERT( path != NULL ) ;
  _path = path ;
  if( name )
  {
#ifdef _MSC_VER
#  ifndef NDEBUG
    // first try in _path
    _path += "/" + std::string( name ) + "_d.dll" ;
    struct stat buffer ;
    if( stat( _path.c_str(), &buffer ) )
    { // The file doesn't exist => search in sub-directory according to the debug/release flag
      _path = std::string( path ) + "/debug/" + std::string( name ) + "_d.dll" ;
    }
#  else
    // first try in _path
    _path += "/" + std::string( name ) + ".dll" ;
    struct stat buffer ;
    if( stat( _path.c_str(), &buffer ) )
    { // The file doesn't exist => search in sub-directory according to the debug/release flag
      _path = std::string( path ) + "/release/" + std::string( name ) + ".dll" ;
    }
#  endif
#else
    // first try in _path
    _path += ( ( "" == _path ) ? "lib" : "/lib" ) + std::string( name ) + ".so" ;
#endif
  }
  
  if ( configurationFile != NULL )
  {
    _configurationFile = configurationFile ;
  }
  else
  {
    _configurationFile = "" ;
  }
}

Plugin::~Plugin

(

)

[virtual]

Destructor.

Definition at line 61 of file OBTPlugin.cpp.

References unload().

{
  unload( ) ;
}

OBT::Plugin::Plugin

(

const Plugin &

)

[private]

No copy.

---

Member Function Documentation

bool Plugin::load

(

)

Load the plugin.

Returns:

true on success, false otherwise.

Definition at line 70 of file OBTPlugin.cpp.

References _initialised, _path, _pluginHandle, getConfigurationFile(), and TRACE_ERROR.

{
  if ( _pluginHandle == NULL )
  {
    // load the plugin
  #ifdef _MSC_VER
    _pluginHandle = LoadLibrary( _path.c_str() ) ;
  #else
    _pluginHandle = dlopen( _path.c_str(), RTLD_LAZY | RTLD_GLOBAL ) ;
  #endif
    if ( _pluginHandle == NULL )
    {
      TRACE_ERROR( "Unable to load plugin: " << _path.c_str() ) ;
  #ifndef _MSC_VER
      char *s = dlerror() ;
      if (s)
      {
        TRACE_ERROR( "Error message from plugin loading: " << s ) ;
        free( s ) ;
      }
  #endif
      _initialised = false ;
    }
    // call the initPlugin function of the plugin
    else
    {
      _initialised = true ;
      void* functionPointer( NULL ) ;
  #ifdef _MSC_VER
      functionPointer = GetProcAddress( _pluginHandle, "initPlugin" ) ;
  #else
      functionPointer = dlsym( _pluginHandle, "initPlugin" ) ;
  #endif
      InitFunc initFunc( reinterpret_cast<InitFunc>( functionPointer ) ) ;
      if( initFunc == NULL )
      {
        TRACE_ERROR( "Unable to call the initPlugin function of the plugin: " << _path.c_str() ) ;
        _initialised = false ;
      }
      else 
      {
        _initialised = initFunc( getConfigurationFile() ) ;
      }
    }
  }

  return _initialised ;
}

bool Plugin::unload

(

)

Unload the plugin.

Returns:

true on success, false otherwise.

Definition at line 123 of file OBTPlugin.cpp.

References _initialised, _path, _pluginHandle, and TRACE_ERROR.

Referenced by ~Plugin().

{
  bool returnCode( true ) ;
  if( _pluginHandle != NULL )
  {  
    // call the finishPlugin function of the plugin
    void* functionPointer( NULL ) ;
#ifdef _MSC_VER
    functionPointer = GetProcAddress( _pluginHandle, "finishPlugin" ) ;
#else
    functionPointer = dlsym( _pluginHandle, "finishPlugin" ) ;
#endif
    DeInitFunc deInitFunc( reinterpret_cast<DeInitFunc>( functionPointer ) ) ;
    if( deInitFunc == NULL )
    {
      TRACE_ERROR( "Unable to call the finishPlugin function of the plugin: " << _path.c_str() ) ;
      returnCode = false ;
    }
    else 
    {
      returnCode = deInitFunc() ;
    }

    // unload the plugin
#ifdef _MSC_VER
    FreeLibrary( _pluginHandle ) ;
#else
    dlclose( _pluginHandle ) ;
#endif
    _pluginHandle = NULL ;
    _path = "" ;
  }
  _initialised = false ;

  return returnCode ;
}

bool OBT::Plugin::isLoaded

(

)

const [inline]

Get accessor to the loaded state.

Returns:

true if the plugin is loaded, false otherwise.

Definition at line 120 of file OBTPlugin.h.

References _initialised.

{
        return _initialised ;
}

const PluginInformation & Plugin::getInformation

(

)

const

Get plugin information.

Returns:

plugin information.

Definition at line 164 of file OBTPlugin.cpp.

References _path, _pluginHandle, TRACE_ERROR, and OBT::PluginInformation::Unknown.

{
  if( _pluginHandle != NULL )
  {
    void* functionPointer( NULL ) ;
#ifdef _MSC_VER
    functionPointer = GetProcAddress( _pluginHandle, "getPluginInformation" ) ;
#else
    functionPointer = dlsym( _pluginHandle, "getPluginInformation" ) ;
#endif
    PluginInformationFunc pluginInformationFunc( reinterpret_cast<PluginInformationFunc>( functionPointer ) ) ;
    if( pluginInformationFunc != NULL )
    {
      return pluginInformationFunc() ;
    }
    else
    {
      TRACE_ERROR( "Unable to call the getPluginInformation function of the plugin: " << _path.c_str() ) ;
    }
  }

  return PluginInformation::Unknown ;
}

const char * OBT::Plugin::getPath

(

)

const [inline]

get accessor to the plugin path.

Returns:

a C string of the plugin path.

Definition at line 129 of file OBTPlugin.h.

References _path.

{
  return _path.c_str() ;
}

const char * OBT::Plugin::getConfigurationFile

(

)

const [inline]

get accessor to the plugin configuration file path.

Returns:

a C string to the configuration file path, null if there is no configuration file.

Definition at line 138 of file OBTPlugin.h.

References _configurationFile.

Referenced by load().

{
  return _configurationFile.empty() ? NULL : _configurationFile.c_str() ;
}

Plugin& OBT::Plugin::operator=

(

const Plugin &

)

[private]

No copy.

---

Member Data Documentation

void* OBT::Plugin::_pluginHandle [private]

OBTPlugin.handle.

Definition at line 103 of file OBTPlugin.h.

Referenced by getInformation(), load(), and unload().

bool OBT::Plugin::_initialised [private]

initialised state (set by a call to initPlugin)

Definition at line 107 of file OBTPlugin.h.

Referenced by isLoaded(), load(), and unload().

std::string OBT::Plugin::_path [private]

plugin path

Definition at line 110 of file OBTPlugin.h.

Referenced by getInformation(), getPath(), load(), Plugin(), and unload().

std::string OBT::Plugin::_configurationFile [private]

plugin configuration file path

Definition at line 113 of file OBTPlugin.h.

Referenced by getConfigurationFile(), and Plugin().

---