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