1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Dynamic loading framework
4 // Author: Ron Lee, David Falkinder, Vadim Zeitlin and a cast of 1000's
5 // (derived in part from dynlib.cpp (c) 1998 Guilhem Lavaux)
9 // Copyright: (c) 2001 Ron Lee <ron@debian.org>
10 // Licence: wxWindows licence
11 /////////////////////////////////////////////////////////////////////////////
13 #ifndef _WX_DYNAMICLOADER_H__
14 #define _WX_DYNAMICLOADER_H__
16 #if defined(__GNUG__) && !defined(__APPLE__)
17 #pragma interface "dynload.h"
20 // ----------------------------------------------------------------------------
22 // ----------------------------------------------------------------------------
26 #if wxUSE_DYNAMIC_LOADER
28 #include "wx/hashmap.h"
29 #include "wx/module.h"
31 // FIXME: can this go in private.h or something too??
32 #if defined(__WXPM__) || defined(__EMX__)
38 #include "wx/msw/private.h"
41 class WXDLLIMPEXP_BASE wxPluginLibrary
;
43 WX_DECLARE_EXPORTED_STRING_HASH_MAP(wxPluginLibrary
*, wxDLManifest
);
44 typedef wxDLManifest wxDLImports
;
46 // ----------------------------------------------------------------------------
47 // conditional compilation
48 // ----------------------------------------------------------------------------
50 // Note: WXPM/EMX has to be tested first, since we want to use
51 // native version, even if configure detected presence of DLOPEN.
53 #if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__)
54 typedef HMODULE wxDllType
;
55 #elif defined(HAVE_DLOPEN)
57 typedef void *wxDllType
;
58 #elif defined(HAVE_SHL_LOAD)
60 typedef shl_t wxDllType
;
61 #elif defined(__DARWIN__)
62 typedef void *wxDllType
;
63 #elif defined(__WXMAC__)
64 typedef CFragConnectionID wxDllType
;
66 #error "Dynamic Loading classes can't be compiled on this platform, sorry."
70 // ---------------------------------------------------------------------------
72 // ---------------------------------------------------------------------------
74 //FIXME: This class isn't really common at all, it should be moved
75 // into platform dependent files.
77 // NOTE: this class is (deliberately) not virtual, do not attempt
78 // to use it polymorphically.
82 wxDL_LAZY
= 0x00000001, // resolve undefined symbols at first use
83 wxDL_NOW
= 0x00000002, // resolve undefined symbols on load
84 wxDL_GLOBAL
= 0x00000004, // export extern symbols to subsequently
86 wxDL_VERBATIM
= 0x00000008, // Attempt to load the supplied library
87 // name without appending the usual dll
88 // filename extension.
90 wxDL_NOSHARE
= 0x00000010, // load new DLL, don't reuse already loaded
94 wxDL_DEFAULT
= wxDL_LAZY
96 wxDL_DEFAULT
= wxDL_LAZY
| wxDL_GLOBAL
100 enum wxDynamicLibraryCategory
102 wxDL_LIBRARY
, // standard library
103 wxDL_MODULE
, // loadable module/plugin
106 enum wxPluginCategory
108 wxDL_PLUGIN_GUI
, // plugin that uses GUI classes
109 wxDL_PLUGIN_BASE
, // wxBase-only plugin
113 class WXDLLIMPEXP_BASE wxDynamicLibrary
117 // return a valid handle for the main program itself or NULL if
118 // back linking is not supported by the current platform (e.g. Win32)
120 static wxDllType
GetProgramHandle();
122 // return the platform standard DLL extension (with leading dot)
124 static const wxChar
*GetDllExt() { return ms_dllext
; }
126 wxDynamicLibrary() : m_handle(0) {}
127 wxDynamicLibrary(wxString libname
, int flags
= wxDL_DEFAULT
)
130 Load(libname
, flags
);
132 ~wxDynamicLibrary() { Unload(); }
134 // return TRUE if the library was loaded successfully
136 bool IsLoaded() const { return m_handle
!= 0; }
138 // load the library with the given name
139 // (full or not), return TRUE on success
141 bool Load(wxString libname
, int flags
= wxDL_DEFAULT
);
143 // detach the library object from its handle, i.e. prevent the object
144 // from unloading the library in its dtor -- the caller is now
145 // responsible for doing this
146 wxDllType
Detach() { wxDllType h
= m_handle
; m_handle
= 0; return h
; }
148 // unload the library, also done automatically in dtor
152 // Return the raw handle from dlopen and friends.
154 wxDllType
GetLibHandle() const { return m_handle
; }
156 // resolve a symbol in a loaded DLL, such as a variable or function
157 // name. 'name' is the (possibly mangled) name of the symbol.
158 // (use extern "C" to export unmangled names)
160 // Since it is perfectly valid for the returned symbol to actually be
161 // NULL, that is not always indication of an error. Pass and test the
162 // parameter 'success' for a true indication of success or failure to
165 // Returns a pointer to the symbol on success, or NULL if an error
166 // occurred or the symbol wasn't found.
168 void *GetSymbol(const wxString
& name
, bool *success
= 0) const;
170 #if WXWIN_COMPATIBILITY_2_2
171 operator bool() const { return IsLoaded(); }
174 // return platform-specific name of dynamic library with proper extension
175 // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
176 static wxString
CanonicalizeName(const wxString
& name
,
177 wxDynamicLibraryCategory cat
= wxDL_LIBRARY
);
179 // return name of wxWindows plugin (adds compiler and version info
181 static wxString
CanonicalizePluginName(const wxString
& name
,
182 wxPluginCategory cat
);
184 // return plugin directory on platforms where it makes sense and empty
186 static wxString
GetPluginsDirectory();
190 // Platform specific shared lib suffix.
192 static const wxChar
*ms_dllext
;
194 // the handle to DLL or NULL
198 // no copy ctor/assignment operators
199 // or we'd try to unload the library twice
201 DECLARE_NO_COPY_CLASS(wxDynamicLibrary
)
205 // ---------------------------------------------------------------------------
207 // ---------------------------------------------------------------------------
209 // NOTE: Do not attempt to use a base class pointer to this class.
210 // wxDL is not virtual and we deliberately hide some of it's
213 // Unless you know exacty why you need to, you probably shouldn't
214 // instantiate this class directly anyway, use wxPluginManager
217 class WXDLLIMPEXP_BASE wxPluginLibrary
: public wxDynamicLibrary
221 static wxDLImports
* ms_classes
; // Static hash of all imported classes.
223 wxPluginLibrary( const wxString
&libname
, int flags
= wxDL_DEFAULT
);
226 wxPluginLibrary
*RefLib();
229 // These two are called by the PluginSentinel on (PLUGGABLE) object
230 // creation/destruction. There is usually no reason for the user to
231 // call them directly. We have to separate this from the link count,
232 // since the two are not interchangeable.
234 // FIXME: for even better debugging PluginSentinel should register
235 // the name of the class created too, then we can state
236 // exactly which object was not destroyed which may be
237 // difficult to find otherwise. Also this code should
238 // probably only be active in DEBUG mode, but let's just
239 // get it right first.
241 void RefObj() { ++m_objcount
; }
244 wxASSERT_MSG( m_objcount
> 0, _T("Too many objects deleted??") );
248 // Override/hide some base class methods
250 bool IsLoaded() const { return m_linkcount
> 0; }
251 void Unload() { UnrefLib(); }
255 wxClassInfo
*m_before
; // sm_first before loading this lib
256 wxClassInfo
*m_after
; // ..and after.
258 size_t m_linkcount
; // Ref count of library link calls
259 size_t m_objcount
; // ..and (pluggable) object instantiations.
260 wxModuleList m_wxmodules
; // any wxModules that we initialised.
262 void UpdateClassInfo(); // Update the wxClassInfo table
263 void RestoreClassInfo(); // Restore the original wxClassInfo state.
264 void RegisterModules(); // Init any wxModules in the lib.
265 void UnregisterModules(); // Cleanup any wxModules we installed.
267 DECLARE_NO_COPY_CLASS(wxPluginLibrary
)
271 class WXDLLIMPEXP_BASE wxPluginManager
277 static wxPluginLibrary
*LoadLibrary( const wxString
&libname
,
278 int flags
= wxDL_DEFAULT
);
279 static bool UnloadLibrary(const wxString
&libname
);
281 // This is used by wxDllLoader. It's wrapped in the compatibility
282 // macro because it's of arguable use outside of that.
284 #if WXWIN_COMPATIBILITY_2_2
285 static wxPluginLibrary
*GetObjectFromHandle(wxDllType handle
);
290 wxPluginManager() : m_entry(NULL
) {};
291 wxPluginManager(const wxString
&libname
, int flags
= wxDL_DEFAULT
)
293 Load(libname
, flags
);
295 ~wxPluginManager() { Unload(); }
297 bool Load(const wxString
&libname
, int flags
= wxDL_DEFAULT
);
300 bool IsLoaded() const { return m_entry
&& m_entry
->IsLoaded(); }
301 void *GetSymbol(const wxString
&symbol
, bool *success
= 0)
303 return m_entry
->GetSymbol( symbol
, success
);
306 static void CreateManifest() { ms_manifest
= new wxDLManifest(wxKEY_STRING
); }
307 static void ClearManifest() { delete ms_manifest
; ms_manifest
= NULL
; }
310 // return the pointer to the entry for the library with given name in
311 // ms_manifest or NULL if none
312 static wxPluginLibrary
*FindByName(const wxString
& name
)
314 const wxDLManifest::iterator i
= ms_manifest
->find(name
);
316 return i
== ms_manifest
->end() ? NULL
: i
->second
;
319 static wxDLManifest
* ms_manifest
; // Static hash of loaded libs.
320 wxPluginLibrary
* m_entry
; // Cache our entry in the manifest.
322 // We could allow this class to be copied if we really
323 // wanted to, but not without modification.
324 DECLARE_NO_COPY_CLASS(wxPluginManager
)
328 // ---------------------------------------------------------------------------
330 // ---------------------------------------------------------------------------
332 // Cross platform wrapper for dlopen and friends.
333 // There are no instances of this class, it simply
334 // serves as a namespace for its static member functions.
336 #if WXWIN_COMPATIBILITY_2_2
337 class WXDLLIMPEXP_BASE wxDllLoader
341 static wxDllType
LoadLibrary(const wxString
& name
, bool *success
= NULL
);
342 static void UnloadLibrary(wxDllType dll
);
344 static wxDllType
GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
346 static void *GetSymbol(wxDllType dllHandle
, const wxString
&name
, bool *success
= 0);
348 static wxString
GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
352 wxDllLoader(); // forbid construction of objects
356 #endif // wxUSE_DYNAMIC_LOADER
357 #endif // _WX_DYNAMICLOADER_H__