A class for handling shared libraries (DLLs, SO, DyLibs). More...

#include <Library.h>

Inheritance diagram for te::core::Library:

Classes
struct	Impl

Public Member Functions
void *	getAddress (const char *symbol) const
	Return the address where the given symbol is loaded into memory. More...

const std::string &	getFileName () const
	Return the shared library file name as informed in the constructor. More...

bool	isLoaded () const
	Return true if the shared library is loaded otherwise return false. More...

	Library (const std::string &slib_file_name, const bool &delay_load=false)
	Load a new shared library. More...

void	load ()
	Load the shared library to memory. More...

void	unload ()
	Force the unload of the shared library from memory. More...

	~Library ()
	The destructor automatically unloads from memory the shared library if it was not unloaded explicitly. More...

Static Public Member Functions
static void	addSearchDir (const std::string &dir_name)
	Add the informed dir to the path used by the operational system to lookup for shared libraries. More...

static std::string	getNativeName (const std::string &name)
	Given a shared library name without file extensions, prefixes and nor suffixes it will construct a library name according to the specifc platform. More...

static std::string	getSearchPath ()
	Returns the system lookup path. More...

static void	resetSearchPath ()
	Comes back the application lookup path to the original state, before any add_search_dir has been called. More...

Private Attributes
Impl *	m_pimpl

Detailed Description

A class for handling shared libraries (DLLs, SO, DyLibs).

You can use this class to load any shared library and acces any address inside it.

If the shared library you are attempting to load has dependencies the other shared libraries must be in a folder reachable by the operational system.

On Mac OS X the environment variables PATH, DYLD_LIBRARY_PATH, DYLD_FALLBACK_LIBRARY_PATH and DYLD_FRAMEWORK_FALLBACK_PATH may be set to indicate the list of folders containing shared libraries.

On Linux the environment variables PATH and LD_LIBRARY_PATH may be used to indicate the folders searchable by the operational system.

On Windows you can set the environment variable PATH.

Note that this class has a special static method (or class method) named addSearchDir that can be used to control the behaviour of operational system when loading the shared library dependencies.

Warning: Shared libraries should not be loaded concurrently by multiple threads.

Definition at line 73 of file Library.h.

Constructor & Destructor Documentation

te::core::Library::Library	(	const std::string &	slib_file_name,
		const bool &	delay_load = `false`
	)

Load a new shared library.

The file name may be a relative or absolute path.

If just the name of the shared library is given the class will look for the library in the operational system specific locations.

Parameters

slib_file_name	The library file name. The file name may contain the full library path.
delay_load	If true the client object must call explicitly the load method before trying to access any symbol in the library.

Exceptions

LibraryLoadException	It can throw an exception if delay_load is set to false and the library can not be loaded.
LibraryNameException	It throws an exception if library name is empty or just white-spaces.

Definition at line 116 of file Library.cpp.

References load(), m_pimpl, and TE_TR.

te::core::Library::~Library ( )

The destructor automatically unloads from memory the shared library if it was not unloaded explicitly.

Definition at line 134 of file Library.cpp.

References m_pimpl, and unload().

Member Function Documentation

void te::core::Library::addSearchDir ( const std::string & dir_name )

static

Add the informed dir to the path used by the operational system to lookup for shared libraries.

Parameters

dir_name A directory to be added to the lookup of shared libraries.

Exceptions

LibraryInvalidSearchPathException It throws an exception if the path couldn't be added to the search path.

Note: Not thread-safe.; For Linux and Mac OS X this method doesn't perform operations.

Definition at line 279 of file Library.cpp.

References te_get_os_error(), and TE_TR.

Referenced by BOOST_AUTO_TEST_CASE(), and main().

void * te::core::Library::getAddress ( const char * symbol ) const

Return the address where the given symbol is loaded into memory.

Parameters

symbol The name of the symbol inside the library you are searching for. It may be for instance a function name.

Returns: The address where the symbol is loaded.

Exceptions

LibrarySymbolNotFoundException It throws an exception if it is not possible to locate the given symbol.

Note: Not thread-safe.

Definition at line 227 of file Library.cpp.

References m_pimpl, te::core::Library::Impl::module, te::core::Library::Impl::slib_file_name, te_get_os_error(), and TE_TR.

Referenced by BOOST_AUTO_TEST_CASE(), and main().

const std::string & te::core::Library::getFileName ( ) const

Return the shared library file name as informed in the constructor.

Definition at line 221 of file Library.cpp.

References m_pimpl, and te::core::Library::Impl::slib_file_name.

Referenced by BOOST_AUTO_TEST_CASE(), and main().

std::string te::core::Library::getNativeName ( const std::string & name )

static

Given a shared library name without file extensions, prefixes and nor suffixes it will construct a library name according to the specifc platform.

Definition at line 256 of file Library.cpp.

Referenced by BOOST_AUTO_TEST_CASE(), te::plugin::CppPluginEngine::getPluginFileName(), te::core::CppPluginEngine::load(), and main().

std::string te::core::Library::getSearchPath ( )

static

Returns the system lookup path.

Exceptions

LibrarySearchPathException It throws an exception if the path couldn't be reset.

Note: Not thread-safe.

Definition at line 323 of file Library.cpp.

References te_get_os_error(), and TE_TR.

bool te::core::Library::isLoaded ( ) const

Return true if the shared library is loaded otherwise return false.

Definition at line 215 of file Library.cpp.

References m_pimpl, and te::core::Library::Impl::module.

Referenced by BOOST_AUTO_TEST_CASE(), load(), main(), and unload().

void te::core::Library::load ( )

Load the shared library to memory.

If the shared library was already loaded this method doesn't perform operations.

Exceptions

LibraryLoadException If the shared library can not be loaded to memory.

Note: Not thread-safe.

Definition at line 152 of file Library.cpp.

References isLoaded(), m_pimpl, te::core::Library::Impl::module, te::core::Library::Impl::slib_file_name, te_get_os_error(), and TE_TR.

Referenced by BOOST_AUTO_TEST_CASE(), and Library().

void te::core::Library::resetSearchPath ( )

static

Comes back the application lookup path to the original state, before any add_search_dir has been called.

Exceptions

LibraryResetSearchPathException It throws an exception if the path couldn't be reset.

Note: Not thread-safe.; For Linux and Mac OS X this method doesn't perform operations.

Definition at line 304 of file Library.cpp.

References te_get_os_error(), and TE_TR.

Referenced by BOOST_AUTO_TEST_CASE().

void te::core::Library::unload ( )

Force the unload of the shared library from memory.

If the library wasn't previously loaded or if it was already unloaded this method doesn't perform operations.

Exceptions

LibraryUnloadException If the library can not be unload from memory this method raises an exception.

Note: Not thread-safe.

Definition at line 180 of file Library.cpp.

References isLoaded(), m_pimpl, te::core::Library::Impl::module, te::core::Library::Impl::slib_file_name, te_get_os_error(), and TE_TR.

Referenced by BOOST_AUTO_TEST_CASE(), main(), and ~Library().

Member Data Documentation

Impl* te::core::Library::m_pimpl

private

Definition at line 173 of file Library.h.

Referenced by getAddress(), getFileName(), isLoaded(), Library(), load(), unload(), and ~Library().

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

Classes

Public Member Functions

Static Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation