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