include/wx/dynlib.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/dynlib.h
   3 // Purpose:     Dynamic library loading classes
   4 // Author:      Guilhem Lavaux, Vadim Zeitlin, Vaclav Slavik
   5 // Modified by:
   6 // Created:     20/07/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Guilhem Lavaux
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_DYNLIB_H__
  13 #define _WX_DYNLIB_H__
  14
  15 #if defined(__GNUG__) && !defined(__APPLE__)
  16 #   pragma interface "dynlib.h"
  17 #endif
  18
  19 #include "wx/setup.h"
  20
  21 #if wxUSE_DYNLIB_CLASS
  22
  23 #include "wx/string.h"
  24
  25 // FIXME: can this go in private.h or something too??
  26 #if defined(__WXPM__) || defined(__EMX__)
  27 #define INCL_DOS
  28 #include <os2.h>
  29 #endif
  30
  31 #ifdef __WXMSW__
  32 #include "wx/msw/private.h"
  33 #endif
  34
  35 // ----------------------------------------------------------------------------
  36 // conditional compilation
  37 // ----------------------------------------------------------------------------
  38
  39     // Note: WXPM/EMX has to be tested first, since we want to use
  40     // native version, even if configure detected presence of DLOPEN.
  41
  42 #if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__)
  43 typedef HMODULE             wxDllType;
  44 #elif defined(HAVE_DLOPEN)
  45 #include <dlfcn.h>
  46 typedef void               *wxDllType;
  47 #elif defined(HAVE_SHL_LOAD)
  48 #include <dl.h>
  49 typedef shl_t               wxDllType;
  50 #elif defined(__DARWIN__)
  51 typedef void               *wxDllType;
  52 #elif defined(__WXMAC__)
  53 typedef CFragConnectionID   wxDllType;
  54 #else
  55 #error "Dynamic Loading classes can't be compiled on this platform, sorry."
  56 #endif
  57
  58
  59 // ---------------------------------------------------------------------------
  60 // wxDynamicLibrary
  61 // ---------------------------------------------------------------------------
  62
  63 //FIXME:  This class isn't really common at all, it should be moved
  64 //        into platform dependent files.
  65
  66 // NOTE: this class is (deliberately) not virtual, do not attempt
  67 //       to use it polymorphically.
  68
  69 enum wxDLFlags
  70 {
  71     wxDL_LAZY       = 0x00000001,   // resolve undefined symbols at first use
  72     wxDL_NOW        = 0x00000002,   // resolve undefined symbols on load
  73     wxDL_GLOBAL     = 0x00000004,   // export extern symbols to subsequently
  74                                     // loaded libs.
  75     wxDL_VERBATIM   = 0x00000008,   // Attempt to load the supplied library
  76                                     // name without appending the usual dll
  77                                     // filename extension.
  78
  79     wxDL_NOSHARE    = 0x00000010,   // load new DLL, don't reuse already loaded
  80
  81     // FIXME: why? (VZ)
  82 #ifdef __osf__
  83     wxDL_DEFAULT    = wxDL_LAZY
  84 #else
  85     wxDL_DEFAULT    = wxDL_LAZY | wxDL_GLOBAL
  86 #endif
  87 };
  88
  89 enum wxDynamicLibraryCategory
  90 {
  91     wxDL_LIBRARY,       // standard library
  92     wxDL_MODULE,        // loadable module/plugin
  93 };
  94
  95 enum wxPluginCategory
  96 {
  97     wxDL_PLUGIN_GUI,    // plugin that uses GUI classes
  98     wxDL_PLUGIN_BASE,   // wxBase-only plugin
  99 };
 100
 101
 102 class WXDLLIMPEXP_BASE wxDynamicLibrary
 103 {
 104 public:
 105         // return a valid handle for the main program itself or NULL if
 106         // back linking is not supported by the current platform (e.g. Win32)
 107
 108     static wxDllType         GetProgramHandle();
 109
 110         // return the platform standard DLL extension (with leading dot)
 111
 112     static const wxChar *GetDllExt() { return ms_dllext; }
 113
 114     wxDynamicLibrary() : m_handle(0) {}
 115     wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT)
 116         : m_handle(0)
 117     {
 118         Load(libname, flags);
 119     }
 120     ~wxDynamicLibrary() { Unload(); }
 121
 122         // return TRUE if the library was loaded successfully
 123
 124     bool IsLoaded() const { return m_handle != 0; }
 125
 126         // load the library with the given name
 127         // (full or not), return TRUE on success
 128
 129     bool Load(wxString libname, int flags = wxDL_DEFAULT);
 130
 131         // detach the library object from its handle, i.e. prevent the object
 132         // from unloading the library in its dtor -- the caller is now
 133         // responsible for doing this
 134     wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
 135
 136         // unload the library, also done automatically in dtor
 137
 138     void Unload();
 139
 140         // Return the raw handle from dlopen and friends.
 141
 142     wxDllType GetLibHandle() const { return m_handle; }
 143
 144         // resolve a symbol in a loaded DLL, such as a variable or function
 145         // name.  'name' is the (possibly mangled) name of the symbol.
 146         // (use extern "C" to export unmangled names)
 147         //
 148         // Since it is perfectly valid for the returned symbol to actually be
 149         // NULL, that is not always indication of an error.  Pass and test the
 150         // parameter 'success' for a true indication of success or failure to
 151         // load the symbol.
 152         //
 153         // Returns a pointer to the symbol on success, or NULL if an error
 154         // occurred or the symbol wasn't found.
 155
 156     void *GetSymbol(const wxString& name, bool *success = 0) const;
 157
 158 #if WXWIN_COMPATIBILITY_2_2
 159     operator bool() const { return IsLoaded(); }
 160 #endif
 161
 162     // return platform-specific name of dynamic library with proper extension
 163     // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
 164     static wxString CanonicalizeName(const wxString& name,
 165                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 166
 167     // return name of wxWindows plugin (adds compiler and version info
 168     // to the filename):
 169     static wxString CanonicalizePluginName(const wxString& name,
 170                                            wxPluginCategory cat);
 171
 172     // return plugin directory on platforms where it makes sense and empty
 173     // string on others:
 174     static wxString GetPluginsDirectory();
 175
 176 protected:
 177
 178         // Platform specific shared lib suffix.
 179
 180     static const wxChar *ms_dllext;
 181
 182         // the handle to DLL or NULL
 183
 184     wxDllType m_handle;
 185
 186         // no copy ctor/assignment operators
 187         // or we'd try to unload the library twice
 188
 189     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 190 };
 191
 192
 193 // ----------------------------------------------------------------------------
 194 // wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code
 195 // ----------------------------------------------------------------------------
 196
 197 #if WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
 198
 199 /*
 200     wxDllLoader is a class providing an interface similar to unix's dlopen().
 201     It is used by wxDynamicLibrary wxLibrary and manages the actual loading of
 202     DLLs and the resolving of symbols in them. There are no instances of this
 203     class, it simply serves as a namespace for its static member functions.
 204 */
 205 class WXDLLIMPEXP_BASE wxDllLoader
 206 {
 207 public:
 208     /*
 209       This function loads the shared library libname into memory.
 210
 211       libname may be either the full path to the file or just the filename in
 212       which case the library is searched for in all standard locations
 213       (use GetDllExt() to construct the filename)
 214
 215       if success pointer is not NULL, it will be filled with TRUE if everything
 216       went ok and FALSE otherwise
 217      */
 218     static wxDllType LoadLibrary(const wxString& name, bool *success = NULL);
 219
 220     /*
 221       This function unloads the shared library previously loaded with
 222       LoadLibrary
 223      */
 224     static void UnloadLibrary(wxDllType dll);
 225
 226     /*
 227        This function returns a valid handle for the main program
 228        itself or NULL if back linking is not supported by the current platform
 229        (e.g. Win32).
 230      */
 231     static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
 232
 233     /*
 234        This function resolves a symbol in a loaded DLL, such as a
 235        variable or function name.
 236
 237        dllHandle Handle of the DLL, as returned by LoadDll().
 238        name Name of the symbol.
 239
 240        Returns the pointer to the symbol or NULL on error.
 241      */
 242     static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0);
 243
 244     // return the standard DLL extension (with leading dot) for this platform
 245     static wxString GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
 246
 247 private:
 248
 249     wxDllLoader();                    // forbid construction of objects
 250 };
 251
 252
 253 // ----------------------------------------------------------------------------
 254 // wxLibrary
 255 // ----------------------------------------------------------------------------
 256
 257 #include "wx/hash.h"
 258
 259 class WXDLLIMPEXP_BASE wxLibrary : public wxObject
 260 {
 261 public:
 262     wxLibrary(wxDllType handle);
 263     virtual ~wxLibrary();
 264
 265     // Get a symbol from the dynamic library
 266     void *GetSymbol(const wxString& symbname);
 267
 268     // Create the object whose classname is "name"
 269     wxObject *CreateObject(const wxString& name);
 270
 271 protected:
 272     void PrepareClasses(wxClassInfo *first);
 273
 274     wxDllType m_handle;
 275
 276 public:
 277     wxHashTable classTable;
 278 };
 279
 280 // ----------------------------------------------------------------------------
 281 // wxLibraries
 282 // ----------------------------------------------------------------------------
 283
 284 class WXDLLIMPEXP_BASE wxLibraries
 285 {
 286 public:
 287     wxLibraries();
 288     ~wxLibraries();
 289
 290     // caller is responsible for deleting the returned pointer if !NULL
 291     wxLibrary *LoadLibrary(const wxString& basename);
 292
 293     wxObject *CreateObject(const wxString& name);
 294
 295 protected:
 296     wxList m_loaded;
 297 };
 298
 299 // ----------------------------------------------------------------------------
 300 // Global variables
 301 // ----------------------------------------------------------------------------
 302
 303 extern WXDLLIMPEXP_DATA_BASE(wxLibraries) wxTheLibraries;
 304
 305 #endif // WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
 306
 307 // ----------------------------------------------------------------------------
 308 // Interesting defines
 309 // ----------------------------------------------------------------------------
 310
 311 #define WXDLL_ENTRY_FUNCTION() \
 312 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
 313 const wxClassInfo *wxGetClassFirst() { \
 314   return wxClassInfo::GetFirst(); \
 315 }
 316
 317 #endif // wxUSE_DYNLIB_CLASS
 318
 319 #endif // _WX_DYNLIB_H__