1 /* $Id: module.hg,v 1.5 2004/04/09 14:49:44 murrayc Exp $ */
3 /* Copyright (C) 2002 The gtkmm Development Team
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library; if not, write to the Free
17 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
22 #include <glibmmconfig.h>
25 GLIBMM_USING_STD(string)
27 #ifndef DOXYGEN_SHOULD_SKIP_THIS
28 extern "C" { typedef struct _GModule GModule; }
35 _WRAP_ENUM(ModuleFlags, GModuleFlags, NO_GTYPE)
37 //TODO: Replace get_last_error() with exceptions?
40 /** Dynamic Loading of Modules
41 * These functions provide a portable way to dynamically load object
42 * files (commonly known as 'plug-ins'). The current implementation
43 * supports all systems that provide an implementation of dlopen()
44 * (e.g. Linux/Sun), as well as HP-UX via its shl_load() mechanism,
45 * and Windows platforms via DLLs.
49 _CLASS_GENERIC(Module, GModule)
50 _IGNORE(g_module_open, g_module_close)
56 * First of all it tries to open file_name as a module. If that
57 * fails and file_name has the ".la"-suffix (and is a libtool
58 * archive) it tries to open the corresponding module. If that fails
59 * and it doesn't have the proper module suffix for the platform
60 * (G_MODULE_SUFFIX), this suffix will be appended and the
61 * corresponding module will be opended. If that fails and file_name
62 * doesn't have the ".la"-suffix, this suffix is appended and
63 * it tries to open the corresponding module.
65 * Use operator bool() to see whether the operation succeeded. For instance,
67 * Glib::Module module("plugins/helloworld");
71 * bool found = get_symbol("some_function", func);
75 * @param file_name The library filename to open
76 * @param flags Flags to configure the load process
78 explicit Module(const std::string& file_name, ModuleFlags flags = ModuleFlags(0));
80 /** Close a module. The module will be removed from memory, unless
81 * <tt>make_resident</tt> has been called.
85 /** Check whether the module was found.
87 operator bool() const;
89 /** Checks if modules are supported on the current platform.
90 * @returns true if available, false otherwise
92 _WRAP_METHOD(static bool get_supported(), g_module_supported)
94 /** Ensures that a module will never be unloaded. Any calls to the
95 * Glib::Module destructor will not unload the module.
97 _WRAP_METHOD(void make_resident(), g_module_make_resident)
99 /** Gets a string describing the last module error.
100 * @returns The error string
102 _WRAP_METHOD(static std::string get_last_error(), g_module_error)
104 /** Gets a symbol pointer from the module.
105 * @param symbol_name The name of the symbol to lookup
106 * @param symbol A pointer to set to the symbol
107 * @returns True if the symbol was found, false otherwise.
109 _WRAP_METHOD(bool get_symbol(const std::string& symbol_name, void*& symbol) const, g_module_symbol)
111 /** Get the name of the module.
112 * @returns The name of the module
114 _WRAP_METHOD(std::string get_name() const, g_module_name)
116 /** A portable way to build the filename of a module. The
117 * platform-specific prefix and suffix are added to the filename, if
118 * needed, and the result is added to the directory, using the
119 * correct separator character.
121 * The directory should specify the directory where the module can
122 * be found. It can be an empty string to indicate that the
123 * module is in a standard platform-specific directory, though this
124 * is not recommended since the wrong module may be found.
126 * For example, calling <tt>g_module_build_path()</tt> on a Linux
127 * system with a directory of <tt>/lib</tt> and a module_name of
128 * "mylibrary" will return <tt>/lib/libmylibrary.so</tt>. On a
129 * Windows system, using <tt>\\Windows</tt> as the directory it will
130 * return <tt>\\Windows\\mylibrary.dll</tt>.
132 * @param directory The directory the module is in
133 * @param module_name The name of the module
134 * @returns The system-specific filename of the module
136 // TODO: add an override which doesn't take a directory
137 // TODO: check what happens when directory is ""
138 _WRAP_METHOD(static std::string build_path(const std::string& directory, const std::string& module_name), g_module_build_path)
140 GModule* gobj() { return gobject_; }
141 const GModule* gobj() const { return gobject_; }
148 Module(const Module&);
149 Module& operator=(const Module&);