libs/glibmm2/glib/glibmm/module.h

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