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_DYNAMIC_LOADER
  22
  23 #include "wx/dynload.h"  // Use the new (version of) wxDynamicLibrary instead
  24
  25 #elif wxUSE_DYNLIB_CLASS
  26
  27 #include "wx/string.h"
  28 #include "wx/list.h"
  29 #include "wx/hash.h"
  30
  31 // this is normally done by configure, but I leave it here for now...
  32 #if defined(__UNIX__) && !(defined(HAVE_DLOPEN) || defined(HAVE_SHL_LOAD))
  33 #   if defined(__LINUX__) || defined(__SOLARIS__) || defined(__SUNOS__) || defined(__FREEBSD__)
  34 #      define HAVE_DLOPEN
  35 #   elif defined(__HPUX__)
  36 #      define HAVE_SHL_LOAD
  37 #   endif // Unix flavour
  38 #endif // !Unix or already have some HAVE_xxx defined
  39
  40 // Note: WXPM/EMX has to be tested first, since we want to use
  41 // native version, even if configure detected presence of DLOPEN.
  42 #if defined(__WXPM__) || defined(__EMX__)
  43 #   define INCL_DOS
  44 #   include <os2.h>
  45     typedef HMODULE wxDllType;
  46 #elif defined(HAVE_DLOPEN)
  47 #   include <dlfcn.h>
  48     typedef void *wxDllType;
  49 #elif defined(HAVE_SHL_LOAD)
  50 #   include <dl.h>
  51     typedef shl_t wxDllType;
  52 #elif defined(__WINDOWS__)
  53 #   include <windows.h>         // needed to get HMODULE
  54     typedef HMODULE wxDllType;
  55 #elif defined(__DARWIN__)
  56     typedef void *wxDllType;
  57 #elif defined(__WXMAC__)
  58     typedef void *wxDllType;
  59 #else
  60 #   error "wxLibrary can't be compiled on this platform, sorry."
  61 #endif // OS
  62
  63 // LoadLibrary is defined in windows.h as LoadLibraryA, but wxDllLoader method
  64 // should be called LoadLibrary, not LoadLibraryA or LoadLibraryW!
  65 #if defined(__WIN32__) && defined(LoadLibrary)
  66 #   include "wx/msw/winundef.h"
  67 #endif
  68
  69 // ----------------------------------------------------------------------------
  70 // wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code
  71 // ----------------------------------------------------------------------------
  72
  73 /*
  74     wxDllLoader is a class providing an interface similar to unix's dlopen().
  75     It is used by wxDynamicLibrary wxLibrary and manages the actual loading of
  76     DLLs and the resolving of symbols in them. There are no instances of this
  77     class, it simply serves as a namespace for its static member functions.
  78 */
  79 class WXDLLEXPORT_BASE wxDllLoader
  80 {
  81 public:
  82     /*
  83       This function loads the shared library libname into memory.
  84
  85       libname may be either the full path to the file or just the filename in
  86       which case the library is searched for in all standard locations
  87       (use GetDllExt() to construct the filename)
  88
  89       if success pointer is not NULL, it will be filled with TRUE if everything
  90       went ok and FALSE otherwise
  91      */
  92     static wxDllType LoadLibrary(const wxString& libname, bool *success = 0);
  93
  94     /*
  95       This function unloads the shared library previously loaded with
  96       LoadLibrary
  97      */
  98     static void UnloadLibrary(wxDllType dll);
  99
 100     /*
 101        This function returns a valid handle for the main program
 102        itself or NULL if back linking is not supported by the current platform
 103        (e.g. Win32).
 104      */
 105     static wxDllType GetProgramHandle();
 106
 107     /*
 108        This function resolves a symbol in a loaded DLL, such as a
 109        variable or function name.
 110
 111        dllHandle Handle of the DLL, as returned by LoadDll().
 112        name Name of the symbol.
 113
 114        Returns the pointer to the symbol or NULL on error.
 115      */
 116     static void *GetSymbol(wxDllType dllHandle,
 117                            const wxString &name,
 118                            bool *success = NULL);
 119
 120     // return the standard DLL extension (with leading dot) for this platform
 121     static const wxString &GetDllExt() { return ms_dllext; }
 122
 123 private:
 124     // forbid construction of objects
 125     wxDllLoader();
 126     static const wxString   ms_dllext;
 127 };
 128
 129 // ----------------------------------------------------------------------------
 130 // wxDynamicLibrary - friendly interface to wxDllLoader
 131 // ----------------------------------------------------------------------------
 132
 133 class WXDLLEXPORT_BASE wxDynamicLibrary
 134 {
 135 public:
 136     // ctors
 137     wxDynamicLibrary() { m_library = 0; }
 138     wxDynamicLibrary(const wxString& name) { Load(name); }
 139
 140     // return TRUE if the library was loaded successfully
 141     bool IsLoaded() const { return m_library != 0; }
 142     operator bool() const { return IsLoaded(); }
 143
 144     // load the library with the given name (full or not), return TRUE on
 145     // success
 146     bool Load(const wxString& name)
 147     {
 148         m_library = wxDllLoader::LoadLibrary(name);
 149
 150         return IsLoaded();
 151     }
 152
 153     // unload the library, also done automatically in dtor
 154     void Unload()
 155     {
 156         if ( IsLoaded() )
 157             wxDllLoader::UnloadLibrary(m_library);
 158     }
 159
 160     // load a symbol from the library, return NULL if an error occured or
 161     // symbol wasn't found
 162     void *GetSymbol(const wxString& name) const
 163     {
 164         wxCHECK_MSG( IsLoaded(), NULL,
 165                      _T("can't load symbol from unloaded library") );
 166
 167         return wxDllLoader::GetSymbol(m_library, name);
 168     }
 169
 170     // unload the library
 171     //
 172     // NB: dtor is not virtual, don't derive from this class
 173     ~wxDynamicLibrary() { Unload(); }
 174
 175 private:
 176     // the handle to DLL or NULL
 177     wxDllType m_library;
 178
 179     // no copy ctor/assignment operators (or we'd try to unload the library
 180     // twice)
 181     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 182 };
 183
 184 // ----------------------------------------------------------------------------
 185 // wxLibrary
 186 // ----------------------------------------------------------------------------
 187
 188 class WXDLLEXPORT_BASE wxLibrary : public wxObject
 189 {
 190 public:
 191     wxLibrary(wxDllType handle);
 192     virtual ~wxLibrary();
 193
 194     // Get a symbol from the dynamic library
 195     void *GetSymbol(const wxString& symbname);
 196
 197     // Create the object whose classname is "name"
 198     wxObject *CreateObject(const wxString& name);
 199
 200 protected:
 201     void PrepareClasses(wxClassInfo *first);
 202
 203     wxDllType m_handle;
 204
 205 public:
 206     wxHashTable classTable;
 207 };
 208
 209 // ----------------------------------------------------------------------------
 210 // wxLibraries
 211 // ----------------------------------------------------------------------------
 212
 213 class WXDLLEXPORT_BASE wxLibraries
 214 {
 215 public:
 216     wxLibraries();
 217     ~wxLibraries();
 218
 219     // caller is responsible for deleting the returned pointer if !NULL
 220     wxLibrary *LoadLibrary(const wxString& basename);
 221
 222     wxObject *CreateObject(const wxString& name);
 223
 224 protected:
 225     wxList m_loaded;
 226 };
 227
 228 // ----------------------------------------------------------------------------
 229 // Global variables
 230 // ----------------------------------------------------------------------------
 231
 232 extern WXDLLEXPORT_DATA_BASE(wxLibraries) wxTheLibraries;
 233
 234 // ----------------------------------------------------------------------------
 235 // Interesting defines
 236 // ----------------------------------------------------------------------------
 237
 238 #define WXDLL_ENTRY_FUNCTION() \
 239 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
 240 const wxClassInfo *wxGetClassFirst() { \
 241   return wxClassInfo::GetFirst(); \
 242 }
 243
 244 #endif // wxUSE_DYNLIB_CLASS
 245
 246 #endif // _WX_DYNLIB_H__