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