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 license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_DYNLIB_H__
  13 #define _WX_DYNLIB_H__
  14
  15 #ifdef __GNUG__
  16 #   pragma interface
  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 CFragConnectionID 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 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, const wxString &name, bool success = 0);
 117
 118     // return the standard DLL extension (with leading dot) for this platform
 119     static const wxString &GetDllExt() { return ms_dllext; }
 120
 121 private:
 122     // forbid construction of objects
 123     wxDllLoader();
 124     static const wxString   ms_dllext;
 125 };
 126
 127 // ----------------------------------------------------------------------------
 128 // wxDynamicLibrary - friendly interface to wxDllLoader
 129 // ----------------------------------------------------------------------------
 130
 131 class WXDLLEXPORT wxDynamicLibrary
 132 {
 133 public:
 134     // ctors
 135     wxDynamicLibrary() { m_library = 0; }
 136     wxDynamicLibrary(const wxString& name) { Load(name); }
 137
 138     // return TRUE if the library was loaded successfully
 139     bool IsLoaded() const { return m_library != 0; }
 140     operator bool() const { return IsLoaded(); }
 141
 142     // load the library with the given name (full or not), return TRUE on
 143     // success
 144     bool Load(const wxString& name)
 145     {
 146         m_library = wxDllLoader::LoadLibrary(name);
 147
 148         return IsLoaded();
 149     }
 150
 151     // unload the library, also done automatically in dtor
 152     void Unload()
 153     {
 154         if ( IsLoaded() )
 155             wxDllLoader::UnloadLibrary(m_library);
 156     }
 157
 158     // load a symbol from the library, return NULL if an error occured or
 159     // symbol wasn't found
 160     void *GetSymbol(const wxString& name) const
 161     {
 162         wxCHECK_MSG( IsLoaded(), NULL,
 163                      _T("can't load symbol from unloaded library") );
 164
 165         return wxDllLoader::GetSymbol(m_library, name);
 166     }
 167
 168     // unload the library
 169     //
 170     // NB: dtor is not virtual, don't derive from this class
 171     ~wxDynamicLibrary() { Unload(); }
 172
 173 private:
 174     // the handle to DLL or NULL
 175     wxDllType m_library;
 176
 177     // no copy ctor/assignment operators (or we'd try to unload the library
 178     // twice)
 179     DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
 180 };
 181
 182 // ----------------------------------------------------------------------------
 183 // wxLibrary
 184 // ----------------------------------------------------------------------------
 185
 186 class WXDLLEXPORT wxLibrary : public wxObject
 187 {
 188 public:
 189     wxLibrary(wxDllType handle);
 190     virtual ~wxLibrary();
 191
 192     // Get a symbol from the dynamic library
 193     void *GetSymbol(const wxString& symbname);
 194
 195     // Create the object whose classname is "name"
 196     wxObject *CreateObject(const wxString& name);
 197
 198 protected:
 199     void PrepareClasses(wxClassInfo *first);
 200
 201     wxDllType m_handle;
 202
 203 public:
 204     wxHashTable classTable;
 205 };
 206
 207 // ----------------------------------------------------------------------------
 208 // wxLibraries
 209 // ----------------------------------------------------------------------------
 210
 211 class WXDLLEXPORT wxLibraries
 212 {
 213 public:
 214     wxLibraries();
 215     ~wxLibraries();
 216
 217     // caller is responsible for deleting the returned pointer if !NULL
 218     wxLibrary *LoadLibrary(const wxString& basename);
 219
 220     wxObject *CreateObject(const wxString& name);
 221
 222 protected:
 223     wxList m_loaded;
 224 };
 225
 226 // ----------------------------------------------------------------------------
 227 // Global variables
 228 // ----------------------------------------------------------------------------
 229
 230 extern WXDLLEXPORT_DATA(wxLibraries) wxTheLibraries;
 231
 232 // ----------------------------------------------------------------------------
 233 // Interesting defines
 234 // ----------------------------------------------------------------------------
 235
 236 #define WXDLL_ENTRY_FUNCTION() \
 237 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
 238 const wxClassInfo *wxGetClassFirst() { \
 239   return wxClassInfo::GetFirst(); \
 240 }
 241
 242 #endif // wxUSE_DYNLIB_CLASS
 243
 244 #endif // _WX_DYNLIB_H__