Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::G::Module Class Reference

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

#include <xfc/glib/module.hh>

Inheritance diagram for Xfc::G::Module:

Xfc::Object Xfc::Trackable List of all members.

Public Member Functions

Accessors
Methods

Static Public Member Functions

Accessors
Methods

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

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::name (  )  const

Gets the filename of the module.

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

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

Checks if modules are supported on the current platform.

Returns:
true if modules are supported.

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

Gets a string describing the last module error.

Returns:
A string describing the last module error.

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

Closes the module.

Returns:
true if successful.

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

Ensures that the module will never be unloaded.

Any future close() calls on the module will be ignored.

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.

static 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.

static 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&)).

static 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.


The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3