]> git.saurik.com Git - wxWidgets.git/blame_incremental - include/wx/dynlib.h
Document that wxDC::FloodFill() is not implemented under wxOSX.
[wxWidgets.git] / include / wx / dynlib.h
... / ...
CommitLineData
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
27class 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
57enum 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
86enum wxDynamicLibraryCategory
87{
88 wxDL_LIBRARY, // standard library
89 wxDL_MODULE // loadable module/plugin
90};
91
92enum 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
174class WXDLLIMPEXP_BASE wxDynamicLibraryDetails
175{
176public:
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
208private:
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
219WX_DECLARE_USER_EXPORTED_OBJARRAY(wxDynamicLibraryDetails,
220 wxDynamicLibraryDetailsArray,
221 WXDLLIMPEXP_BASE);
222
223// ----------------------------------------------------------------------------
224// wxDynamicLibrary: represents a handle to a DLL/shared object
225// ----------------------------------------------------------------------------
226
227class WXDLLIMPEXP_BASE wxDynamicLibrary
228{
229public:
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 wxString GetDllExt(wxDynamicLibraryCategory cat = wxDL_LIBRARY);
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
365protected:
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 // the handle to DLL or NULL
376 wxDllType m_handle;
377
378 // no copy ctor/assignment operators (or we'd try to unload the library
379 // twice)
380 wxDECLARE_NO_COPY_CLASS(wxDynamicLibrary);
381};
382
383#ifdef __WINDOWS__
384
385// ----------------------------------------------------------------------------
386// wxLoadedDLL is a MSW-only internal helper class allowing to dynamically bind
387// to a DLL already loaded into the project address space
388// ----------------------------------------------------------------------------
389
390class wxLoadedDLL : public wxDynamicLibrary
391{
392public:
393 wxLoadedDLL(const wxString& dllname)
394 : wxDynamicLibrary(dllname, wxDL_GET_LOADED | wxDL_VERBATIM | wxDL_QUIET)
395 {
396 }
397
398 ~wxLoadedDLL()
399 {
400 Detach();
401 }
402};
403
404#endif // __WINDOWS__
405
406// ----------------------------------------------------------------------------
407// Interesting defines
408// ----------------------------------------------------------------------------
409
410#define WXDLL_ENTRY_FUNCTION() \
411extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
412const wxClassInfo *wxGetClassFirst() { \
413 return wxClassInfo::GetFirst(); \
414}
415
416#endif // wxUSE_DYNLIB_CLASS
417
418#endif // _WX_DYNLIB_H__