1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Dynamic library loading classes
4 // Author: Guilhem Lavaux, Vadim Zeitlin, Vaclav Slavik
8 // Copyright: (c) 1998 Guilhem Lavaux
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_DYNLIB_H__
13 #define _WX_DYNLIB_H__
15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
16 # pragma interface "dynlib.h"
21 #if wxUSE_DYNLIB_CLASS
23 #include "wx/string.h"
25 // FIXME: can this go in private.h or something too??
26 #if defined(__WXPM__) || defined(__EMX__)
32 #include "wx/msw/private.h"
35 // ----------------------------------------------------------------------------
36 // conditional compilation
37 // ----------------------------------------------------------------------------
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)
45 typedef void *wxDllType
;
46 #elif defined(HAVE_SHL_LOAD)
48 typedef shl_t wxDllType
;
49 #elif defined(__DARWIN__)
50 typedef void *wxDllType
;
51 #elif defined(__WXMAC__)
52 #include <CodeFragments.h>
53 typedef CFragConnectionID wxDllType
;
55 #error "Dynamic Loading classes can't be compiled on this platform, sorry."
58 // ----------------------------------------------------------------------------
60 // ----------------------------------------------------------------------------
64 wxDL_LAZY
= 0x00000001, // resolve undefined symbols at first use
65 wxDL_NOW
= 0x00000002, // resolve undefined symbols on load
66 wxDL_GLOBAL
= 0x00000004, // export extern symbols to subsequently
68 wxDL_VERBATIM
= 0x00000008, // Attempt to load the supplied library
69 // name without appending the usual dll
70 // filename extension.
72 wxDL_NOSHARE
= 0x00000010, // load new DLL, don't reuse already loaded
76 wxDL_DEFAULT
= wxDL_LAZY
78 wxDL_DEFAULT
= wxDL_LAZY
| wxDL_GLOBAL
82 enum wxDynamicLibraryCategory
84 wxDL_LIBRARY
, // standard library
85 wxDL_MODULE
// loadable module/plugin
90 wxDL_PLUGIN_GUI
, // plugin that uses GUI classes
91 wxDL_PLUGIN_BASE
// wxBase-only plugin
94 // ----------------------------------------------------------------------------
96 // ----------------------------------------------------------------------------
98 // when loading a function from a DLL you always have to cast the returned
99 // "void *" pointer to the correct type and, even more annoyingly, you have to
100 // repeat this type twice if you want to declare and define a function pointer
103 // this macro makes this slightly less painful by allowing you to specify the
104 // type only once, as the first parameter, and creating a variable of this type
105 // called "pfn<name>" initialized with the "name" from the "dynlib"
106 #define wxDYNLIB_FUNCTION(type, name, dynlib) \
107 type pfn ## name = (type)(dynlib).GetSymbol(_T(#name))
109 // ---------------------------------------------------------------------------
111 // ---------------------------------------------------------------------------
113 class WXDLLIMPEXP_BASE wxDynamicLibrary
116 // return a valid handle for the main program itself or NULL if back
117 // linking is not supported by the current platform (e.g. Win32)
118 static wxDllType
GetProgramHandle();
120 // return the platform standard DLL extension (with leading dot)
121 static const wxChar
*GetDllExt() { return ms_dllext
; }
123 wxDynamicLibrary() : m_handle(0) { }
124 wxDynamicLibrary(const wxString
& libname
, int flags
= wxDL_DEFAULT
)
127 Load(libname
, flags
);
130 // NOTE: this class is (deliberately) not virtual, do not attempt
131 // to use it polymorphically.
132 ~wxDynamicLibrary() { Unload(); }
134 // return true if the library was loaded successfully
135 bool IsLoaded() const { return m_handle
!= 0; }
137 // load the library with the given name (full or not), return true if ok
138 bool Load(wxString libname
, int flags
= wxDL_DEFAULT
);
140 // detach the library object from its handle, i.e. prevent the object from
141 // unloading the library in its dtor -- the caller is now responsible for
143 wxDllType
Detach() { wxDllType h
= m_handle
; m_handle
= 0; return h
; }
145 // unload the given library handle (presumably returned by Detach() before)
146 static void Unload(wxDllType handle
);
148 // unload the library, also done automatically in dtor
149 void Unload() { if ( IsLoaded() ) { Unload(m_handle
); m_handle
= 0; } }
151 // Return the raw handle from dlopen and friends.
152 wxDllType
GetLibHandle() const { return m_handle
; }
154 // check if the given symbol is present in the library, useful to verify if
155 // a loadable module is our plugin, for example, without provoking error
156 // messages from GetSymbol()
157 bool HasSymbol(const wxString
& name
) const
160 DoGetSymbol(name
, &ok
);
164 // resolve a symbol in a loaded DLL, such as a variable or function name.
165 // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to
166 // export unmangled names)
168 // Since it is perfectly valid for the returned symbol to actually be NULL,
169 // that is not always indication of an error. Pass and test the parameter
170 // 'success' for a true indication of success or failure to load the
173 // Returns a pointer to the symbol on success, or NULL if an error occurred
174 // or the symbol wasn't found.
175 void *GetSymbol(const wxString
& name
, bool *success
= 0) const;
178 // return platform-specific name of dynamic library with proper extension
179 // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
180 static wxString
CanonicalizeName(const wxString
& name
,
181 wxDynamicLibraryCategory cat
= wxDL_LIBRARY
);
183 // return name of wxWidgets plugin (adds compiler and version info
186 CanonicalizePluginName(const wxString
& name
,
187 wxPluginCategory cat
= wxDL_PLUGIN_GUI
);
189 // return plugin directory on platforms where it makes sense and empty
191 static wxString
GetPluginsDirectory();
194 #if WXWIN_COMPATIBILITY_2_2
195 operator bool() const { return IsLoaded(); }
199 // the real implementation of GetSymbol()
200 void *DoGetSymbol(const wxString
& name
, bool *success
= 0) const;
203 // platform specific shared lib suffix.
204 static const wxChar
*ms_dllext
;
206 // the handle to DLL or NULL
209 // no copy ctor/assignment operators (or we'd try to unload the library
211 DECLARE_NO_COPY_CLASS(wxDynamicLibrary
)
215 // ----------------------------------------------------------------------------
216 // wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code
217 // ----------------------------------------------------------------------------
219 #if WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
222 wxDllLoader is a class providing an interface similar to unix's dlopen().
223 It is used by wxDynamicLibrary wxLibrary and manages the actual loading of
224 DLLs and the resolving of symbols in them. There are no instances of this
225 class, it simply serves as a namespace for its static member functions.
227 class WXDLLIMPEXP_BASE wxDllLoader
231 This function loads the shared library libname into memory.
233 libname may be either the full path to the file or just the filename in
234 which case the library is searched for in all standard locations
235 (use GetDllExt() to construct the filename)
237 if success pointer is not NULL, it will be filled with true if everything
238 went ok and false otherwise
240 static wxDllType
LoadLibrary(const wxString
& name
, bool *success
= NULL
);
243 This function unloads the shared library previously loaded with
246 static void UnloadLibrary(wxDllType dll
);
249 This function returns a valid handle for the main program
250 itself or NULL if back linking is not supported by the current platform
253 static wxDllType
GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
256 This function resolves a symbol in a loaded DLL, such as a
257 variable or function name.
259 dllHandle Handle of the DLL, as returned by LoadDll().
260 name Name of the symbol.
262 Returns the pointer to the symbol or NULL on error.
264 static void *GetSymbol(wxDllType dllHandle
, const wxString
&name
, bool *success
= 0);
266 // return the standard DLL extension (with leading dot) for this platform
267 static wxString
GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
271 wxDllLoader(); // forbid construction of objects
275 // ----------------------------------------------------------------------------
277 // ----------------------------------------------------------------------------
281 class WXDLLIMPEXP_BASE wxLibrary
: public wxObject
284 wxLibrary(wxDllType handle
);
285 virtual ~wxLibrary();
287 // Get a symbol from the dynamic library
288 void *GetSymbol(const wxString
& symbname
);
290 // Create the object whose classname is "name"
291 wxObject
*CreateObject(const wxString
& name
);
294 void PrepareClasses(wxClassInfo
*first
);
299 wxHashTable classTable
;
302 // ----------------------------------------------------------------------------
304 // ----------------------------------------------------------------------------
306 class WXDLLIMPEXP_BASE wxLibraries
312 // caller is responsible for deleting the returned pointer if !NULL
313 wxLibrary
*LoadLibrary(const wxString
& basename
);
315 wxObject
*CreateObject(const wxString
& name
);
321 // ----------------------------------------------------------------------------
323 // ----------------------------------------------------------------------------
325 extern WXDLLIMPEXP_DATA_BASE(wxLibraries
) wxTheLibraries
;
327 #endif // WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
329 // ----------------------------------------------------------------------------
330 // Interesting defines
331 // ----------------------------------------------------------------------------
333 #define WXDLL_ENTRY_FUNCTION() \
334 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
335 const wxClassInfo *wxGetClassFirst() { \
336 return wxClassInfo::GetFirst(); \
339 #endif // wxUSE_DYNLIB_CLASS
341 #endif // _WX_DYNLIB_H__