glibmm 2.56.0

Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
Glib::Module Class Reference

Dynamic Loading of Modules These functions provide a portable way to dynamically load object files (commonly known as 'plug-ins'). More...

`#include <glibmm/module.h>`

## Public Member Functions
| Module (const std::string& file_name, ModuleFlags flags=ModuleFlags(0))
| Opens a module. More...
| Module (const Module&)=delete
Module& | operator= (const Module&)=delete
| Module (Module&& other) noexcept
Module& | operator= (Module&& other) noexcept
virtual | ~Module ()
| Close a module. More...
| operator bool () const
| Check whether the module was found. More...
void | make_resident ()
| Ensures that a module will never be unloaded. More...
bool | get_symbol (const std::string& symbol_name, void*& symbol) const
| Gets a symbol pointer from the module. More...
std::string | get_name () const
| Get the name of the module. More...
GModule* | gobj ()
const GModule* | gobj () const

## Static Public Member Functions
static bool | get_supported ()
| Checks if modules are supported on the current platform. More...
static std::string | get_last_error ()
| Gets a string describing the last module error. More...
static std::string | build_path (const std::string& directory, const std::string& module_name)
| A portable way to build the filename of a module. More...

## Protected Attributes
GModule* | gobject_

## Detailed Description

Dynamic Loading of Modules These functions provide 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.

## Constructor & Destructor Documentation

## ◆ Module() [1/3]

Glib::Module::Module | ( | const std::string & | file_name,
|  | ModuleFlags | flags = `ModuleFlags(0)`
| ) |  |
| explicit

Opens a module.

First of all it tries to open file_name as a module. If that fails and file_name 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 file_name doesn't have the ".la"-suffix, this suffix is appended and it tries to open the corresponding module.

Use operator bool() to see whether the operation succeeded. For instance,

Glib::Module module("plugins/helloworld");
if(module)
{
void* func = nullptr;
bool found = get_symbol("some_function", func);
}

Parameters

  file_name | The library filename to open
  flags | Flags to configure the load process

## ◆ Module() [2/3]

Glib::Module::Module | ( | const Module& |  | ) |
| delete

## ◆ Module() [3/3]

Glib::Module::Module | ( | Module&& | other | ) |
| noexcept

## ◆ ~Module()

virtual Glib::Module::~Module | ( |  | ) |
| virtual

Close a module.

The module will be removed from memory, unless `make_resident` has been called.

## Member Function Documentation

## ◆ build_path()

static std::string Glib::Module::build_path | ( | const std::string & | directory,
|  | const std::string & | module_name
| ) |  |
| static

A portable way to build the filename of a module.

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

Parameters

  directory | The directory the module is in
  module_name | The name of the module

Returns
  The system-specific filename of the module A portable way to build the filename of a module. 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 `nullptr` 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 g_module_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`.

Parameters

  directory | The directory where the module is. This can be `nullptr` or the empty string to indicate that the standard platform-specific directories will be used, though that is not recommended.
  module_name | The name of the module.

Returns
  The complete path of the module, including the standard library prefix and suffix. This should be freed when no longer needed.

## ◆ get_last_error()

static std::string Glib::Module::get_last_error | ( |  | ) |
| static

Gets a string describing the last module error.

Returns
  The error string

## ◆ get_name()

std::string Glib::Module::get_name | ( |  | ) | const

Get the name of the module.

Returns
  The name of the module

## ◆ get_supported()

static bool Glib::Module::get_supported | ( |  | ) |
| static

Checks if modules are supported on the current platform.

Returns
  true if available, false otherwise

## ◆ get_symbol()

bool Glib::Module::get_symbol | ( | const std::string & | symbol_name,
|  | void *& | symbol
| ) |  | const

Gets a symbol pointer from the module.

Parameters

  symbol_name | The name of the symbol to lookup
  symbol | A pointer to set to the symbol

Returns
  True if the symbol was found, false otherwise.

## ◆ gobj() [1/2]

GModule* Glib::Module::gobj | ( |  | ) |
| inline

## ◆ gobj() [2/2]

const GModule* Glib::Module::gobj | ( |  | ) | const
| inline

## ◆ make_resident()

void Glib::Module::make_resident | ( |  | ) |

Ensures that a module will never be unloaded.

Any calls to the Glib::Module destructor will not unload the module.

## ◆ operator bool()

Glib::Module::operator bool | ( |  | ) | const
| explicit

Check whether the module was found.

## ◆ operator=() [1/2]

Module& Glib::Module::operator= | ( | const Module& |  | ) |
| delete

## ◆ operator=() [2/2]

Module& Glib::Module::operator= | ( | Module&& | other | ) |
| noexcept

## Member Data Documentation

## ◆ gobject_

GModule* Glib::Module::gobject_
| protected