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 #include "wx/defs.h"
  16
  17 #if wxUSE_DYNLIB_CLASS
  18
  19 #include "wx/string.h"
  20 #include "wx/dynarray.h"
  21
  22 #if defined(__OS2__) || defined(__EMX__)
  23 #include "wx/os2/private.h"
  24 #endif
  25
  26 #ifdef __WXMSW__
  27 #include "wx/msw/private.h"
  28 #endif
  29
  30 // note that we have our own dlerror() implementation under Darwin
  31 #if (defined(HAVE_DLERROR) && !defined(__EMX__)) || defined(__DARWIN__)
  32     #define wxHAVE_DYNLIB_ERROR
  33 #endif
  34
  35 class WXDLLIMPEXP_FWD_BASE wxDynamicLibraryDetailsCreator;
  36
  37 // ----------------------------------------------------------------------------
  38 // conditional compilation
  39 // ----------------------------------------------------------------------------
  40
  41 // Note: __OS2__/EMX has to be tested first, since we want to use
  42 // native version, even if configure detected presence of DLOPEN.
  43 #if defined(__OS2__) || defined(__EMX__) || defined(__WINDOWS__)
  44     typedef HMODULE             wxDllType;
  45 #elif defined(HAVE_DLOPEN)
  46     #include <dlfcn.h>
  47     typedef void               *wxDllType;
  48 #elif defined(HAVE_SHL_LOAD)
  49     #include <dl.h>
  50     typedef shl_t               wxDllType;
  51 #elif defined(__DARWIN__)
  52     typedef void               *wxDllType;
  53 #elif defined(__WXMAC__)
  54     #include <CodeFragments.h>
  55     typedef CFragConnectionID   wxDllType;
  56 #else
  57     #error "Dynamic Loading classes can't be compiled on this platform, sorry."
  58 #endif
  59
  60 // ----------------------------------------------------------------------------
  61 // constants
  62 // ----------------------------------------------------------------------------
  63
  64 enum wxDLFlags
  65 {
  66     wxDL_LAZY       = 0x00000001,   // resolve undefined symbols at first use
  67                                     // (only works on some Unix versions)
  68     wxDL_NOW        = 0x00000002,   // resolve undefined symbols on load
  69                                     // (default, always the case under Win32)
  70     wxDL_GLOBAL     = 0x00000004,   // export extern symbols to subsequently
  71                                     // loaded libs.
  72     wxDL_VERBATIM   = 0x00000008,   // attempt to load the supplied library
  73                                     // name without appending the usual dll
  74                                     // filename extension.
  75     wxDL_NOSHARE    = 0x00000010,   // load new DLL, don't reuse already loaded
  76                                     // (only for wxPluginManager)
  77
  78     wxDL_DEFAULT    = wxDL_NOW      // default flags correspond to Win32
  79 };
  80
  81 enum wxDynamicLibraryCategory
  82 {
  83     wxDL_LIBRARY,       // standard library
  84     wxDL_MODULE         // loadable module/plugin
  85 };
  86
  87 enum wxPluginCategory
  88 {
  89     wxDL_PLUGIN_GUI,    // plugin that uses GUI classes
  90     wxDL_PLUGIN_BASE    // wxBase-only plugin
  91 };
  92
  93 // ----------------------------------------------------------------------------
  94 // macros
  95 // ----------------------------------------------------------------------------
  96
  97 // when loading a function from a DLL you always have to cast the returned
  98 // "void *" pointer to the correct type and, even more annoyingly, you have to
  99 // repeat this type twice if you want to declare and define a function pointer
 100 // all in one line
 101 //
 102 // this macro makes this slightly less painful by allowing you to specify the
 103 // type only once, as the first parameter, and creating a variable of this type
 104 // called "pfn<name>" initialized with the "name" from the "dynlib"
 105 #define wxDYNLIB_FUNCTION(type, name, dynlib) \
 106     type pfn ## name = (type)(dynlib).GetSymbol(_T(#name))
 107
 108
 109 // the following macros can be used to redirect a whole
 110 // library to a class and check at run-time if the the
 111 // library is present and contains all required methods.
 112
 113 #define wxDL_METHOD_DEFINE( rettype, name, args, shortargs, defret ) \
 114     typedef rettype (* name ## Type) args ; \
 115     name ## Type pfn_ ## name; \
 116     rettype name args \
 117     { if (m_ok) return pfn_ ## name shortargs ; return defret; }
 118
 119 #define wxDL_VOIDMETHOD_DEFINE( name, args, shortargs ) \
 120     typedef void (* name ## Type) args ; \
 121     name ## Type pfn_ ## name; \
 122     void name args \
 123     { if (m_ok) pfn_ ## name shortargs ; }
 124
 125 #define wxDL_METHOD_LOAD( lib, name, success ) \
 126     pfn_ ## name = (name ## Type) lib->GetSymbol( wxT(#name), &success ); \
 127     if (!success) return;
 128
 129 // ----------------------------------------------------------------------------
 130 // wxDynamicLibraryDetails: contains details about a loaded wxDynamicLibrary
 131 // ----------------------------------------------------------------------------
 132
 133 class WXDLLIMPEXP_BASE wxDynamicLibraryDetails
 134 {
 135 public:
 136     // ctor, normally never used as these objects are only created by
 137     // wxDynamicLibrary::ListLoaded()
 138     wxDynamicLibraryDetails() { m_address = NULL; m_length = 0; }
 139
 140     // get the (base) name
 141     wxString GetName() const { return m_name; }
 142
 143     // get the full path of this object
 144     wxString GetPath() const { return m_path; }
 145
 146     // get the load address and the extent, return true if this information is
 147     // available
 148     bool GetAddress(void **addr, size_t *len) const
 149     {
 150         if ( !m_address )
 151             return false;
 152
 153         if ( addr )
 154             *addr = m_address;
 155         if ( len )
 156             *len = m_length;
 157
 158         return true;
 159     }
 160
 161     // return the version of the DLL (may be empty if no version info)
 162     wxString GetVersion() const
 163     {
 164         return m_version;
 165     }
 166
 167 private:
 168     wxString m_name,
 169              m_path,
 170              m_version;
 171
 172     void *m_address;
 173     size_t m_length;
 174
 175     friend class wxDynamicLibraryDetailsCreator;
 176 };
 177
 178 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxDynamicLibraryDetails,
 179                                   wxDynamicLibraryDetailsArray,
 180                                   WXDLLIMPEXP_BASE);
 181
 182 // ----------------------------------------------------------------------------
 183 // wxDynamicLibrary: represents a handle to a DLL/shared object
 184 // ----------------------------------------------------------------------------
 185
 186 class WXDLLIMPEXP_BASE wxDynamicLibrary
 187 {
 188 public:
 189     // return a valid handle for the main program itself or NULL if back
 190     // linking is not supported by the current platform (e.g. Win32)
 191     static wxDllType         GetProgramHandle();
 192
 193     // return the platform standard DLL extension (with leading dot)
 194     static const wxString& GetDllExt() { return ms_dllext; }
 195
 196     wxDynamicLibrary() : m_handle(0) { }
 197     wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT)
 198         : m_handle(0)
 199     {
 200         Load(libname, flags);
 201     }
 202
 203     // NOTE: this class is (deliberately) not virtual, do not attempt
 204     //       to use it polymorphically.
 205     ~wxDynamicLibrary() { Unload(); }
 206
 207     // return true if the library was loaded successfully
 208     bool IsLoaded() const { return m_handle != 0; }
 209
 210     // load the library with the given name (full or not), return true if ok
 211     bool Load(const wxString& libname, int flags = wxDL_DEFAULT);
 212
 213     // raw function for loading dynamic libs: always behaves as if
 214     // wxDL_VERBATIM were specified and doesn't log error message if the
 215     // library couldn't be loaded but simply returns NULL
 216     static wxDllType RawLoad(const wxString& libname, int flags = wxDL_DEFAULT);
 217
 218     // detach the library object from its handle, i.e. prevent the object from
 219     // unloading the library in its dtor -- the caller is now responsible for
 220     // doing this
 221     wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
 222
 223     // unload the given library handle (presumably returned by Detach() before)
 224     static void Unload(wxDllType handle);
 225
 226     // unload the library, also done automatically in dtor
 227     void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } }
 228
 229     // Return the raw handle from dlopen and friends.
 230     wxDllType GetLibHandle() const { return m_handle; }
 231
 232     // check if the given symbol is present in the library, useful to verify if
 233     // a loadable module is our plugin, for example, without provoking error
 234     // messages from GetSymbol()
 235     bool HasSymbol(const wxString& name) const
 236     {
 237         bool ok;
 238         DoGetSymbol(name, &ok);
 239         return ok;
 240     }
 241
 242     // resolve a symbol in a loaded DLL, such as a variable or function name.
 243     // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to
 244     // export unmangled names)
 245     //
 246     // Since it is perfectly valid for the returned symbol to actually be NULL,
 247     // that is not always indication of an error.  Pass and test the parameter
 248     // 'success' for a true indication of success or failure to load the
 249     // symbol.
 250     //
 251     // Returns a pointer to the symbol on success, or NULL if an error occurred
 252     // or the symbol wasn't found.
 253     void *GetSymbol(const wxString& name, bool *success = NULL) const;
 254
 255     // low-level version of GetSymbol()
 256     static void *RawGetSymbol(wxDllType handle, const wxString& name);
 257     void *RawGetSymbol(const wxString& name) const
 258     {
 259 #if defined (__WXPM__) || defined(__EMX__)
 260         return GetSymbol(name);
 261 #else
 262         return RawGetSymbol(m_handle, name);
 263 #endif
 264     }
 265
 266 #ifdef __WXMSW__
 267     // this function is useful for loading functions from the standard Windows
 268     // DLLs: such functions have an 'A' (in ANSI build) or 'W' (in Unicode, or
 269     // wide character build) suffix if they take string parameters
 270     static void *RawGetSymbolAorW(wxDllType handle, const wxString& name)
 271     {
 272         return RawGetSymbol
 273                (
 274                 handle,
 275                 name +
 276 #if wxUSE_UNICODE
 277                 L'W'
 278 #else
 279                 'A'
 280 #endif
 281                );
 282     }
 283
 284     void *GetSymbolAorW(const wxString& name) const
 285     {
 286         return RawGetSymbolAorW(m_handle, name);
 287     }
 288 #endif // __WXMSW__
 289
 290     // return all modules/shared libraries in the address space of this process
 291     //
 292     // returns an empty array if not implemented or an error occurred
 293     static wxDynamicLibraryDetailsArray ListLoaded();
 294
 295     // return platform-specific name of dynamic library with proper extension
 296     // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
 297     static wxString CanonicalizeName(const wxString& name,
 298                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 299
 300     // return name of wxWidgets plugin (adds compiler and version info
 301     // to the filename):
 302     static wxString
 303     CanonicalizePluginName(const wxString& name,
 304                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 305
 306     // return plugin directory on platforms where it makes sense and empty
 307     // string on others:
 308     static wxString GetPluginsDirectory();
 309
 310
 311 protected:
 312     // common part of GetSymbol() and HasSymbol()
 313     void *DoGetSymbol(const wxString& name, bool *success = 0) const;
 314
 315 #ifdef wxHAVE_DYNLIB_ERROR
 316     // log the error after a dlxxx() function failure
 317     static void Error();
 318 #endif // wxHAVE_DYNLIB_ERROR
 319
 320
 321     // platform specific shared lib suffix.
 322     static const wxString ms_dllext;
 323
 324     // the handle to DLL or NULL
 325     wxDllType m_handle;
 326
 327     // no copy ctor/assignment operators (or we'd try to unload the library
 328     // twice)
 329     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 330 };
 331
 332
 333 // ----------------------------------------------------------------------------
 334 // Interesting defines
 335 // ----------------------------------------------------------------------------
 336
 337 #define WXDLL_ENTRY_FUNCTION() \
 338 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
 339 const wxClassInfo *wxGetClassFirst() { \
 340   return wxClassInfo::GetFirst(); \
 341 }
 342
 343 #endif // wxUSE_DYNLIB_CLASS
 344
 345 #endif // _WX_DYNLIB_H__