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