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 license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_DYNAMICLOADER_H__
  14 #define _WX_DYNAMICLOADER_H__
  15
  16 #ifdef __GNUG__
  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/hash.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 // Ugh, I'd much rather this was typesafe, but no time
  42 // to rewrite wxHashTable right now..
  43
  44 typedef wxHashTable wxDLManifest;
  45 typedef wxHashTable wxDLImports;
  46
  47 // ----------------------------------------------------------------------------
  48 // conditional compilation
  49 // ----------------------------------------------------------------------------
  50
  51     // Note: WXPM/EMX has to be tested first, since we want to use
  52     // native version, even if configure detected presence of DLOPEN.
  53
  54 #if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__)
  55 typedef HMODULE             wxDllType;
  56 #elif defined(HAVE_DLOPEN)
  57 #include <dlfcn.h>
  58 typedef void               *wxDllType;
  59 #elif defined(HAVE_SHL_LOAD)
  60 #include <dl.h>
  61 typedef shl_t               wxDllType;
  62 #elif defined(__DARWIN__)
  63 typedef void               *wxDllType;
  64 #elif defined(__WXMAC__)
  65 typedef CFragConnectionID   wxDllType;
  66 #else
  67 #error "Dynamic Loading classes can't be compiled on this platform, sorry."
  68 #endif
  69
  70
  71 // ---------------------------------------------------------------------------
  72 // wxDynamicLibrary
  73 // ---------------------------------------------------------------------------
  74
  75 //FIXME:  This class isn't really common at all, it should be moved
  76 //        into platform dependent files.
  77
  78 // NOTE: this class is (deliberately) not virtual, do not attempt
  79 //       to use it polymorphically.
  80
  81 enum wxDLFlags
  82 {
  83     wxDL_LAZY       = 0x00000001,   // resolve undefined symbols at first use
  84     wxDL_NOW        = 0x00000002,   // resolve undefined symbols on load
  85     wxDL_GLOBAL     = 0x00000004,   // export extern symbols to subsequently
  86                                     // loaded libs.
  87     wxDL_VERBATIM   = 0x00000008,   // Attempt to load the supplied library
  88                                     // name without appending the usual dll
  89                                     // filename extension.
  90 #ifdef __osf__
  91     wxDL_DEFAULT    = wxDL_LAZY
  92 #else
  93     wxDL_DEFAULT    = wxDL_LAZY | wxDL_GLOBAL
  94 #endif
  95 };
  96
  97
  98 class WXDLLEXPORT wxDynamicLibrary
  99 {
 100 public:
 101
 102         // return a valid handle for the main program itself or NULL if
 103         // back linking is not supported by the current platform (e.g. Win32)
 104
 105     static wxDllType         GetProgramHandle();
 106
 107         // return the platform standard DLL extension (with leading dot)
 108
 109     static const wxString   &GetDllExt() { return ms_dllext; }
 110
 111     wxDynamicLibrary() : m_handle(0) {}
 112     wxDynamicLibrary(wxString libname, wxDLFlags flags = wxDL_DEFAULT)
 113         : m_handle(0)
 114     {
 115         Load(libname, flags);
 116     }
 117     ~wxDynamicLibrary() { Unload(); }
 118
 119         // return TRUE if the library was loaded successfully
 120
 121     bool IsLoaded() const { return m_handle != 0; }
 122
 123         // load the library with the given name
 124         // (full or not), return TRUE on success
 125
 126     bool Load(wxString libname, wxDLFlags flags = wxDL_DEFAULT);
 127
 128         // unload the library, also done automatically in dtor
 129
 130     void Unload();
 131
 132         // Return the raw handle from dlopen and friends.
 133
 134     wxDllType GetLibHandle() const { return m_handle; }
 135
 136         // resolve a symbol in a loaded DLL, such as a variable or function
 137         // name.  'name' is the (possibly mangled) name of the symbol.
 138         // (use extern "C" to export unmangled names)
 139         //
 140         // Since it is perfectly valid for the returned symbol to actually be
 141         // NULL, that is not always indication of an error.  Pass and test the
 142         // parameter 'success' for a true indication of success or failure to
 143         // load the symbol.
 144         //
 145         // Returns a pointer to the symbol on success, or NULL if an error
 146         // occurred or the symbol wasn't found.
 147
 148     void *GetSymbol(const wxString& name, bool *success = 0) const;
 149
 150 #if WXWIN_COMPATIBILITY_2_2
 151     operator bool() const { return IsLoaded(); }
 152 #endif
 153
 154 protected:
 155
 156         // Platform specific shared lib suffix.
 157
 158     static const wxString ms_dllext;
 159
 160         // the handle to DLL or NULL
 161
 162     wxDllType m_handle;
 163
 164         // no copy ctor/assignment operators
 165         // or we'd try to unload the library twice
 166
 167 DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 168 };
 169
 170
 171 // ---------------------------------------------------------------------------
 172 // wxPluginLibrary
 173 // ---------------------------------------------------------------------------
 174
 175 // NOTE: Do not attempt to use a base class pointer to this class.
 176 //       wxDL is not virtual and we deliberately hide some of it's
 177 //       methods here.
 178 //
 179 //       Unless you know exacty why you need to, you probably shouldn't
 180 //       instantiate this class directly anyway, use wxPluginManager
 181 //       instead.
 182
 183 class WXDLLEXPORT wxPluginLibrary : public wxDynamicLibrary
 184 {
 185 public:
 186
 187     static wxDLImports ms_classes;  // Static hash of all imported classes.
 188
 189     wxPluginLibrary( const wxString &libname, wxDLFlags flags = wxDL_DEFAULT );
 190     ~wxPluginLibrary();
 191
 192     wxPluginLibrary  *RefLib() { ++m_linkcount; return this; }
 193     bool              UnrefLib();
 194
 195         // These two are called by the PluginSentinel on (PLUGGABLE) object
 196         // creation/destruction.  There is usually no reason for the user to
 197         // call them directly.  We have to separate this from the link count,
 198         // since the two are not interchangeable.
 199
 200         // FIXME: for even better debugging PluginSentinel should register
 201         //        the name of the class created too, then we can state
 202         //        exactly which object was not destroyed which may be
 203         //        difficult to find otherwise.  Also this code should
 204         //        probably only be active in DEBUG mode, but let's just
 205         //        get it right first.
 206
 207     void  RefObj() { ++m_objcount; }
 208     void  UnrefObj()
 209     {
 210         wxASSERT_MSG( m_objcount > 0, _T("Too many objects deleted??") );
 211         --m_objcount;
 212     }
 213
 214         // Override/hide some base class methods
 215
 216     bool  IsLoaded() const { return m_linkcount > 0; }
 217     void  Unload() { UnrefLib(); }
 218
 219 private:
 220
 221     wxClassInfo    *m_before;       // sm_first before loading this lib
 222     wxClassInfo    *m_after;        // ..and after.
 223
 224     size_t          m_linkcount;    // Ref count of library link calls
 225     size_t          m_objcount;     // ..and (pluggable) object instantiations.
 226     wxModuleList    m_wxmodules;    // any wxModules that we initialised.
 227
 228     void    UpdateClassInfo();      // Update the wxClassInfo table
 229     void    RestoreClassInfo();     // Restore the original wxClassInfo state.
 230     void    RegisterModules();      // Init any wxModules in the lib.
 231     void    UnregisterModules();    // Cleanup any wxModules we installed.
 232
 233 DECLARE_NO_COPY_CLASS(wxPluginLibrary)
 234 };
 235
 236
 237 class WXDLLEXPORT wxPluginManager
 238 {
 239 public:
 240
 241         // Static accessors.
 242
 243     static wxPluginLibrary    *LoadLibrary( const wxString &libname,
 244                                             wxDLFlags flags = wxDL_DEFAULT );
 245     static bool                UnloadLibrary(const wxString &libname);
 246
 247         // This is used by wxDllLoader.  It's wrapped in the compatibility
 248         // macro because it's of arguable use outside of that.
 249
 250 #if WXWIN_COMPATIBILITY_2_2
 251     static wxPluginLibrary *GetObjectFromHandle(wxDllType handle);
 252 #endif
 253
 254         // Instance methods.
 255
 256     wxPluginManager() : m_entry(0) {};
 257     wxPluginManager(const wxString &libname, wxDLFlags flags = wxDL_DEFAULT)
 258     {
 259         Load(libname, flags);
 260     }
 261     ~wxPluginManager() { Unload(); }
 262
 263     bool   Load(const wxString &libname, wxDLFlags flags = wxDL_DEFAULT);
 264     void   Unload();
 265
 266     bool   IsLoaded() const { return m_entry && m_entry->IsLoaded(); }
 267     void  *GetSymbol(const wxString &symbol, bool *success = 0)
 268     {
 269         return m_entry->GetSymbol( symbol, success );
 270     }
 271
 272 private:
 273
 274     static wxDLManifest  ms_manifest;  // Static hash of loaded libs.
 275     wxPluginLibrary     *m_entry;      // Cache our entry in the manifest.
 276
 277     // We could allow this class to be copied if we really
 278     // wanted to, but not without modification.
 279
 280 DECLARE_NO_COPY_CLASS(wxPluginManager)
 281 };
 282
 283
 284 // ---------------------------------------------------------------------------
 285 // wxDllLoader
 286 // ---------------------------------------------------------------------------
 287
 288     //  Cross platform wrapper for dlopen and friends.
 289     //  There are no instances of this class, it simply
 290     //  serves as a namespace for its static member functions.
 291
 292 #if WXWIN_COMPATIBILITY_2_2
 293 class WXDLLEXPORT wxDllLoader
 294 {
 295 public:
 296
 297     static wxDllType    LoadLibrary(const wxString& name);
 298     static void         UnloadLibrary(wxDllType dll);
 299
 300     static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
 301
 302     static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0);
 303
 304     static const wxString &GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
 305
 306 private:
 307
 308     wxDllLoader();                    // forbid construction of objects
 309 };
 310 #endif
 311
 312
 313 #endif  // wxUSE_DYNAMIC_LOADER
 314 #endif  // _WX_DYNAMICLOADER_H__
 315
 316 // vi:sts=4:sw=4:et