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(NO_GCC_PRAGMA)
  16 #   pragma interface "dynlib.h"
  17 #endif
  18
  19 #include "wx/defs.h"
  20
  21 #if wxUSE_DYNLIB_CLASS
  22
  23 #include "wx/string.h"
  24 #include "wx/dynarray.h"
  25
  26 // FIXME: can this go in private.h or something too??
  27 #if defined(__WXPM__) || defined(__EMX__)
  28 #define INCL_DOS
  29 #include <os2.h>
  30 #endif
  31
  32 #ifdef __WXMSW__
  33 #include "wx/msw/private.h"
  34 #endif
  35
  36 #if defined(HAVE_DLERROR) && !defined(__EMX__)
  37     #define wxHAVE_DYNLIB_ERROR
  38 #endif
  39
  40 class WXDLLIMPEXP_BASE wxDynamicLibraryDetailsCreator;
  41
  42 // ----------------------------------------------------------------------------
  43 // conditional compilation
  44 // ----------------------------------------------------------------------------
  45
  46 // Note: WXPM/EMX has to be tested first, since we want to use
  47 // native version, even if configure detected presence of DLOPEN.
  48 #if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__)
  49     typedef HMODULE             wxDllType;
  50 #elif defined(HAVE_DLOPEN)
  51     #include <dlfcn.h>
  52     typedef void               *wxDllType;
  53 #elif defined(HAVE_SHL_LOAD)
  54     #include <dl.h>
  55     typedef shl_t               wxDllType;
  56 #elif defined(__DARWIN__)
  57     typedef void               *wxDllType;
  58 #elif defined(__WXMAC__)
  59     #include <CodeFragments.h>
  60     typedef CFragConnectionID   wxDllType;
  61 #else
  62     #error "Dynamic Loading classes can't be compiled on this platform, sorry."
  63 #endif
  64
  65 // ----------------------------------------------------------------------------
  66 // constants
  67 // ----------------------------------------------------------------------------
  68
  69 enum wxDLFlags
  70 {
  71     wxDL_LAZY       = 0x00000001,   // resolve undefined symbols at first use
  72                                     // (only works on some Unix versions)
  73     wxDL_NOW        = 0x00000002,   // resolve undefined symbols on load
  74                                     // (default, always the case under Win32)
  75     wxDL_GLOBAL     = 0x00000004,   // export extern symbols to subsequently
  76                                     // loaded libs.
  77     wxDL_VERBATIM   = 0x00000008,   // attempt to load the supplied library
  78                                     // name without appending the usual dll
  79                                     // filename extension.
  80     wxDL_NOSHARE    = 0x00000010,   // load new DLL, don't reuse already loaded
  81                                     // (only for wxPluginManager)
  82
  83     wxDL_DEFAULT    = wxDL_NOW      // default flags correspond to Win32
  84 };
  85
  86 enum wxDynamicLibraryCategory
  87 {
  88     wxDL_LIBRARY,       // standard library
  89     wxDL_MODULE         // loadable module/plugin
  90 };
  91
  92 enum wxPluginCategory
  93 {
  94     wxDL_PLUGIN_GUI,    // plugin that uses GUI classes
  95     wxDL_PLUGIN_BASE    // wxBase-only plugin
  96 };
  97
  98 // ----------------------------------------------------------------------------
  99 // macros
 100 // ----------------------------------------------------------------------------
 101
 102 // when loading a function from a DLL you always have to cast the returned
 103 // "void *" pointer to the correct type and, even more annoyingly, you have to
 104 // repeat this type twice if you want to declare and define a function pointer
 105 // all in one line
 106 //
 107 // this macro makes this slightly less painful by allowing you to specify the
 108 // type only once, as the first parameter, and creating a variable of this type
 109 // called "pfn<name>" initialized with the "name" from the "dynlib"
 110 #define wxDYNLIB_FUNCTION(type, name, dynlib) \
 111     type pfn ## name = (type)(dynlib).GetSymbol(_T(#name))
 112
 113 // ----------------------------------------------------------------------------
 114 // wxDynamicLibraryDetails: contains details about a loaded wxDynamicLibrary
 115 // ----------------------------------------------------------------------------
 116
 117 class WXDLLIMPEXP_BASE wxDynamicLibraryDetails
 118 {
 119 public:
 120     // ctor, normally never used as these objects are only created by
 121     // wxDynamicLibrary::ListLoaded()
 122     wxDynamicLibraryDetails() { m_address = NULL; m_length = 0; }
 123
 124     // get the (base) name
 125     wxString GetName() const { return m_name; }
 126
 127     // get the full path of this object
 128     wxString GetPath() const { return m_path; }
 129
 130     // get the load address and the extent, return true if this information is
 131     // available
 132     bool GetAddress(void **addr, size_t *len) const
 133     {
 134         if ( !m_address )
 135             return false;
 136
 137         if ( addr )
 138             *addr = m_address;
 139         if ( len )
 140             *len = m_length;
 141
 142         return true;
 143     }
 144
 145     // return the version of the DLL (may be empty if no version info)
 146     wxString GetVersion() const
 147     {
 148         return m_version;
 149     }
 150
 151 private:
 152     wxString m_name,
 153              m_path,
 154              m_version;
 155
 156     void *m_address;
 157     size_t m_length;
 158
 159     friend class wxDynamicLibraryDetailsCreator;
 160 };
 161
 162 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxDynamicLibraryDetails,
 163                                   wxDynamicLibraryDetailsArray,
 164                                   WXDLLIMPEXP_BASE);
 165
 166 // ----------------------------------------------------------------------------
 167 // wxDynamicLibrary: represents a handle to a DLL/shared object
 168 // ----------------------------------------------------------------------------
 169
 170 class WXDLLIMPEXP_BASE wxDynamicLibrary
 171 {
 172 public:
 173     // return a valid handle for the main program itself or NULL if back
 174     // linking is not supported by the current platform (e.g. Win32)
 175     static wxDllType         GetProgramHandle();
 176
 177     // return the platform standard DLL extension (with leading dot)
 178     static const wxChar *GetDllExt() { return ms_dllext; }
 179
 180     wxDynamicLibrary() : m_handle(0) { }
 181     wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT)
 182         : m_handle(0)
 183     {
 184         Load(libname, flags);
 185     }
 186
 187     // NOTE: this class is (deliberately) not virtual, do not attempt
 188     //       to use it polymorphically.
 189     ~wxDynamicLibrary() { Unload(); }
 190
 191     // return true if the library was loaded successfully
 192     bool IsLoaded() const { return m_handle != 0; }
 193
 194     // load the library with the given name (full or not), return true if ok
 195     bool Load(const wxString& libname, int flags = wxDL_DEFAULT);
 196
 197     // raw function for loading dynamic libs: always behaves as if
 198     // wxDL_VERBATIM were specified and doesn't log error message if the
 199     // library couldn't be loaded but simply returns NULL
 200     static wxDllType RawLoad(const wxString& libname, int flags = wxDL_DEFAULT);
 201
 202     // detach the library object from its handle, i.e. prevent the object from
 203     // unloading the library in its dtor -- the caller is now responsible for
 204     // doing this
 205     wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
 206
 207     // unload the given library handle (presumably returned by Detach() before)
 208     static void Unload(wxDllType handle);
 209
 210     // unload the library, also done automatically in dtor
 211     void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } }
 212
 213     // Return the raw handle from dlopen and friends.
 214     wxDllType GetLibHandle() const { return m_handle; }
 215
 216     // check if the given symbol is present in the library, useful to verify if
 217     // a loadable module is our plugin, for example, without provoking error
 218     // messages from GetSymbol()
 219     bool HasSymbol(const wxString& name) const
 220     {
 221         bool ok;
 222         DoGetSymbol(name, &ok);
 223         return ok;
 224     }
 225
 226     // resolve a symbol in a loaded DLL, such as a variable or function name.
 227     // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to
 228     // export unmangled names)
 229     //
 230     // Since it is perfectly valid for the returned symbol to actually be NULL,
 231     // that is not always indication of an error.  Pass and test the parameter
 232     // 'success' for a true indication of success or failure to load the
 233     // symbol.
 234     //
 235     // Returns a pointer to the symbol on success, or NULL if an error occurred
 236     // or the symbol wasn't found.
 237     void *GetSymbol(const wxString& name, bool *success = NULL) const;
 238
 239     // low-level version of GetSymbol()
 240     static void *RawGetSymbol(wxDllType handle, const wxString& name);
 241     void *RawGetSymbol(const wxString& name) const
 242     {
 243 #if defined (__WXPM__) || defined(__EMX__)
 244         return GetSymbol(name);
 245 #else
 246         return RawGetSymbol(m_handle, name);
 247 #endif
 248     }
 249
 250     // return all modules/shared libraries in the address space of this process
 251     //
 252     // returns an empty array if not implemented or an error occured
 253     static wxDynamicLibraryDetailsArray ListLoaded();
 254
 255     // return platform-specific name of dynamic library with proper extension
 256     // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
 257     static wxString CanonicalizeName(const wxString& name,
 258                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 259
 260     // return name of wxWidgets plugin (adds compiler and version info
 261     // to the filename):
 262     static wxString
 263     CanonicalizePluginName(const wxString& name,
 264                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 265
 266     // return plugin directory on platforms where it makes sense and empty
 267     // string on others:
 268     static wxString GetPluginsDirectory();
 269
 270
 271 #if WXWIN_COMPATIBILITY_2_2
 272     operator bool() const { return IsLoaded(); }
 273 #endif
 274
 275 protected:
 276     // common part of GetSymbol() and HasSymbol()
 277     void *DoGetSymbol(const wxString& name, bool *success = 0) const;
 278
 279 #ifdef wxHAVE_DYNLIB_ERROR
 280     // log the error after a dlxxx() function failure
 281     static void Error();
 282 #endif // wxHAVE_DYNLIB_ERROR
 283
 284
 285     // platform specific shared lib suffix.
 286     static const wxChar *ms_dllext;
 287
 288     // the handle to DLL or NULL
 289     wxDllType m_handle;
 290
 291     // no copy ctor/assignment operators (or we'd try to unload the library
 292     // twice)
 293     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 294 };
 295
 296
 297 // ----------------------------------------------------------------------------
 298 // wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code
 299 // ----------------------------------------------------------------------------
 300
 301 #if WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
 302
 303 /*
 304     wxDllLoader is a class providing an interface similar to unix's dlopen().
 305     It is used by wxDynamicLibrary wxLibrary and manages the actual loading of
 306     DLLs and the resolving of symbols in them. There are no instances of this
 307     class, it simply serves as a namespace for its static member functions.
 308 */
 309 class WXDLLIMPEXP_BASE wxDllLoader
 310 {
 311 public:
 312     /*
 313       This function loads the shared library libname into memory.
 314
 315       libname may be either the full path to the file or just the filename in
 316       which case the library is searched for in all standard locations
 317       (use GetDllExt() to construct the filename)
 318
 319       if success pointer is not NULL, it will be filled with true if everything
 320       went ok and false otherwise
 321      */
 322     static wxDllType LoadLibrary(const wxString& name, bool *success = NULL);
 323
 324     /*
 325       This function unloads the shared library previously loaded with
 326       LoadLibrary
 327      */
 328     static void UnloadLibrary(wxDllType dll);
 329
 330     /*
 331        This function returns a valid handle for the main program
 332        itself or NULL if back linking is not supported by the current platform
 333        (e.g. Win32).
 334      */
 335     static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
 336
 337     /*
 338        This function resolves a symbol in a loaded DLL, such as a
 339        variable or function name.
 340
 341        dllHandle Handle of the DLL, as returned by LoadDll().
 342        name Name of the symbol.
 343
 344        Returns the pointer to the symbol or NULL on error.
 345      */
 346     static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0);
 347
 348     // return the standard DLL extension (with leading dot) for this platform
 349     static wxString GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
 350
 351 private:
 352
 353     wxDllLoader();                    // forbid construction of objects
 354 };
 355
 356
 357 // ----------------------------------------------------------------------------
 358 // wxLibrary
 359 // ----------------------------------------------------------------------------
 360
 361 #include "wx/hash.h"
 362
 363 class WXDLLIMPEXP_BASE wxLibrary : public wxObject
 364 {
 365 public:
 366     wxLibrary(wxDllType handle);
 367     virtual ~wxLibrary();
 368
 369     // Get a symbol from the dynamic library
 370     void *GetSymbol(const wxString& symbname);
 371
 372     // Create the object whose classname is "name"
 373     wxObject *CreateObject(const wxString& name);
 374
 375 protected:
 376     void PrepareClasses(wxClassInfo *first);
 377
 378     wxDllType m_handle;
 379
 380 public:
 381     wxHashTable classTable;
 382 };
 383
 384 // ----------------------------------------------------------------------------
 385 // wxLibraries
 386 // ----------------------------------------------------------------------------
 387
 388 class WXDLLIMPEXP_BASE wxLibraries
 389 {
 390 public:
 391     wxLibraries();
 392     ~wxLibraries();
 393
 394     // caller is responsible for deleting the returned pointer if !NULL
 395     wxLibrary *LoadLibrary(const wxString& basename);
 396
 397     wxObject *CreateObject(const wxString& name);
 398
 399 protected:
 400     wxList m_loaded;
 401 };
 402
 403 // ----------------------------------------------------------------------------
 404 // Global variables
 405 // ----------------------------------------------------------------------------
 406
 407 extern WXDLLIMPEXP_DATA_BASE(wxLibraries) wxTheLibraries;
 408
 409 #endif // WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
 410
 411 // ----------------------------------------------------------------------------
 412 // Interesting defines
 413 // ----------------------------------------------------------------------------
 414
 415 #define WXDLL_ENTRY_FUNCTION() \
 416 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
 417 const wxClassInfo *wxGetClassFirst() { \
 418   return wxClassInfo::GetFirst(); \
 419 }
 420
 421 #endif // wxUSE_DYNLIB_CLASS
 422
 423 #endif // _WX_DYNLIB_H__