libs/glibmm2/glib/src/module.hg

   1 /* $Id: module.hg,v 1.5 2004/04/09 14:49:44 murrayc Exp $ */
   2
   3 /* Copyright (C) 2002 The gtkmm Development Team
   4  *
   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.
   9  *
  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.
  14  *
  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.
  18  */
  19
  20 _DEFS(glibmm,glib)
  21
  22 #include <glibmmconfig.h>
  23 #include <string>
  24
  25 GLIBMM_USING_STD(string)
  26
  27 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  28 extern "C" { typedef struct _GModule GModule; }
  29 #endif
  30
  31
  32 namespace Glib
  33 {
  34
  35 _WRAP_ENUM(ModuleFlags, GModuleFlags, NO_GTYPE)
  36
  37 //TODO: Replace get_last_error() with exceptions?
  38 //Provide operator()?
  39
  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.
  46  */
  47 class Module
  48 {
  49   _CLASS_GENERIC(Module, GModule)
  50   _IGNORE(g_module_open, g_module_close)
  51
  52 public:
  53
  54   /** Opens a module.
  55    *
  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.
  64    *
  65    * Use operator bool() to see whether the operation succeeded. For instance,
  66    * @code
  67    * Glib::Module module("plugins/helloworld");
  68    * if(module)
  69    * {
  70    *   void* func = 0;
  71    *   bool found = get_symbol("some_function", func);
  72    * }
  73    * @endcode
  74    *
  75    * @param file_name The library filename to open
  76    * @param flags Flags to configure the load process
  77    */
  78   explicit Module(const std::string& file_name, ModuleFlags flags = ModuleFlags(0));
  79
  80   /** Close a module. The module will be removed from memory, unless
  81    * <tt>make_resident</tt> has been called.
  82    */
  83   virtual ~Module();
  84
  85   /** Check whether the module was found.
  86    */
  87   operator bool() const;
  88
  89   /** Checks if modules are supported on the current platform.
  90    * @returns true if available, false otherwise
  91    */
  92   _WRAP_METHOD(static bool get_supported(), g_module_supported)
  93
  94   /** Ensures that a module will never be unloaded. Any calls to the
  95    * Glib::Module destructor will not unload the module.
  96    */
  97   _WRAP_METHOD(void make_resident(), g_module_make_resident)
  98
  99   /** Gets a string describing the last module error.
 100    * @returns The error string
 101    */
 102   _WRAP_METHOD(static std::string get_last_error(), g_module_error)
 103
 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.
 108    */
 109   _WRAP_METHOD(bool get_symbol(const std::string& symbol_name, void*& symbol) const, g_module_symbol)
 110
 111   /** Get the name of the module.
 112    * @returns The name of the module
 113    */
 114   _WRAP_METHOD(std::string get_name() const, g_module_name)
 115
 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.
 120    *
 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.
 125    *
 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>.
 131    *
 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
 135    */
 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)
 139
 140   GModule*       gobj()       { return gobject_; }
 141   const GModule* gobj() const { return gobject_; }
 142
 143 protected:
 144   GModule* gobject_;
 145
 146 private:
 147   // noncopyable
 148   Module(const Module&);
 149   Module& operator=(const Module&);
 150 };
 151
 152 } // namespace Glib
 153