]>
Commit | Line | Data |
---|---|---|
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 | #include "wx/defs.h" | |
16 | ||
17 | #if wxUSE_DYNLIB_CLASS | |
18 | ||
19 | #include "wx/string.h" | |
20 | #include "wx/dynarray.h" | |
21 | ||
22 | // note that we have our own dlerror() implementation under Darwin | |
23 | #if (defined(HAVE_DLERROR) && !defined(__EMX__)) || defined(__DARWIN__) | |
24 | #define wxHAVE_DYNLIB_ERROR | |
25 | #endif | |
26 | ||
27 | class WXDLLIMPEXP_FWD_BASE wxDynamicLibraryDetailsCreator; | |
28 | ||
29 | // ---------------------------------------------------------------------------- | |
30 | // conditional compilation | |
31 | // ---------------------------------------------------------------------------- | |
32 | ||
33 | // Note: __OS2__/EMX has to be tested first, since we want to use | |
34 | // native version, even if configure detected presence of DLOPEN. | |
35 | #if defined(__OS2__) || defined(__EMX__) || defined(__WINDOWS__) | |
36 | typedef WXHMODULE wxDllType; | |
37 | #elif defined(__DARWIN__) | |
38 | // Don't include dlfcn.h on Darwin, we may be using our own replacements. | |
39 | typedef void *wxDllType; | |
40 | #elif defined(HAVE_DLOPEN) | |
41 | #include <dlfcn.h> | |
42 | typedef void *wxDllType; | |
43 | #elif defined(HAVE_SHL_LOAD) | |
44 | #include <dl.h> | |
45 | typedef shl_t wxDllType; | |
46 | #elif defined(__WXMAC__) | |
47 | #include <CodeFragments.h> | |
48 | typedef CFragConnectionID wxDllType; | |
49 | #else | |
50 | #error "Dynamic Loading classes can't be compiled on this platform, sorry." | |
51 | #endif | |
52 | ||
53 | // ---------------------------------------------------------------------------- | |
54 | // constants | |
55 | // ---------------------------------------------------------------------------- | |
56 | ||
57 | enum wxDLFlags | |
58 | { | |
59 | wxDL_LAZY = 0x00000001, // resolve undefined symbols at first use | |
60 | // (only works on some Unix versions) | |
61 | wxDL_NOW = 0x00000002, // resolve undefined symbols on load | |
62 | // (default, always the case under Win32) | |
63 | wxDL_GLOBAL = 0x00000004, // export extern symbols to subsequently | |
64 | // loaded libs. | |
65 | wxDL_VERBATIM = 0x00000008, // attempt to load the supplied library | |
66 | // name without appending the usual dll | |
67 | // filename extension. | |
68 | ||
69 | // this flag is obsolete, don't use | |
70 | wxDL_NOSHARE = 0x00000010, // load new DLL, don't reuse already loaded | |
71 | // (only for wxPluginManager) | |
72 | ||
73 | wxDL_QUIET = 0x00000020, // don't log an error if failed to load | |
74 | ||
75 | // this flag is dangerous, for internal use of wxMSW only, don't use at all | |
76 | // and especially don't use directly, use wxLoadedDLL instead if you really | |
77 | // do need it | |
78 | wxDL_GET_LOADED = 0x00000040, // Win32 only: return handle of already | |
79 | // loaded DLL or NULL otherwise; Unload() | |
80 | // should not be called so don't forget to | |
81 | // Detach() if you use this function | |
82 | ||
83 | wxDL_DEFAULT = wxDL_NOW // default flags correspond to Win32 | |
84 | }; | |
85 | ||
86 | enum wxDynamicLibraryCategory | |
87 | { | |
88 | wxDL_LIBRARY, // standard library | |
89 | wxDL_MODULE // loadable module/plugin | |
90 | }; | |
91 | ||
92 | enum wxPluginCategory | |
93 | { | |
94 | wxDL_PLUGIN_GUI, // plugin that uses GUI classes | |
95 | wxDL_PLUGIN_BASE // wxBase-only plugin | |
96 | }; | |
97 | ||
98 | // ---------------------------------------------------------------------------- | |
99 | // macros | |
100 | // ---------------------------------------------------------------------------- | |
101 | ||
102 | // when loading a function from a DLL you always have to cast the returned | |
103 | // "void *" pointer to the correct type and, even more annoyingly, you have to | |
104 | // repeat this type twice if you want to declare and define a function pointer | |
105 | // all in one line | |
106 | // | |
107 | // this macro makes this slightly less painful by allowing you to specify the | |
108 | // type only once, as the first parameter, and creating a variable of this type | |
109 | // called "pfn<name>" initialized with the "name" from the "dynlib" | |
110 | #define wxDYNLIB_FUNCTION(type, name, dynlib) \ | |
111 | type pfn ## name = (type)(dynlib).GetSymbol(wxT(#name)) | |
112 | ||
113 | ||
114 | // a more convenient function replacing wxDYNLIB_FUNCTION above | |
115 | // | |
116 | // it uses the convention that the type of the function is its name suffixed | |
117 | // with "_t" but it doesn't define a variable but just assigns the loaded value | |
118 | // to it and also allows to pass it the prefix to be used instead of hardcoding | |
119 | // "pfn" (the prefix can be "m_" or "gs_pfn" or whatever) | |
120 | // | |
121 | // notice that this function doesn't generate error messages if the symbol | |
122 | // couldn't be loaded, the caller should generate the appropriate message | |
123 | #define wxDL_INIT_FUNC(pfx, name, dynlib) \ | |
124 | pfx ## name = (name ## _t)(dynlib).RawGetSymbol(#name) | |
125 | ||
126 | #ifdef __WINDOWS__ | |
127 | ||
128 | // same as wxDL_INIT_FUNC() but appends 'A' or 'W' to the function name, see | |
129 | // wxDynamicLibrary::GetSymbolAorW() | |
130 | #define wxDL_INIT_FUNC_AW(pfx, name, dynlib) \ | |
131 | pfx ## name = (name ## _t)(dynlib).GetSymbolAorW(#name) | |
132 | ||
133 | #endif // __WINDOWS__ | |
134 | ||
135 | // the following macros can be used to redirect a whole library to a class and | |
136 | // check at run-time if the library is present and contains all required | |
137 | // methods | |
138 | // | |
139 | // notice that they are supposed to be used inside a class which has "m_ok" | |
140 | // member variable indicating if the library had been successfully loaded | |
141 | ||
142 | // helper macros constructing the name of the variable storing the function | |
143 | // pointer and the name of its type from the function name | |
144 | #define wxDL_METHOD_NAME(name) m_pfn ## name | |
145 | #define wxDL_METHOD_TYPE(name) name ## _t | |
146 | ||
147 | // parameters are: | |
148 | // - rettype: return type of the function, e.g. "int" | |
149 | // - name: name of the function, e.g. "foo" | |
150 | // - args: function signature in parentheses, e.g. "(int x, int y)" | |
151 | // - argnames: the names of the parameters in parentheses, e.g. "(x, y)" | |
152 | // - defret: the value to return if the library wasn't successfully loaded | |
153 | #define wxDL_METHOD_DEFINE( rettype, name, args, argnames, defret ) \ | |
154 | typedef rettype (* wxDL_METHOD_TYPE(name)) args ; \ | |
155 | wxDL_METHOD_TYPE(name) wxDL_METHOD_NAME(name); \ | |
156 | rettype name args \ | |
157 | { return m_ok ? wxDL_METHOD_NAME(name) argnames : defret; } | |
158 | ||
159 | #define wxDL_VOIDMETHOD_DEFINE( name, args, argnames ) \ | |
160 | typedef void (* wxDL_METHOD_TYPE(name)) args ; \ | |
161 | wxDL_METHOD_TYPE(name) wxDL_METHOD_NAME(name); \ | |
162 | void name args \ | |
163 | { if ( m_ok ) wxDL_METHOD_NAME(name) argnames ; } | |
164 | ||
165 | #define wxDL_METHOD_LOAD(lib, name) \ | |
166 | wxDL_METHOD_NAME(name) = \ | |
167 | (wxDL_METHOD_TYPE(name)) lib.GetSymbol(#name, &m_ok); \ | |
168 | if ( !m_ok ) return false | |
169 | ||
170 | // ---------------------------------------------------------------------------- | |
171 | // wxDynamicLibraryDetails: contains details about a loaded wxDynamicLibrary | |
172 | // ---------------------------------------------------------------------------- | |
173 | ||
174 | class WXDLLIMPEXP_BASE wxDynamicLibraryDetails | |
175 | { | |
176 | public: | |
177 | // ctor, normally never used as these objects are only created by | |
178 | // wxDynamicLibrary::ListLoaded() | |
179 | wxDynamicLibraryDetails() { m_address = NULL; m_length = 0; } | |
180 | ||
181 | // get the (base) name | |
182 | wxString GetName() const { return m_name; } | |
183 | ||
184 | // get the full path of this object | |
185 | wxString GetPath() const { return m_path; } | |
186 | ||
187 | // get the load address and the extent, return true if this information is | |
188 | // available | |
189 | bool GetAddress(void **addr, size_t *len) const | |
190 | { | |
191 | if ( !m_address ) | |
192 | return false; | |
193 | ||
194 | if ( addr ) | |
195 | *addr = m_address; | |
196 | if ( len ) | |
197 | *len = m_length; | |
198 | ||
199 | return true; | |
200 | } | |
201 | ||
202 | // return the version of the DLL (may be empty if no version info) | |
203 | wxString GetVersion() const | |
204 | { | |
205 | return m_version; | |
206 | } | |
207 | ||
208 | private: | |
209 | wxString m_name, | |
210 | m_path, | |
211 | m_version; | |
212 | ||
213 | void *m_address; | |
214 | size_t m_length; | |
215 | ||
216 | friend class wxDynamicLibraryDetailsCreator; | |
217 | }; | |
218 | ||
219 | WX_DECLARE_USER_EXPORTED_OBJARRAY(wxDynamicLibraryDetails, | |
220 | wxDynamicLibraryDetailsArray, | |
221 | WXDLLIMPEXP_BASE); | |
222 | ||
223 | // ---------------------------------------------------------------------------- | |
224 | // wxDynamicLibrary: represents a handle to a DLL/shared object | |
225 | // ---------------------------------------------------------------------------- | |
226 | ||
227 | class WXDLLIMPEXP_BASE wxDynamicLibrary | |
228 | { | |
229 | public: | |
230 | // return a valid handle for the main program itself or NULL if back | |
231 | // linking is not supported by the current platform (e.g. Win32) | |
232 | static wxDllType GetProgramHandle(); | |
233 | ||
234 | // return the platform standard DLL extension (with leading dot) | |
235 | static const wxString& GetDllExt() { return ms_dllext; } | |
236 | ||
237 | wxDynamicLibrary() : m_handle(0) { } | |
238 | wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT) | |
239 | : m_handle(0) | |
240 | { | |
241 | Load(libname, flags); | |
242 | } | |
243 | ||
244 | // NOTE: this class is (deliberately) not virtual, do not attempt | |
245 | // to use it polymorphically. | |
246 | ~wxDynamicLibrary() { Unload(); } | |
247 | ||
248 | // return true if the library was loaded successfully | |
249 | bool IsLoaded() const { return m_handle != 0; } | |
250 | ||
251 | // load the library with the given name (full or not), return true if ok | |
252 | bool Load(const wxString& libname, int flags = wxDL_DEFAULT); | |
253 | ||
254 | // raw function for loading dynamic libs: always behaves as if | |
255 | // wxDL_VERBATIM were specified and doesn't log error message if the | |
256 | // library couldn't be loaded but simply returns NULL | |
257 | static wxDllType RawLoad(const wxString& libname, int flags = wxDL_DEFAULT); | |
258 | ||
259 | // detach the library object from its handle, i.e. prevent the object from | |
260 | // unloading the library in its dtor -- the caller is now responsible for | |
261 | // doing this | |
262 | wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; } | |
263 | ||
264 | // unload the given library handle (presumably returned by Detach() before) | |
265 | static void Unload(wxDllType handle); | |
266 | ||
267 | // unload the library, also done automatically in dtor | |
268 | void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } } | |
269 | ||
270 | // Return the raw handle from dlopen and friends. | |
271 | wxDllType GetLibHandle() const { return m_handle; } | |
272 | ||
273 | // check if the given symbol is present in the library, useful to verify if | |
274 | // a loadable module is our plugin, for example, without provoking error | |
275 | // messages from GetSymbol() | |
276 | bool HasSymbol(const wxString& name) const | |
277 | { | |
278 | bool ok; | |
279 | DoGetSymbol(name, &ok); | |
280 | return ok; | |
281 | } | |
282 | ||
283 | // resolve a symbol in a loaded DLL, such as a variable or function name. | |
284 | // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to | |
285 | // export unmangled names) | |
286 | // | |
287 | // Since it is perfectly valid for the returned symbol to actually be NULL, | |
288 | // that is not always indication of an error. Pass and test the parameter | |
289 | // 'success' for a true indication of success or failure to load the | |
290 | // symbol. | |
291 | // | |
292 | // Returns a pointer to the symbol on success, or NULL if an error occurred | |
293 | // or the symbol wasn't found. | |
294 | void *GetSymbol(const wxString& name, bool *success = NULL) const; | |
295 | ||
296 | // low-level version of GetSymbol() | |
297 | static void *RawGetSymbol(wxDllType handle, const wxString& name); | |
298 | void *RawGetSymbol(const wxString& name) const | |
299 | { | |
300 | #if defined (__WXPM__) || defined(__EMX__) | |
301 | return GetSymbol(name); | |
302 | #else | |
303 | return RawGetSymbol(m_handle, name); | |
304 | #endif | |
305 | } | |
306 | ||
307 | #ifdef __WINDOWS__ | |
308 | // this function is useful for loading functions from the standard Windows | |
309 | // DLLs: such functions have an 'A' (in ANSI build) or 'W' (in Unicode, or | |
310 | // wide character build) suffix if they take string parameters | |
311 | static void *RawGetSymbolAorW(wxDllType handle, const wxString& name) | |
312 | { | |
313 | return RawGetSymbol | |
314 | ( | |
315 | handle, | |
316 | name + | |
317 | #if wxUSE_UNICODE | |
318 | L'W' | |
319 | #else | |
320 | 'A' | |
321 | #endif | |
322 | ); | |
323 | } | |
324 | ||
325 | void *GetSymbolAorW(const wxString& name) const | |
326 | { | |
327 | return RawGetSymbolAorW(m_handle, name); | |
328 | } | |
329 | #endif // __WINDOWS__ | |
330 | ||
331 | // return all modules/shared libraries in the address space of this process | |
332 | // | |
333 | // returns an empty array if not implemented or an error occurred | |
334 | static wxDynamicLibraryDetailsArray ListLoaded(); | |
335 | ||
336 | // return platform-specific name of dynamic library with proper extension | |
337 | // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux) | |
338 | static wxString CanonicalizeName(const wxString& name, | |
339 | wxDynamicLibraryCategory cat = wxDL_LIBRARY); | |
340 | ||
341 | // return name of wxWidgets plugin (adds compiler and version info | |
342 | // to the filename): | |
343 | static wxString | |
344 | CanonicalizePluginName(const wxString& name, | |
345 | wxPluginCategory cat = wxDL_PLUGIN_GUI); | |
346 | ||
347 | // return plugin directory on platforms where it makes sense and empty | |
348 | // string on others: | |
349 | static wxString GetPluginsDirectory(); | |
350 | ||
351 | ||
352 | #ifdef __WINDOWS__ | |
353 | // return the handle (HMODULE/HINSTANCE) of the DLL with the given name | |
354 | // and/or containing the specified address: for XP and later systems only | |
355 | // the address is used and the name is ignored but for the previous systems | |
356 | // only the name (which may be either a full path to the DLL or just its | |
357 | // base name, possibly even without extension) is used | |
358 | // | |
359 | // the returned handle reference count is not incremented so it doesn't | |
360 | // need to be freed using FreeLibrary() but it also means that it can | |
361 | // become invalid if the DLL is unloaded | |
362 | static WXHMODULE MSWGetModuleHandle(const wxString& name, void *addr); | |
363 | #endif // __WINDOWS__ | |
364 | ||
365 | protected: | |
366 | // common part of GetSymbol() and HasSymbol() | |
367 | void *DoGetSymbol(const wxString& name, bool *success = 0) const; | |
368 | ||
369 | #ifdef wxHAVE_DYNLIB_ERROR | |
370 | // log the error after a dlxxx() function failure | |
371 | static void Error(); | |
372 | #endif // wxHAVE_DYNLIB_ERROR | |
373 | ||
374 | ||
375 | // platform specific shared lib suffix. | |
376 | static const wxString ms_dllext; | |
377 | ||
378 | // the handle to DLL or NULL | |
379 | wxDllType m_handle; | |
380 | ||
381 | // no copy ctor/assignment operators (or we'd try to unload the library | |
382 | // twice) | |
383 | wxDECLARE_NO_COPY_CLASS(wxDynamicLibrary); | |
384 | }; | |
385 | ||
386 | #ifdef __WINDOWS__ | |
387 | ||
388 | // ---------------------------------------------------------------------------- | |
389 | // wxLoadedDLL is a MSW-only internal helper class allowing to dynamically bind | |
390 | // to a DLL already loaded into the project address space | |
391 | // ---------------------------------------------------------------------------- | |
392 | ||
393 | class wxLoadedDLL : public wxDynamicLibrary | |
394 | { | |
395 | public: | |
396 | wxLoadedDLL(const wxString& dllname) | |
397 | : wxDynamicLibrary(dllname, wxDL_GET_LOADED | wxDL_VERBATIM | wxDL_QUIET) | |
398 | { | |
399 | } | |
400 | ||
401 | ~wxLoadedDLL() | |
402 | { | |
403 | Detach(); | |
404 | } | |
405 | }; | |
406 | ||
407 | #endif // __WINDOWS__ | |
408 | ||
409 | // ---------------------------------------------------------------------------- | |
410 | // Interesting defines | |
411 | // ---------------------------------------------------------------------------- | |
412 | ||
413 | #define WXDLL_ENTRY_FUNCTION() \ | |
414 | extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \ | |
415 | const wxClassInfo *wxGetClassFirst() { \ | |
416 | return wxClassInfo::GetFirst(); \ | |
417 | } | |
418 | ||
419 | #endif // wxUSE_DYNLIB_CLASS | |
420 | ||
421 | #endif // _WX_DYNLIB_H__ |