Xfce Foundation Classes

Xfc::G::Module Class Reference

A GModule C++ wrapper interface. More...

#include <xfc/glib/module.hh>

Inheritance diagram for Xfc::G::Module:

List of all members.

Public Member Functions

Constructors

virtual ~Module ()
Destructor.

Accessors

GModule * g_module () const
Get a pointer to the GModule object.
operator GModule * () const
Conversion operator; Safely converts a G::Module object into a GModule pointer.
String name () const
Gets the filename of the module.

Methods

bool close ()
Closes the module.
void make_resident ()
Ensures that the module will never be unloaded.
bool symbol (const String &symbol_name, void **symbol)
Gets a symbol pointer from the module.

Static Public Member Functions

Accessors

bool supported ()
Checks if modules are supported on the current platform.
String error ()
Gets a string describing the last module error.

Methods

Module * open (const String &file_name, ModuleFlagsField flags)
Opens a module; if the module has already been opened, its reference count is incremented.
String build_path (const String &module_name)
A portable way to build the filename of a module.
String build_path (const String &directory, const String &module_name)
A portable way to build the filename of a module.

Protected Member Functions

Constructors

Module (GModule *module)
Constructs a new module from an existing GModule.

Detailed Description

A GModule C++ wrapper interface.

Module provides a portable way to dynamically load object files (commonly known as 'plug-ins'). The current implementation supports all systems that provide an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its shl_load() mechanism, and Windows platforms via DLLs.

To use Module you must first determine whether dynamic loading is supported on the platform by calling G::Module::supported(). If it is, you can open a module with G::Module::open(), find the module's symbols (e.g. function names) with G::Module::symbol(), and later close the module with G::Module::close(). G::Module::name() will return the file name of a currently opened module. If any of these methods fail, the error status can be found with G::Module::error().

If your module introduces static data to common subsystems in the running program it must ensure that it is never unloaded, by calling G::Module::make_resident().

Constructor & Destructor Documentation

Xfc::G::Module::Module ( GModule * module ) [protected]

Constructs a new module from an existing GModule.
When the module is destroyed it close will be called to close the module

Member Function Documentation

String Xfc::G::Module::build_path ( const String & directory,

const String & module_name

) [static]

A portable way to build the filename of a module.

Parameters:

directory The directory where the module is.

module_name The name of the module.

Returns:
The complete path of the module, including the standard library prefix and suffix.
The platform-specific prefix and suffix are added to the filename, if needed, and the result is added to the directory, using the correct separator character.
The directory should specify the directory where the module can be found. It can be null or an empty string to indicate that the module is in a standard platform-specific directory, though this is not recommended since the wrong module may be found. For example, calling build_path() on a Linux system with a directory of /lib and a module_name of "mylibrary" will return /lib/libmylibrary.so. On a Windows system, using \Windows as the directory it will return \Windows\mylibrary.dll. To be absoultely sure to get the correct module, always pass in a directory.

String Xfc::G::Module::build_path ( const String & module_name ) [static]

A portable way to build the filename of a module.

Parameters:

module_name The name of the module.

This method is not recommended because it uses the standard platform-specific directories to build the filename and the wrong module may be found (see build_path(const String&, const String&)).

bool Xfc::G::Module::close ( )

Closes the module.

Returns:
true if successful.

String Xfc::G::Module::error ( ) [static]

Gets a string describing the last module error.

Returns:
A string describing the last module error.

void Xfc::G::Module::make_resident ( )

Ensures that the module will never be unloaded.
Any future close() calls on the module will be ignored.

String Xfc::G::Module::name ( ) const

Gets the filename of the module.

Returns:
The filename of the module, or "main" if the module is the main program itself.

Module* Xfc::G::Module::open ( const String & file_name,

ModuleFlagsField flags

) [static]

Opens a module; if the module has already been opened, its reference count is incremented.

Parameters:

file_name The name of the file containing the module.

flags One or more G::ModuleFlags used for opening the module.

Returns:
A Module on success, or null on failure.
First of all this method tries to open filename as a module. If that fails and filename has the ".la" suffix (and is a libtool archive) it tries to open the corresponding module. If that fails and it doesn't have the proper module suffix for the platform (G_MODULE_SUFFIX), this suffix will be appended and the corresponding module will be opended. If that fails and filename doesn't have the ".la"-suffix, this suffix is appended and open() tries to open the corresponding module. If eventually that fails as well, null is returned.

bool Xfc::G::Module::supported ( ) [static]

Checks if modules are supported on the current platform.

Returns:
true if modules are supported.

bool Xfc::G::Module::symbol ( const String & symbol_name,

void ** symbol

)

Gets a symbol pointer from the module.

Parameters:

symbol_name The name of the symbol to find.

symbol The return location for a pointer to the symbol value.

Returns:
true on success.

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

module.hh

Xfce Foundation Classes

XFC 4.3