]> git.saurik.com Git - wxWidgets.git/blob - include/wx/dynlib.h
use slashes instead of backslashes and quotes instead of angle brackets in all #includes
[wxWidgets.git] / 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(NO_GCC_PRAGMA)
16 # pragma interface "dynlib.h"
17 #endif
18
19 #include "wx/setup.h"
20
21 #if wxUSE_DYNLIB_CLASS
22
23 #include "wx/string.h"
24
25 // FIXME: can this go in private.h or something too??
26 #if defined(__WXPM__) || defined(__EMX__)
27 #define INCL_DOS
28 #include <os2.h>
29 #endif
30
31 #ifdef __WXMSW__
32 #include "wx/msw/private.h"
33 #endif
34
35 // ----------------------------------------------------------------------------
36 // conditional compilation
37 // ----------------------------------------------------------------------------
38
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)
44 #include <dlfcn.h>
45 typedef void *wxDllType;
46 #elif defined(HAVE_SHL_LOAD)
47 #include <dl.h>
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;
54 #else
55 #error "Dynamic Loading classes can't be compiled on this platform, sorry."
56 #endif
57
58 // ----------------------------------------------------------------------------
59 // constants
60 // ----------------------------------------------------------------------------
61
62 enum wxDLFlags
63 {
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
67 // loaded libs.
68 wxDL_VERBATIM = 0x00000008, // Attempt to load the supplied library
69 // name without appending the usual dll
70 // filename extension.
71
72 wxDL_NOSHARE = 0x00000010, // load new DLL, don't reuse already loaded
73
74 // FIXME: why? (VZ)
75 #ifdef __osf__
76 wxDL_DEFAULT = wxDL_LAZY
77 #else
78 wxDL_DEFAULT = wxDL_LAZY | wxDL_GLOBAL
79 #endif
80 };
81
82 enum wxDynamicLibraryCategory
83 {
84 wxDL_LIBRARY, // standard library
85 wxDL_MODULE // loadable module/plugin
86 };
87
88 enum wxPluginCategory
89 {
90 wxDL_PLUGIN_GUI, // plugin that uses GUI classes
91 wxDL_PLUGIN_BASE // wxBase-only plugin
92 };
93
94 // ----------------------------------------------------------------------------
95 // macros
96 // ----------------------------------------------------------------------------
97
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
101 // all in one line
102 //
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))
108
109 // ---------------------------------------------------------------------------
110 // wxDynamicLibrary
111 // ---------------------------------------------------------------------------
112
113 class WXDLLIMPEXP_BASE wxDynamicLibrary
114 {
115 public:
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();
119
120 // return the platform standard DLL extension (with leading dot)
121 static const wxChar *GetDllExt() { return ms_dllext; }
122
123 wxDynamicLibrary() : m_handle(0) { }
124 wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT)
125 : m_handle(0)
126 {
127 Load(libname, flags);
128 }
129
130 // NOTE: this class is (deliberately) not virtual, do not attempt
131 // to use it polymorphically.
132 ~wxDynamicLibrary() { Unload(); }
133
134 // return true if the library was loaded successfully
135 bool IsLoaded() const { return m_handle != 0; }
136
137 // load the library with the given name (full or not), return true if ok
138 bool Load(wxString libname, int flags = wxDL_DEFAULT);
139
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
142 // doing this
143 wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
144
145 // unload the given library handle (presumably returned by Detach() before)
146 static void Unload(wxDllType handle);
147
148 // unload the library, also done automatically in dtor
149 void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } }
150
151 // Return the raw handle from dlopen and friends.
152 wxDllType GetLibHandle() const { return m_handle; }
153
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
158 {
159 bool ok;
160 DoGetSymbol(name, &ok);
161 return ok;
162 }
163
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)
167 //
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
171 // symbol.
172 //
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;
176
177
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);
182
183 // return name of wxWidgets plugin (adds compiler and version info
184 // to the filename):
185 static wxString
186 CanonicalizePluginName(const wxString& name,
187 wxPluginCategory cat = wxDL_PLUGIN_GUI);
188
189 // return plugin directory on platforms where it makes sense and empty
190 // string on others:
191 static wxString GetPluginsDirectory();
192
193
194 #if WXWIN_COMPATIBILITY_2_2
195 operator bool() const { return IsLoaded(); }
196 #endif
197
198 protected:
199 // the real implementation of GetSymbol()
200 void *DoGetSymbol(const wxString& name, bool *success = 0) const;
201
202
203 // platform specific shared lib suffix.
204 static const wxChar *ms_dllext;
205
206 // the handle to DLL or NULL
207 wxDllType m_handle;
208
209 // no copy ctor/assignment operators (or we'd try to unload the library
210 // twice)
211 DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
212 };
213
214
215 // ----------------------------------------------------------------------------
216 // wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code
217 // ----------------------------------------------------------------------------
218
219 #if WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
220
221 /*
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.
226 */
227 class WXDLLIMPEXP_BASE wxDllLoader
228 {
229 public:
230 /*
231 This function loads the shared library libname into memory.
232
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)
236
237 if success pointer is not NULL, it will be filled with true if everything
238 went ok and false otherwise
239 */
240 static wxDllType LoadLibrary(const wxString& name, bool *success = NULL);
241
242 /*
243 This function unloads the shared library previously loaded with
244 LoadLibrary
245 */
246 static void UnloadLibrary(wxDllType dll);
247
248 /*
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
251 (e.g. Win32).
252 */
253 static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
254
255 /*
256 This function resolves a symbol in a loaded DLL, such as a
257 variable or function name.
258
259 dllHandle Handle of the DLL, as returned by LoadDll().
260 name Name of the symbol.
261
262 Returns the pointer to the symbol or NULL on error.
263 */
264 static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0);
265
266 // return the standard DLL extension (with leading dot) for this platform
267 static wxString GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
268
269 private:
270
271 wxDllLoader(); // forbid construction of objects
272 };
273
274
275 // ----------------------------------------------------------------------------
276 // wxLibrary
277 // ----------------------------------------------------------------------------
278
279 #include "wx/hash.h"
280
281 class WXDLLIMPEXP_BASE wxLibrary : public wxObject
282 {
283 public:
284 wxLibrary(wxDllType handle);
285 virtual ~wxLibrary();
286
287 // Get a symbol from the dynamic library
288 void *GetSymbol(const wxString& symbname);
289
290 // Create the object whose classname is "name"
291 wxObject *CreateObject(const wxString& name);
292
293 protected:
294 void PrepareClasses(wxClassInfo *first);
295
296 wxDllType m_handle;
297
298 public:
299 wxHashTable classTable;
300 };
301
302 // ----------------------------------------------------------------------------
303 // wxLibraries
304 // ----------------------------------------------------------------------------
305
306 class WXDLLIMPEXP_BASE wxLibraries
307 {
308 public:
309 wxLibraries();
310 ~wxLibraries();
311
312 // caller is responsible for deleting the returned pointer if !NULL
313 wxLibrary *LoadLibrary(const wxString& basename);
314
315 wxObject *CreateObject(const wxString& name);
316
317 protected:
318 wxList m_loaded;
319 };
320
321 // ----------------------------------------------------------------------------
322 // Global variables
323 // ----------------------------------------------------------------------------
324
325 extern WXDLLIMPEXP_DATA_BASE(wxLibraries) wxTheLibraries;
326
327 #endif // WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
328
329 // ----------------------------------------------------------------------------
330 // Interesting defines
331 // ----------------------------------------------------------------------------
332
333 #define WXDLL_ENTRY_FUNCTION() \
334 extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
335 const wxClassInfo *wxGetClassFirst() { \
336 return wxClassInfo::GetFirst(); \
337 }
338
339 #endif // wxUSE_DYNLIB_CLASS
340
341 #endif // _WX_DYNLIB_H__