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 #ifdef __WXMSW__
 249     // this function is useful for loading functions from the standard Windows
 250     // DLLs: such functions have an 'A' (in ANSI build) or 'W' (in Unicode, or
 251     // wide character build) suffix if they take string parameters
 252     static void *RawGetSymbolAorW(wxDllType handle, const wxString& name)
 253     {
 254         return RawGetSymbol
 255                (
 256                 handle,
 257                 name +
 258 #if wxUSE_UNICODE
 259                 L'W'
 260 #else
 261                 'A'
 262 #endif
 263                );
 264     }
 265
 266     void *GetSymbolAorW(const wxString& name) const
 267     {
 268         return RawGetSymbolAorW(m_handle, name);
 269     }
 270 #endif // __WXMSW__
 271
 272     // return all modules/shared libraries in the address space of this process
 273     //
 274     // returns an empty array if not implemented or an error occurred
 275     static wxDynamicLibraryDetailsArray ListLoaded();
 276
 277     // return platform-specific name of dynamic library with proper extension
 278     // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
 279     static wxString CanonicalizeName(const wxString& name,
 280                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 281
 282     // return name of wxWidgets plugin (adds compiler and version info
 283     // to the filename):
 284     static wxString
 285     CanonicalizePluginName(const wxString& name,
 286                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 287
 288     // return plugin directory on platforms where it makes sense and empty
 289     // string on others:
 290     static wxString GetPluginsDirectory();
 291
 292
 293 #if WXWIN_COMPATIBILITY_2_2
 294     operator bool() const { return IsLoaded(); }
 295 #endif
 296
 297 protected:
 298     // common part of GetSymbol() and HasSymbol()
 299     void *DoGetSymbol(const wxString& name, bool *success = 0) const;
 300
 301 #ifdef wxHAVE_DYNLIB_ERROR
 302     // log the error after a dlxxx() function failure
 303     static void Error();
 304 #endif // wxHAVE_DYNLIB_ERROR
 305
 306
 307     // platform specific shared lib suffix.
 308     static const wxChar *ms_dllext;
 309
 310     // the handle to DLL or NULL
 311     wxDllType m_handle;
 312
 313     // no copy ctor/assignment operators (or we'd try to unload the library
 314     // twice)
 315     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 316 };
 317
 318
 319 // ----------------------------------------------------------------------------
 320 // wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code
 321 // ----------------------------------------------------------------------------
 322
 323 #if WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
 324
 325 #include "wx/object.h"
 326
 327 /*
 328     wxDllLoader is a class providing an interface similar to unix's dlopen().
 329     It is used by wxDynamicLibrary wxLibrary and manages the actual loading of
 330     DLLs and the resolving of symbols in them. There are no instances of this
 331     class, it simply serves as a namespace for its static member functions.
 332 */
 333 class WXDLLIMPEXP_BASE wxDllLoader
 334 {
 335 public:
 336     /*
 337       This function loads the shared library libname into memory.
 338
 339       libname may be either the full path to the file or just the filename in
 340       which case the library is searched for in all standard locations
 341       (use GetDllExt() to construct the filename)
 342
 343       if success pointer is not NULL, it will be filled with true if everything
 344       went ok and false otherwise
 345      */
 346     static wxDllType LoadLibrary(const wxString& name, bool *success = NULL);
 347
 348     /*
 349       This function unloads the shared library previously loaded with
 350       LoadLibrary
 351      */
 352     static void UnloadLibrary(wxDllType dll);
 353
 354     /*
 355        This function returns a valid handle for the main program
 356        itself or NULL if back linking is not supported by the current platform
 357        (e.g. Win32).
 358      */
 359     static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
 360
 361     /*
 362        This function resolves a symbol in a loaded DLL, such as a
 363        variable or function name.
 364
 365        dllHandle Handle of the DLL, as returned by LoadDll().
 366        name Name of the symbol.
 367
 368        Returns the pointer to the symbol or NULL on error.
 369      */
 370     static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0);
 371
 372     // return the standard DLL extension (with leading dot) for this platform
 373     static wxString GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
 374
 375 private:
 376
 377     wxDllLoader();                    // forbid construction of objects
 378 };
 379
 380
 381 // ----------------------------------------------------------------------------
 382 // wxLibrary
 383 // ----------------------------------------------------------------------------
 384
 385 #include "wx/hash.h"
 386
 387 class WXDLLIMPEXP_BASE wxLibrary : public wxObject
 388 {
 389 public:
 390     wxLibrary(wxDllType handle);
 391     virtual ~wxLibrary();
 392
 393     // Get a symbol from the dynamic library
 394     void *GetSymbol(const wxString& symbname);
 395
 396     // Create the object whose classname is "name"
 397     wxObject *CreateObject(const wxString& name);
 398
 399 protected:
 400     void PrepareClasses(wxClassInfo *first);
 401
 402     wxDllType m_handle;
 403
 404 public:
 405     wxHashTable classTable;
 406 };
 407
 408 // ----------------------------------------------------------------------------
 409 // wxLibraries
 410 // ----------------------------------------------------------------------------
 411
 412 class WXDLLIMPEXP_BASE wxLibraries
 413 {
 414 public:
 415     wxLibraries();
 416     ~wxLibraries();
 417
 418     // caller is responsible for deleting the returned pointer if !NULL
 419     wxLibrary *LoadLibrary(const wxString& basename);
 420
 421     wxObject *CreateObject(const wxString& name);
 422
 423 protected:
 424     wxList m_loaded;
 425 };
 426
 427 // ----------------------------------------------------------------------------
 428 // Global variables
 429 // ----------------------------------------------------------------------------
 430
 431 extern WXDLLIMPEXP_DATA_BASE(wxLibraries) wxTheLibraries;
 432
 433 #endif // WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
 434
 435 // ----------------------------------------------------------------------------
 436 // Interesting defines
 437 // ----------------------------------------------------------------------------
 438
 439 #define WXDLL_ENTRY_FUNCTION() \
 440 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
 441 const wxClassInfo *wxGetClassFirst() { \
 442   return wxClassInfo::GetFirst(); \
 443 }
 444
 445 #endif // wxUSE_DYNLIB_CLASS
 446
 447 #endif // _WX_DYNLIB_H__