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(__DARWIN__)
  46     // Don't include dlfcn.h on Darwin, we may be using our own replacements.
  47     typedef void               *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(__WXMAC__)
  55     #include <CodeFragments.h>
  56     typedef CFragConnectionID   wxDllType;
  57 #else
  58     #error "Dynamic Loading classes can't be compiled on this platform, sorry."
  59 #endif
  60
  61 // ----------------------------------------------------------------------------
  62 // constants
  63 // ----------------------------------------------------------------------------
  64
  65 enum wxDLFlags
  66 {
  67     wxDL_LAZY       = 0x00000001,   // resolve undefined symbols at first use
  68                                     // (only works on some Unix versions)
  69     wxDL_NOW        = 0x00000002,   // resolve undefined symbols on load
  70                                     // (default, always the case under Win32)
  71     wxDL_GLOBAL     = 0x00000004,   // export extern symbols to subsequently
  72                                     // loaded libs.
  73     wxDL_VERBATIM   = 0x00000008,   // attempt to load the supplied library
  74                                     // name without appending the usual dll
  75                                     // filename extension.
  76
  77     // this flag is obsolete, don't use
  78     wxDL_NOSHARE    = 0x00000010,   // load new DLL, don't reuse already loaded
  79                                     // (only for wxPluginManager)
  80
  81     wxDL_QUIET      = 0x00000020,   // don't log an error if failed to load
  82
  83     // this flag is dangerous, for internal use of wxMSW only, don't use at all
  84     // and especially don't use directly, use wxLoadedDLL instead if you really
  85     // do need it
  86     wxDL_GET_LOADED = 0x00000040,   // Win32 only: return handle of already
  87                                     // loaded DLL or NULL otherwise; Unload()
  88                                     // should not be called so don't forget to
  89                                     // Detach() if you use this function
  90
  91     wxDL_DEFAULT    = wxDL_NOW      // default flags correspond to Win32
  92 };
  93
  94 enum wxDynamicLibraryCategory
  95 {
  96     wxDL_LIBRARY,       // standard library
  97     wxDL_MODULE         // loadable module/plugin
  98 };
  99
 100 enum wxPluginCategory
 101 {
 102     wxDL_PLUGIN_GUI,    // plugin that uses GUI classes
 103     wxDL_PLUGIN_BASE    // wxBase-only plugin
 104 };
 105
 106 // ----------------------------------------------------------------------------
 107 // macros
 108 // ----------------------------------------------------------------------------
 109
 110 // when loading a function from a DLL you always have to cast the returned
 111 // "void *" pointer to the correct type and, even more annoyingly, you have to
 112 // repeat this type twice if you want to declare and define a function pointer
 113 // all in one line
 114 //
 115 // this macro makes this slightly less painful by allowing you to specify the
 116 // type only once, as the first parameter, and creating a variable of this type
 117 // called "pfn<name>" initialized with the "name" from the "dynlib"
 118 #define wxDYNLIB_FUNCTION(type, name, dynlib) \
 119     type pfn ## name = (type)(dynlib).GetSymbol(wxT(#name))
 120
 121
 122 // a more convenient function replacing wxDYNLIB_FUNCTION above
 123 //
 124 // it uses the convention that the type of the function is its name suffixed
 125 // with "_t" but it doesn't define a variable but just assigns the loaded value
 126 // to it and also allows to pass it the prefix to be used instead of hardcoding
 127 // "pfn" (the prefix can be "m_" or "gs_pfn" or whatever)
 128 //
 129 // notice that this function doesn't generate error messages if the symbol
 130 // couldn't be loaded, the caller should generate the appropriate message
 131 #define wxDL_INIT_FUNC(pfx, name, dynlib) \
 132     pfx ## name = (name ## _t)(dynlib).RawGetSymbol(#name)
 133
 134 #ifdef __WXMSW__
 135
 136 // same as wxDL_INIT_FUNC() but appends 'A' or 'W' to the function name, see
 137 // wxDynamicLibrary::GetSymbolAorW()
 138 #define wxDL_INIT_FUNC_AW(pfx, name, dynlib) \
 139     pfx ## name = (name ## _t)(dynlib).GetSymbolAorW(#name)
 140
 141 #endif // __WXMSW__
 142
 143 // the following macros can be used to redirect a whole library to a class and
 144 // check at run-time if the library is present and contains all required
 145 // methods
 146 //
 147 // notice that they are supposed to be used inside a class which has "m_ok"
 148 // member variable indicating if the library had been successfully loaded
 149
 150 // helper macros constructing the name of the variable storing the function
 151 // pointer and the name of its type from the function name
 152 #define wxDL_METHOD_NAME(name) m_pfn ## name
 153 #define wxDL_METHOD_TYPE(name) name ## _t
 154
 155 // parameters are:
 156 //  - rettype: return type of the function, e.g. "int"
 157 //  - name: name of the function, e.g. "foo"
 158 //  - args: function signature in parentheses, e.g. "(int x, int y)"
 159 //  - argnames: the names of the parameters in parentheses, e.g. "(x, y)"
 160 //  - defret: the value to return if the library wasn't successfully loaded
 161 #define wxDL_METHOD_DEFINE( rettype, name, args, argnames, defret ) \
 162     typedef rettype (* wxDL_METHOD_TYPE(name)) args ; \
 163     wxDL_METHOD_TYPE(name) wxDL_METHOD_NAME(name); \
 164     rettype name args \
 165         { return m_ok ? wxDL_METHOD_NAME(name) argnames : defret; }
 166
 167 #define wxDL_VOIDMETHOD_DEFINE( name, args, argnames ) \
 168     typedef void (* wxDL_METHOD_TYPE(name)) args ; \
 169     wxDL_METHOD_TYPE(name) wxDL_METHOD_NAME(name); \
 170     void name args \
 171         { if ( m_ok ) wxDL_METHOD_NAME(name) argnames ; }
 172
 173 #define wxDL_METHOD_LOAD(lib, name) \
 174     wxDL_METHOD_NAME(name) = \
 175         (wxDL_METHOD_TYPE(name)) lib.GetSymbol(#name, &m_ok); \
 176     if ( !m_ok ) return false
 177
 178 // ----------------------------------------------------------------------------
 179 // wxDynamicLibraryDetails: contains details about a loaded wxDynamicLibrary
 180 // ----------------------------------------------------------------------------
 181
 182 class WXDLLIMPEXP_BASE wxDynamicLibraryDetails
 183 {
 184 public:
 185     // ctor, normally never used as these objects are only created by
 186     // wxDynamicLibrary::ListLoaded()
 187     wxDynamicLibraryDetails() { m_address = NULL; m_length = 0; }
 188
 189     // get the (base) name
 190     wxString GetName() const { return m_name; }
 191
 192     // get the full path of this object
 193     wxString GetPath() const { return m_path; }
 194
 195     // get the load address and the extent, return true if this information is
 196     // available
 197     bool GetAddress(void **addr, size_t *len) const
 198     {
 199         if ( !m_address )
 200             return false;
 201
 202         if ( addr )
 203             *addr = m_address;
 204         if ( len )
 205             *len = m_length;
 206
 207         return true;
 208     }
 209
 210     // return the version of the DLL (may be empty if no version info)
 211     wxString GetVersion() const
 212     {
 213         return m_version;
 214     }
 215
 216 private:
 217     wxString m_name,
 218              m_path,
 219              m_version;
 220
 221     void *m_address;
 222     size_t m_length;
 223
 224     friend class wxDynamicLibraryDetailsCreator;
 225 };
 226
 227 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxDynamicLibraryDetails,
 228                                   wxDynamicLibraryDetailsArray,
 229                                   WXDLLIMPEXP_BASE);
 230
 231 // ----------------------------------------------------------------------------
 232 // wxDynamicLibrary: represents a handle to a DLL/shared object
 233 // ----------------------------------------------------------------------------
 234
 235 class WXDLLIMPEXP_BASE wxDynamicLibrary
 236 {
 237 public:
 238     // return a valid handle for the main program itself or NULL if back
 239     // linking is not supported by the current platform (e.g. Win32)
 240     static wxDllType         GetProgramHandle();
 241
 242     // return the platform standard DLL extension (with leading dot)
 243     static const wxString& GetDllExt() { return ms_dllext; }
 244
 245     wxDynamicLibrary() : m_handle(0) { }
 246     wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT)
 247         : m_handle(0)
 248     {
 249         Load(libname, flags);
 250     }
 251
 252     // NOTE: this class is (deliberately) not virtual, do not attempt
 253     //       to use it polymorphically.
 254     ~wxDynamicLibrary() { Unload(); }
 255
 256     // return true if the library was loaded successfully
 257     bool IsLoaded() const { return m_handle != 0; }
 258
 259     // load the library with the given name (full or not), return true if ok
 260     bool Load(const wxString& libname, int flags = wxDL_DEFAULT);
 261
 262     // raw function for loading dynamic libs: always behaves as if
 263     // wxDL_VERBATIM were specified and doesn't log error message if the
 264     // library couldn't be loaded but simply returns NULL
 265     static wxDllType RawLoad(const wxString& libname, int flags = wxDL_DEFAULT);
 266
 267     // detach the library object from its handle, i.e. prevent the object from
 268     // unloading the library in its dtor -- the caller is now responsible for
 269     // doing this
 270     wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
 271
 272     // unload the given library handle (presumably returned by Detach() before)
 273     static void Unload(wxDllType handle);
 274
 275     // unload the library, also done automatically in dtor
 276     void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } }
 277
 278     // Return the raw handle from dlopen and friends.
 279     wxDllType GetLibHandle() const { return m_handle; }
 280
 281     // check if the given symbol is present in the library, useful to verify if
 282     // a loadable module is our plugin, for example, without provoking error
 283     // messages from GetSymbol()
 284     bool HasSymbol(const wxString& name) const
 285     {
 286         bool ok;
 287         DoGetSymbol(name, &ok);
 288         return ok;
 289     }
 290
 291     // resolve a symbol in a loaded DLL, such as a variable or function name.
 292     // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to
 293     // export unmangled names)
 294     //
 295     // Since it is perfectly valid for the returned symbol to actually be NULL,
 296     // that is not always indication of an error.  Pass and test the parameter
 297     // 'success' for a true indication of success or failure to load the
 298     // symbol.
 299     //
 300     // Returns a pointer to the symbol on success, or NULL if an error occurred
 301     // or the symbol wasn't found.
 302     void *GetSymbol(const wxString& name, bool *success = NULL) const;
 303
 304     // low-level version of GetSymbol()
 305     static void *RawGetSymbol(wxDllType handle, const wxString& name);
 306     void *RawGetSymbol(const wxString& name) const
 307     {
 308 #if defined (__WXPM__) || defined(__EMX__)
 309         return GetSymbol(name);
 310 #else
 311         return RawGetSymbol(m_handle, name);
 312 #endif
 313     }
 314
 315 #ifdef __WXMSW__
 316     // this function is useful for loading functions from the standard Windows
 317     // DLLs: such functions have an 'A' (in ANSI build) or 'W' (in Unicode, or
 318     // wide character build) suffix if they take string parameters
 319     static void *RawGetSymbolAorW(wxDllType handle, const wxString& name)
 320     {
 321         return RawGetSymbol
 322                (
 323                 handle,
 324                 name +
 325 #if wxUSE_UNICODE
 326                 L'W'
 327 #else
 328                 'A'
 329 #endif
 330                );
 331     }
 332
 333     void *GetSymbolAorW(const wxString& name) const
 334     {
 335         return RawGetSymbolAorW(m_handle, name);
 336     }
 337 #endif // __WXMSW__
 338
 339     // return all modules/shared libraries in the address space of this process
 340     //
 341     // returns an empty array if not implemented or an error occurred
 342     static wxDynamicLibraryDetailsArray ListLoaded();
 343
 344     // return platform-specific name of dynamic library with proper extension
 345     // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
 346     static wxString CanonicalizeName(const wxString& name,
 347                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 348
 349     // return name of wxWidgets plugin (adds compiler and version info
 350     // to the filename):
 351     static wxString
 352     CanonicalizePluginName(const wxString& name,
 353                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 354
 355     // return plugin directory on platforms where it makes sense and empty
 356     // string on others:
 357     static wxString GetPluginsDirectory();
 358
 359
 360 #ifdef __WXMSW__
 361     // return the handle (HMODULE/HINSTANCE) of the DLL with the given name
 362     // and/or containing the specified address: for XP and later systems only
 363     // the address is used and the name is ignored but for the previous systems
 364     // only the name (which may be either a full path to the DLL or just its
 365     // base name, possibly even without extension) is used
 366     //
 367     // the returned handle reference count is not incremented so it doesn't
 368     // need to be freed using FreeLibrary() but it also means that it can
 369     // become invalid if the DLL is unloaded
 370     static HINSTANCE MSWGetModuleHandle(const char *name, void *addr);
 371 #endif // __WXMSW__
 372
 373 protected:
 374     // common part of GetSymbol() and HasSymbol()
 375     void *DoGetSymbol(const wxString& name, bool *success = 0) const;
 376
 377 #ifdef wxHAVE_DYNLIB_ERROR
 378     // log the error after a dlxxx() function failure
 379     static void Error();
 380 #endif // wxHAVE_DYNLIB_ERROR
 381
 382
 383     // platform specific shared lib suffix.
 384     static const wxString ms_dllext;
 385
 386     // the handle to DLL or NULL
 387     wxDllType m_handle;
 388
 389     // no copy ctor/assignment operators (or we'd try to unload the library
 390     // twice)
 391     wxDECLARE_NO_COPY_CLASS(wxDynamicLibrary);
 392 };
 393
 394 #ifdef __WXMSW__
 395
 396 // ----------------------------------------------------------------------------
 397 // wxLoadedDLL is a MSW-only internal helper class allowing to dynamically bind
 398 // to a DLL already loaded into the project address space
 399 // ----------------------------------------------------------------------------
 400
 401 class wxLoadedDLL : public wxDynamicLibrary
 402 {
 403 public:
 404     wxLoadedDLL(const wxString& dllname)
 405         : wxDynamicLibrary(dllname, wxDL_GET_LOADED | wxDL_VERBATIM | wxDL_QUIET)
 406     {
 407     }
 408
 409     ~wxLoadedDLL()
 410     {
 411         Detach();
 412     }
 413 };
 414
 415 #endif // __WXMSW__
 416
 417 // ----------------------------------------------------------------------------
 418 // Interesting defines
 419 // ----------------------------------------------------------------------------
 420
 421 #define WXDLL_ENTRY_FUNCTION() \
 422 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
 423 const wxClassInfo *wxGetClassFirst() { \
 424   return wxClassInfo::GetFirst(); \
 425 }
 426
 427 #endif // wxUSE_DYNLIB_CLASS
 428
 429 #endif // _WX_DYNLIB_H__