1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY! 2 #ifndef _GLIBMM_MODULE_H 3 #define _GLIBMM_MODULE_H 4 5 6 /* Copyright (C) 2002 The gtkmm Development Team 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 23 #include <glibmmconfig.h> 24 #include <string> 25 26 #ifndef DOXYGEN_SHOULD_SKIP_THIS 27 extern "C" { typedef struct _GModule GModule; } 28 #endif 29 30 namespace Glib 31 { 32 33 /** @addtogroup glibmmEnums glibmm Enums and Flags */ 34 35 /** 36 * @var ModuleFlags MODULE_BIND_LAZY 37 * Specifies that symbols are only resolved when 38 * needed. The default action is to bind all symbols when the module 39 * is loaded. 40 * 41 * @var ModuleFlags MODULE_BIND_LOCAL 42 * Specifies that symbols in the module should 43 * not be added to the global name space. The default action on most 44 * platforms is to place symbols in the module in the global name space, 45 * which may cause conflicts with existing symbols. 46 * 47 * @var ModuleFlags MODULE_BIND_MASK 48 * Mask for all flags. 49 * 50 * @enum ModuleFlags 51 * 52 * Flags passed to g_module_open(). 53 * Note that these flags are not supported on all platforms. 54 * 55 * @ingroup glibmmEnums 56 * @par Bitwise operators: 57 * <tt>%ModuleFlags operator|(ModuleFlags, ModuleFlags)</tt><br> 58 * <tt>%ModuleFlags operator&(ModuleFlags, ModuleFlags)</tt><br> 59 * <tt>%ModuleFlags operator^(ModuleFlags, ModuleFlags)</tt><br> 60 * <tt>%ModuleFlags operator~(ModuleFlags)</tt><br> 61 * <tt>%ModuleFlags& operator|=(ModuleFlags&, ModuleFlags)</tt><br> 62 * <tt>%ModuleFlags& operator&=(ModuleFlags&, ModuleFlags)</tt><br> 63 * <tt>%ModuleFlags& operator^=(ModuleFlags&, ModuleFlags)</tt><br> 64 */ 65 enum ModuleFlags 66 { 67 MODULE_BIND_LAZY = 1 << 0, 68 MODULE_BIND_LOCAL = 1 << 1, 69 MODULE_BIND_MASK = 0x03 70 }; 71 72 /** @ingroup glibmmEnums */ 73 inline ModuleFlags operator|(ModuleFlags lhs, ModuleFlags rhs) 74 { return static_cast<ModuleFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); } 75 76 /** @ingroup glibmmEnums */ 77 inline ModuleFlags operator&(ModuleFlags lhs, ModuleFlags rhs) 78 { return static_cast<ModuleFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); } 79 80 /** @ingroup glibmmEnums */ 81 inline ModuleFlags operator^(ModuleFlags lhs, ModuleFlags rhs) 82 { return static_cast<ModuleFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); } 83 84 /** @ingroup glibmmEnums */ 85 inline ModuleFlags operator~(ModuleFlags flags) 86 { return static_cast<ModuleFlags>(~static_cast<unsigned>(flags)); } 87 88 /** @ingroup glibmmEnums */ 89 inline ModuleFlags& operator|=(ModuleFlags& lhs, ModuleFlags rhs) 90 { return (lhs = static_cast<ModuleFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); } 91 92 /** @ingroup glibmmEnums */ 93 inline ModuleFlags& operator&=(ModuleFlags& lhs, ModuleFlags rhs) 94 { return (lhs = static_cast<ModuleFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); } 95 96 /** @ingroup glibmmEnums */ 97 inline ModuleFlags& operator^=(ModuleFlags& lhs, ModuleFlags rhs) 98 { return (lhs = static_cast<ModuleFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); } 99 100 101 //TODO: Replace get_last_error() with exceptions? 102 //Provide operator()? 103 104 /** Dynamic Loading of Modules 105 * These functions provide a portable way to dynamically load object 106 * files (commonly known as 'plug-ins'). The current implementation 107 * supports all systems that provide an implementation of dlopen() 108 * (e.g. Linux/Sun), as well as HP-UX via its shl_load() mechanism, 109 * and Windows platforms via DLLs. 110 */ 111 class GLIBMM_API Module 112 { 113 public: 114 #ifndef DOXYGEN_SHOULD_SKIP_THIS 115 using CppObjectType = Module; 116 using BaseObjectType = GModule; 117 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 118 119 private: 120 121 122 public: 123 124 /** Opens a module. 125 * 126 * First of all it tries to open file_name as a module. If that 127 * fails and file_name has the ".la"-suffix (and is a libtool 128 * archive) it tries to open the corresponding module. If that fails 129 * and it doesn't have the proper module suffix for the platform 130 * (G_MODULE_SUFFIX), this suffix will be appended and the 131 * corresponding module will be opended. If that fails and file_name 132 * doesn't have the ".la"-suffix, this suffix is appended and 133 * it tries to open the corresponding module. 134 * 135 * Use operator bool() to see whether the operation succeeded. For instance, 136 * @code 137 * Glib::Module module("plugins/helloworld"); 138 * if(module) 139 * { 140 * void* func = nullptr; 141 * bool found = get_symbol("some_function", func); 142 * } 143 * @endcode 144 * 145 * @param file_name The library filename to open 146 * @param flags Flags to configure the load process 147 */ 148 explicit Module(const std::string& file_name, ModuleFlags flags = ModuleFlags(0)); 149 150 Module(const Module&) = delete; 151 Module& operator=(const Module&) = delete; 152 153 Module(Module&& other) noexcept; 154 Module& operator=(Module&& other) noexcept; 155 156 /** Close a module. The module will be removed from memory, unless 157 * <tt>make_resident</tt> has been called. 158 */ 159 virtual ~Module(); 160 161 /** Check whether the module was found. 162 */ 163 explicit operator bool() const; 164 165 166 /** Checks if modules are supported on the current platform. 167 * @returns true if available, false otherwise 168 */ 169 static bool get_supported(); 170 171 172 /** Ensures that a module will never be unloaded. Any calls to the 173 * Glib::Module destructor will not unload the module. 174 */ 175 void make_resident(); 176 177 178 /** Gets a string describing the last module error. 179 * @returns The error string 180 */ 181 static std::string get_last_error(); 182 183 184 /** Gets a symbol pointer from the module. 185 * @param symbol_name The name of the symbol to lookup 186 * @param symbol A pointer to set to the symbol 187 * @returns True if the symbol was found, false otherwise. 188 */ 189 bool get_symbol(const std::string& symbol_name, void*& symbol) const; 190 191 192 /** Get the name of the module. 193 * @returns The name of the module 194 */ 195 std::string get_name() const; 196 197 /** A portable way to build the filename of a module. The 198 * platform-specific prefix and suffix are added to the filename, if 199 * needed, and the result is added to the directory, using the 200 * correct separator character. 201 * 202 * The directory should specify the directory where the module can 203 * be found. It can be an empty string to indicate that the 204 * module is in a standard platform-specific directory, though this 205 * is not recommended since the wrong module may be found. 206 * 207 * For example, calling <tt>build_path()</tt> on a Linux 208 * system with a directory of <tt>/lib</tt> and a module_name of 209 * "mylibrary" will return <tt>/lib/libmylibrary.so</tt>. On a 210 * Windows system, using <tt>\\Windows</tt> as the directory it will 211 * return <tt>\\Windows\\mylibrary.dll</tt>. 212 * 213 * @param directory The directory the module is in 214 * @param module_name The name of the module 215 * @returns The system-specific filename of the module 216 */ 217 // TODO: add an override which doesn't take a directory 218 // TODO: check what happens when directory is "" 219 220 /** A portable way to build the filename of a module. The platform-specific 221 * prefix and suffix are added to the filename, if needed, and the result 222 * is added to the directory, using the correct separator character. 223 * 224 * The directory should specify the directory where the module can be found. 225 * It can be <tt>nullptr</tt> or an empty string to indicate that the module is in a 226 * standard platform-specific directory, though this is not recommended 227 * since the wrong module may be found. 228 * 229 * For example, calling g_module_build_path() on a Linux system with a 230 * @a directory of `/lib` and a @a module_name of "mylibrary" will return 231 * `/lib/libmylibrary.so`. On a Windows system, using `\\Windows` as the 232 * directory it will return `\\Windows\\mylibrary.dll`. 233 * 234 * @param directory The directory where the module is. This can be 235 * <tt>nullptr</tt> or the empty string to indicate that the standard platform-specific 236 * directories will be used, though that is not recommended. 237 * @param module_name The name of the module. 238 * @return The complete path of the module, including the standard library 239 * prefix and suffix. This should be freed when no longer needed. 240 */ 241 static std::string build_path(const std::string& directory, const std::string& module_name); 242 gobj()243 GModule* gobj() { return gobject_; } gobj()244 const GModule* gobj() const { return gobject_; } 245 246 protected: 247 GModule* gobject_; 248 249 250 }; 251 252 } // namespace Glib 253 254 255 #endif /* _GLIBMM_MODULE_H */ 256 257