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(__APPLE__)
  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
  25 // FIXME: can this go in private.h or something too??
  26 #if defined(__WXPM__) || defined(__EMX__)
  27 #define INCL_DOS
  28 #include <os2.h>
  29 #endif
  30
  31 #ifdef __WXMSW__
  32 #include "wx/msw/private.h"
  33 #endif
  34
  35 // ----------------------------------------------------------------------------
  36 // conditional compilation
  37 // ----------------------------------------------------------------------------
  38
  39 // Note: WXPM/EMX has to be tested first, since we want to use
  40 // native version, even if configure detected presence of DLOPEN.
  41 #if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__)
  42     typedef HMODULE             wxDllType;
  43 #elif defined(HAVE_DLOPEN)
  44     #include <dlfcn.h>
  45     typedef void               *wxDllType;
  46 #elif defined(HAVE_SHL_LOAD)
  47     #include <dl.h>
  48     typedef shl_t               wxDllType;
  49 #elif defined(__DARWIN__)
  50     typedef void               *wxDllType;
  51 #elif defined(__WXMAC__)
  52     typedef CFragConnectionID   wxDllType;
  53 #else
  54     #error "Dynamic Loading classes can't be compiled on this platform, sorry."
  55 #endif
  56
  57 // ----------------------------------------------------------------------------
  58 // constants
  59 // ----------------------------------------------------------------------------
  60
  61 enum wxDLFlags
  62 {
  63     wxDL_LAZY       = 0x00000001,   // resolve undefined symbols at first use
  64     wxDL_NOW        = 0x00000002,   // resolve undefined symbols on load
  65     wxDL_GLOBAL     = 0x00000004,   // export extern symbols to subsequently
  66                                     // loaded libs.
  67     wxDL_VERBATIM   = 0x00000008,   // Attempt to load the supplied library
  68                                     // name without appending the usual dll
  69                                     // filename extension.
  70
  71     wxDL_NOSHARE    = 0x00000010,   // load new DLL, don't reuse already loaded
  72
  73     // FIXME: why? (VZ)
  74 #ifdef __osf__
  75     wxDL_DEFAULT    = wxDL_LAZY
  76 #else
  77     wxDL_DEFAULT    = wxDL_LAZY | wxDL_GLOBAL
  78 #endif
  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 // wxDynamicLibrary
 110 // ---------------------------------------------------------------------------
 111
 112 class WXDLLIMPEXP_BASE wxDynamicLibrary
 113 {
 114 public:
 115     // return a valid handle for the main program itself or NULL if back
 116     // linking is not supported by the current platform (e.g. Win32)
 117     static wxDllType         GetProgramHandle();
 118
 119     // return the platform standard DLL extension (with leading dot)
 120     static const wxChar *GetDllExt() { return ms_dllext; }
 121
 122     wxDynamicLibrary() : m_handle(0) { }
 123     wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT)
 124         : m_handle(0)
 125     {
 126         Load(libname, flags);
 127     }
 128
 129     // NOTE: this class is (deliberately) not virtual, do not attempt
 130     //       to use it polymorphically.
 131     ~wxDynamicLibrary() { Unload(); }
 132
 133     // return TRUE if the library was loaded successfully
 134     bool IsLoaded() const { return m_handle != 0; }
 135
 136     // load the library with the given name (full or not), return true if ok
 137     bool Load(wxString libname, int flags = wxDL_DEFAULT);
 138
 139     // detach the library object from its handle, i.e. prevent the object from
 140     // unloading the library in its dtor -- the caller is now responsible for
 141     // doing this
 142     wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
 143
 144     // unload the library, also done automatically in dtor
 145     void Unload();
 146
 147     // Return the raw handle from dlopen and friends.
 148     wxDllType GetLibHandle() const { return m_handle; }
 149
 150     // resolve a symbol in a loaded DLL, such as a variable or function name.
 151     // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to
 152     // export unmangled names)
 153     //
 154     // Since it is perfectly valid for the returned symbol to actually be NULL,
 155     // that is not always indication of an error.  Pass and test the parameter
 156     // 'success' for a true indication of success or failure to load the
 157     // symbol.
 158     //
 159     // Returns a pointer to the symbol on success, or NULL if an error occurred
 160     // or the symbol wasn't found.
 161     void *GetSymbol(const wxString& name, bool *success = 0) const;
 162
 163
 164     // return platform-specific name of dynamic library with proper extension
 165     // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
 166     static wxString CanonicalizeName(const wxString& name,
 167                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 168
 169     // return name of wxWindows plugin (adds compiler and version info
 170     // to the filename):
 171     static wxString CanonicalizePluginName(const wxString& name,
 172                                            wxPluginCategory cat);
 173
 174     // return plugin directory on platforms where it makes sense and empty
 175     // string on others:
 176     static wxString GetPluginsDirectory();
 177
 178
 179 #if WXWIN_COMPATIBILITY_2_2
 180     operator bool() const { return IsLoaded(); }
 181 #endif
 182
 183 protected:
 184     // platform specific shared lib suffix.
 185     static const wxChar *ms_dllext;
 186
 187     // the handle to DLL or NULL
 188     wxDllType m_handle;
 189
 190     // no copy ctor/assignment operators (or we'd try to unload the library
 191     // twice)
 192     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 193 };
 194
 195
 196 // ----------------------------------------------------------------------------
 197 // wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code
 198 // ----------------------------------------------------------------------------
 199
 200 #if WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
 201
 202 /*
 203     wxDllLoader is a class providing an interface similar to unix's dlopen().
 204     It is used by wxDynamicLibrary wxLibrary and manages the actual loading of
 205     DLLs and the resolving of symbols in them. There are no instances of this
 206     class, it simply serves as a namespace for its static member functions.
 207 */
 208 class WXDLLIMPEXP_BASE wxDllLoader
 209 {
 210 public:
 211     /*
 212       This function loads the shared library libname into memory.
 213
 214       libname may be either the full path to the file or just the filename in
 215       which case the library is searched for in all standard locations
 216       (use GetDllExt() to construct the filename)
 217
 218       if success pointer is not NULL, it will be filled with TRUE if everything
 219       went ok and FALSE otherwise
 220      */
 221     static wxDllType LoadLibrary(const wxString& name, bool *success = NULL);
 222
 223     /*
 224       This function unloads the shared library previously loaded with
 225       LoadLibrary
 226      */
 227     static void UnloadLibrary(wxDllType dll);
 228
 229     /*
 230        This function returns a valid handle for the main program
 231        itself or NULL if back linking is not supported by the current platform
 232        (e.g. Win32).
 233      */
 234     static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
 235
 236     /*
 237        This function resolves a symbol in a loaded DLL, such as a
 238        variable or function name.
 239
 240        dllHandle Handle of the DLL, as returned by LoadDll().
 241        name Name of the symbol.
 242
 243        Returns the pointer to the symbol or NULL on error.
 244      */
 245     static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0);
 246
 247     // return the standard DLL extension (with leading dot) for this platform
 248     static wxString GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
 249
 250 private:
 251
 252     wxDllLoader();                    // forbid construction of objects
 253 };
 254
 255
 256 // ----------------------------------------------------------------------------
 257 // wxLibrary
 258 // ----------------------------------------------------------------------------
 259
 260 #include "wx/hash.h"
 261
 262 class WXDLLIMPEXP_BASE wxLibrary : public wxObject
 263 {
 264 public:
 265     wxLibrary(wxDllType handle);
 266     virtual ~wxLibrary();
 267
 268     // Get a symbol from the dynamic library
 269     void *GetSymbol(const wxString& symbname);
 270
 271     // Create the object whose classname is "name"
 272     wxObject *CreateObject(const wxString& name);
 273
 274 protected:
 275     void PrepareClasses(wxClassInfo *first);
 276
 277     wxDllType m_handle;
 278
 279 public:
 280     wxHashTable classTable;
 281 };
 282
 283 // ----------------------------------------------------------------------------
 284 // wxLibraries
 285 // ----------------------------------------------------------------------------
 286
 287 class WXDLLIMPEXP_BASE wxLibraries
 288 {
 289 public:
 290     wxLibraries();
 291     ~wxLibraries();
 292
 293     // caller is responsible for deleting the returned pointer if !NULL
 294     wxLibrary *LoadLibrary(const wxString& basename);
 295
 296     wxObject *CreateObject(const wxString& name);
 297
 298 protected:
 299     wxList m_loaded;
 300 };
 301
 302 // ----------------------------------------------------------------------------
 303 // Global variables
 304 // ----------------------------------------------------------------------------
 305
 306 extern WXDLLIMPEXP_DATA_BASE(wxLibraries) wxTheLibraries;
 307
 308 #endif // WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
 309
 310 // ----------------------------------------------------------------------------
 311 // Interesting defines
 312 // ----------------------------------------------------------------------------
 313
 314 #define WXDLL_ENTRY_FUNCTION() \
 315 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
 316 const wxClassInfo *wxGetClassFirst() { \
 317   return wxClassInfo::GetFirst(); \
 318 }
 319
 320 #endif // wxUSE_DYNLIB_CLASS
 321
 322 #endif // _WX_DYNLIB_H__