include/wx/dynload.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:         dynload.h
   3 // Purpose:      Dynamic loading framework
   4 // Author:       Ron Lee, David Falkinder, Vadim Zeitlin and a cast of 1000's
   5 //               (derived in part from dynlib.cpp (c) 1998 Guilhem Lavaux)
   6 // Modified by:
   7 // Created:      03/12/01
   8 // RCS-ID:       $Id$
   9 // Copyright:    (c) 2001 Ron Lee <ron@debian.org>
  10 // Licence:      wxWindows licence
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_DYNAMICLOADER_H__
  14 #define _WX_DYNAMICLOADER_H__
  15
  16 #if defined(__GNUG__) && !defined(__APPLE__)
  17 #pragma interface "dynload.h"
  18 #endif
  19
  20 // ----------------------------------------------------------------------------
  21 // headers
  22 // ----------------------------------------------------------------------------
  23
  24 #include "wx/defs.h"
  25
  26 #if wxUSE_DYNAMIC_LOADER
  27
  28 #include "wx/hashmap.h"
  29 #include "wx/module.h"
  30
  31 // FIXME: can this go in private.h or something too??
  32 #if defined(__WXPM__) || defined(__EMX__)
  33 #define INCL_DOS
  34 #include <os2.h>
  35 #endif
  36
  37 #ifdef __WXMSW__
  38 #include "wx/msw/private.h"
  39 #endif
  40
  41 class WXDLLIMPEXP_BASE wxPluginLibrary;
  42
  43 WX_DECLARE_EXPORTED_STRING_HASH_MAP(wxPluginLibrary *, wxDLManifest);
  44 typedef wxDLManifest wxDLImports;
  45
  46 // ----------------------------------------------------------------------------
  47 // conditional compilation
  48 // ----------------------------------------------------------------------------
  49
  50     // Note: WXPM/EMX has to be tested first, since we want to use
  51     // native version, even if configure detected presence of DLOPEN.
  52
  53 #if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__)
  54 typedef HMODULE             wxDllType;
  55 #elif defined(HAVE_DLOPEN)
  56 #include <dlfcn.h>
  57 typedef void               *wxDllType;
  58 #elif defined(HAVE_SHL_LOAD)
  59 #include <dl.h>
  60 typedef shl_t               wxDllType;
  61 #elif defined(__DARWIN__)
  62 typedef void               *wxDllType;
  63 #elif defined(__WXMAC__)
  64 typedef CFragConnectionID   wxDllType;
  65 #else
  66 #error "Dynamic Loading classes can't be compiled on this platform, sorry."
  67 #endif
  68
  69
  70 // ---------------------------------------------------------------------------
  71 // wxDynamicLibrary
  72 // ---------------------------------------------------------------------------
  73
  74 //FIXME:  This class isn't really common at all, it should be moved
  75 //        into platform dependent files.
  76
  77 // NOTE: this class is (deliberately) not virtual, do not attempt
  78 //       to use it polymorphically.
  79
  80 enum wxDLFlags
  81 {
  82     wxDL_LAZY       = 0x00000001,   // resolve undefined symbols at first use
  83     wxDL_NOW        = 0x00000002,   // resolve undefined symbols on load
  84     wxDL_GLOBAL     = 0x00000004,   // export extern symbols to subsequently
  85                                     // loaded libs.
  86     wxDL_VERBATIM   = 0x00000008,   // Attempt to load the supplied library
  87                                     // name without appending the usual dll
  88                                     // filename extension.
  89
  90     wxDL_NOSHARE    = 0x00000010,   // load new DLL, don't reuse already loaded
  91
  92     // FIXME: why? (VZ)
  93 #ifdef __osf__
  94     wxDL_DEFAULT    = wxDL_LAZY
  95 #else
  96     wxDL_DEFAULT    = wxDL_LAZY | wxDL_GLOBAL
  97 #endif
  98 };
  99
 100 enum wxDynamicLibraryCategory
 101 {
 102     wxDL_LIBRARY,       // standard library
 103     wxDL_MODULE,        // loadable module/plugin
 104 };
 105
 106 enum wxPluginCategory
 107 {
 108     wxDL_PLUGIN_GUI,    // plugin that uses GUI classes
 109     wxDL_PLUGIN_BASE,   // wxBase-only plugin
 110 };
 111
 112
 113 class WXDLLIMPEXP_BASE wxDynamicLibrary
 114 {
 115 public:
 116
 117         // return a valid handle for the main program itself or NULL if
 118         // back linking is not supported by the current platform (e.g. Win32)
 119
 120     static wxDllType         GetProgramHandle();
 121
 122         // return the platform standard DLL extension (with leading dot)
 123
 124     static const wxChar *GetDllExt() { return ms_dllext; }
 125
 126     wxDynamicLibrary() : m_handle(0) {}
 127     wxDynamicLibrary(wxString libname, int flags = wxDL_DEFAULT)
 128         : m_handle(0)
 129     {
 130         Load(libname, flags);
 131     }
 132     ~wxDynamicLibrary() { Unload(); }
 133
 134         // return TRUE if the library was loaded successfully
 135
 136     bool IsLoaded() const { return m_handle != 0; }
 137
 138         // load the library with the given name
 139         // (full or not), return TRUE on success
 140
 141     bool Load(wxString libname, int flags = wxDL_DEFAULT);
 142
 143         // detach the library object from its handle, i.e. prevent the object
 144         // from unloading the library in its dtor -- the caller is now
 145         // responsible for doing this
 146     wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
 147
 148         // unload the library, also done automatically in dtor
 149
 150     void Unload();
 151
 152         // Return the raw handle from dlopen and friends.
 153
 154     wxDllType GetLibHandle() const { return m_handle; }
 155
 156         // resolve a symbol in a loaded DLL, such as a variable or function
 157         // name.  'name' is the (possibly mangled) name of the symbol.
 158         // (use extern "C" to export unmangled names)
 159         //
 160         // Since it is perfectly valid for the returned symbol to actually be
 161         // NULL, that is not always indication of an error.  Pass and test the
 162         // parameter 'success' for a true indication of success or failure to
 163         // load the symbol.
 164         //
 165         // Returns a pointer to the symbol on success, or NULL if an error
 166         // occurred or the symbol wasn't found.
 167
 168     void *GetSymbol(const wxString& name, bool *success = 0) const;
 169
 170 #if WXWIN_COMPATIBILITY_2_2
 171     operator bool() const { return IsLoaded(); }
 172 #endif
 173
 174     // return platform-specific name of dynamic library with proper extension
 175     // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
 176     static wxString CanonicalizeName(const wxString& name,
 177                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 178
 179     // return name of wxWindows plugin (adds compiler and version info
 180     // to the filename):
 181     static wxString CanonicalizePluginName(const wxString& name,
 182                                            wxPluginCategory cat);
 183
 184     // return plugin directory on platforms where it makes sense and empty
 185     // string on others:
 186     static wxString GetPluginsDirectory();
 187
 188 protected:
 189
 190         // Platform specific shared lib suffix.
 191
 192     static const wxChar *ms_dllext;
 193
 194         // the handle to DLL or NULL
 195
 196     wxDllType m_handle;
 197
 198         // no copy ctor/assignment operators
 199         // or we'd try to unload the library twice
 200
 201     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 202 };
 203
 204
 205 // ---------------------------------------------------------------------------
 206 // wxPluginLibrary
 207 // ---------------------------------------------------------------------------
 208
 209 // NOTE: Do not attempt to use a base class pointer to this class.
 210 //       wxDL is not virtual and we deliberately hide some of it's
 211 //       methods here.
 212 //
 213 //       Unless you know exacty why you need to, you probably shouldn't
 214 //       instantiate this class directly anyway, use wxPluginManager
 215 //       instead.
 216
 217 class WXDLLIMPEXP_BASE wxPluginLibrary : public wxDynamicLibrary
 218 {
 219 public:
 220
 221     static wxDLImports* ms_classes;  // Static hash of all imported classes.
 222
 223     wxPluginLibrary( const wxString &libname, int flags = wxDL_DEFAULT );
 224     ~wxPluginLibrary();
 225
 226     wxPluginLibrary  *RefLib();
 227     bool              UnrefLib();
 228
 229         // These two are called by the PluginSentinel on (PLUGGABLE) object
 230         // creation/destruction.  There is usually no reason for the user to
 231         // call them directly.  We have to separate this from the link count,
 232         // since the two are not interchangeable.
 233
 234         // FIXME: for even better debugging PluginSentinel should register
 235         //        the name of the class created too, then we can state
 236         //        exactly which object was not destroyed which may be
 237         //        difficult to find otherwise.  Also this code should
 238         //        probably only be active in DEBUG mode, but let's just
 239         //        get it right first.
 240
 241     void  RefObj() { ++m_objcount; }
 242     void  UnrefObj()
 243     {
 244         wxASSERT_MSG( m_objcount > 0, _T("Too many objects deleted??") );
 245         --m_objcount;
 246     }
 247
 248         // Override/hide some base class methods
 249
 250     bool  IsLoaded() const { return m_linkcount > 0; }
 251     void  Unload() { UnrefLib(); }
 252
 253 private:
 254
 255     wxClassInfo    *m_before;       // sm_first before loading this lib
 256     wxClassInfo    *m_after;        // ..and after.
 257
 258     size_t          m_linkcount;    // Ref count of library link calls
 259     size_t          m_objcount;     // ..and (pluggable) object instantiations.
 260     wxModuleList    m_wxmodules;    // any wxModules that we initialised.
 261
 262     void    UpdateClassInfo();      // Update the wxClassInfo table
 263     void    RestoreClassInfo();     // Restore the original wxClassInfo state.
 264     void    RegisterModules();      // Init any wxModules in the lib.
 265     void    UnregisterModules();    // Cleanup any wxModules we installed.
 266
 267     DECLARE_NO_COPY_CLASS(wxPluginLibrary)
 268 };
 269
 270
 271 class WXDLLIMPEXP_BASE wxPluginManager
 272 {
 273 public:
 274
 275         // Static accessors.
 276
 277     static wxPluginLibrary    *LoadLibrary( const wxString &libname,
 278                                             int flags = wxDL_DEFAULT );
 279     static bool                UnloadLibrary(const wxString &libname);
 280
 281         // This is used by wxDllLoader.  It's wrapped in the compatibility
 282         // macro because it's of arguable use outside of that.
 283
 284 #if WXWIN_COMPATIBILITY_2_2
 285     static wxPluginLibrary *GetObjectFromHandle(wxDllType handle);
 286 #endif
 287
 288         // Instance methods.
 289
 290     wxPluginManager() : m_entry(NULL) {};
 291     wxPluginManager(const wxString &libname, int flags = wxDL_DEFAULT)
 292     {
 293         Load(libname, flags);
 294     }
 295     ~wxPluginManager() { Unload(); }
 296
 297     bool   Load(const wxString &libname, int flags = wxDL_DEFAULT);
 298     void   Unload();
 299
 300     bool   IsLoaded() const { return m_entry && m_entry->IsLoaded(); }
 301     void  *GetSymbol(const wxString &symbol, bool *success = 0)
 302     {
 303         return m_entry->GetSymbol( symbol, success );
 304     }
 305
 306     static void CreateManifest() { ms_manifest = new wxDLManifest(wxKEY_STRING); }
 307     static void ClearManifest() { delete ms_manifest; ms_manifest = NULL; }
 308
 309 private:
 310     // return the pointer to the entry for the library with given name in
 311     // ms_manifest or NULL if none
 312     static wxPluginLibrary *FindByName(const wxString& name)
 313     {
 314         const wxDLManifest::iterator i = ms_manifest->find(name);
 315
 316         return i == ms_manifest->end() ? NULL : i->second;
 317     }
 318
 319     static wxDLManifest* ms_manifest;  // Static hash of loaded libs.
 320     wxPluginLibrary*     m_entry;      // Cache our entry in the manifest.
 321
 322     // We could allow this class to be copied if we really
 323     // wanted to, but not without modification.
 324     DECLARE_NO_COPY_CLASS(wxPluginManager)
 325 };
 326
 327
 328 // ---------------------------------------------------------------------------
 329 // wxDllLoader
 330 // ---------------------------------------------------------------------------
 331
 332     //  Cross platform wrapper for dlopen and friends.
 333     //  There are no instances of this class, it simply
 334     //  serves as a namespace for its static member functions.
 335
 336 #if WXWIN_COMPATIBILITY_2_2
 337 class WXDLLIMPEXP_BASE wxDllLoader
 338 {
 339 public:
 340
 341     static wxDllType    LoadLibrary(const wxString& name, bool *success = NULL);
 342     static void         UnloadLibrary(wxDllType dll);
 343
 344     static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
 345
 346     static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0);
 347
 348     static wxString GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
 349
 350 private:
 351
 352     wxDllLoader();                    // forbid construction of objects
 353 };
 354 #endif
 355
 356 #endif  // wxUSE_DYNAMIC_LOADER
 357 #endif  // _WX_DYNAMICLOADER_H__
 358