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