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