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