]>
Commit | Line | Data |
---|---|---|
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 | |
1a787c5d | 22 | #if defined(__WXPM__) || 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 | ||
da55d064 VZ |
30 | #if defined(HAVE_DLERROR) && !defined(__EMX__) |
31 | #define wxHAVE_DYNLIB_ERROR | |
32 | #endif | |
33 | ||
defbed48 VZ |
34 | class WXDLLIMPEXP_BASE wxDynamicLibraryDetailsCreator; |
35 | ||
1948bb32 VS |
36 | // ---------------------------------------------------------------------------- |
37 | // conditional compilation | |
38 | // ---------------------------------------------------------------------------- | |
39 | ||
4104ed92 VZ |
40 | // Note: WXPM/EMX has to be tested first, since we want to use |
41 | // native version, even if configure detected presence of DLOPEN. | |
1948bb32 | 42 | #if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__) |
4104ed92 | 43 | typedef HMODULE wxDllType; |
1a787c5d | 44 | #elif defined(HAVE_DLOPEN) |
4104ed92 VZ |
45 | #include <dlfcn.h> |
46 | typedef void *wxDllType; | |
8a0d4cf6 | 47 | #elif defined(HAVE_SHL_LOAD) |
4104ed92 VZ |
48 | #include <dl.h> |
49 | typedef shl_t wxDllType; | |
f11bdd03 | 50 | #elif defined(__DARWIN__) |
4104ed92 | 51 | typedef void *wxDllType; |
7b0bfbb2 | 52 | #elif defined(__WXMAC__) |
609533d5 | 53 | #include <CodeFragments.h> |
4104ed92 | 54 | typedef CFragConnectionID wxDllType; |
7b0bfbb2 | 55 | #else |
4104ed92 | 56 | #error "Dynamic Loading classes can't be compiled on this platform, sorry." |
1948bb32 VS |
57 | #endif |
58 | ||
4104ed92 VZ |
59 | // ---------------------------------------------------------------------------- |
60 | // constants | |
61 | // ---------------------------------------------------------------------------- | |
1948bb32 VS |
62 | |
63 | enum wxDLFlags | |
64 | { | |
65 | wxDL_LAZY = 0x00000001, // resolve undefined symbols at first use | |
e62e17d7 | 66 | // (only works on some Unix versions) |
1948bb32 | 67 | wxDL_NOW = 0x00000002, // resolve undefined symbols on load |
e62e17d7 | 68 | // (default, always the case under Win32) |
1948bb32 VS |
69 | wxDL_GLOBAL = 0x00000004, // export extern symbols to subsequently |
70 | // loaded libs. | |
e62e17d7 | 71 | wxDL_VERBATIM = 0x00000008, // attempt to load the supplied library |
1948bb32 VS |
72 | // name without appending the usual dll |
73 | // filename extension. | |
1948bb32 | 74 | wxDL_NOSHARE = 0x00000010, // load new DLL, don't reuse already loaded |
e62e17d7 | 75 | // (only for wxPluginManager) |
1948bb32 | 76 | |
e62e17d7 | 77 | wxDL_DEFAULT = wxDL_NOW // default flags correspond to Win32 |
1948bb32 VS |
78 | }; |
79 | ||
80 | enum wxDynamicLibraryCategory | |
81 | { | |
82 | wxDL_LIBRARY, // standard library | |
13e51f3a | 83 | wxDL_MODULE // loadable module/plugin |
1948bb32 VS |
84 | }; |
85 | ||
86 | enum wxPluginCategory | |
87 | { | |
88 | wxDL_PLUGIN_GUI, // plugin that uses GUI classes | |
13e51f3a | 89 | wxDL_PLUGIN_BASE // wxBase-only plugin |
1948bb32 VS |
90 | }; |
91 | ||
4104ed92 VZ |
92 | // ---------------------------------------------------------------------------- |
93 | // macros | |
94 | // ---------------------------------------------------------------------------- | |
95 | ||
96 | // when loading a function from a DLL you always have to cast the returned | |
97 | // "void *" pointer to the correct type and, even more annoyingly, you have to | |
98 | // repeat this type twice if you want to declare and define a function pointer | |
99 | // all in one line | |
100 | // | |
101 | // this macro makes this slightly less painful by allowing you to specify the | |
102 | // type only once, as the first parameter, and creating a variable of this type | |
103 | // called "pfn<name>" initialized with the "name" from the "dynlib" | |
104 | #define wxDYNLIB_FUNCTION(type, name, dynlib) \ | |
105 | type pfn ## name = (type)(dynlib).GetSymbol(_T(#name)) | |
106 | ||
defbed48 VZ |
107 | // ---------------------------------------------------------------------------- |
108 | // wxDynamicLibraryDetails: contains details about a loaded wxDynamicLibrary | |
109 | // ---------------------------------------------------------------------------- | |
110 | ||
111 | class WXDLLIMPEXP_BASE wxDynamicLibraryDetails | |
112 | { | |
113 | public: | |
114 | // ctor, normally never used as these objects are only created by | |
115 | // wxDynamicLibrary::ListLoaded() | |
116 | wxDynamicLibraryDetails() { m_address = NULL; m_length = 0; } | |
117 | ||
118 | // get the (base) name | |
119 | wxString GetName() const { return m_name; } | |
120 | ||
121 | // get the full path of this object | |
122 | wxString GetPath() const { return m_path; } | |
123 | ||
124 | // get the load address and the extent, return true if this information is | |
125 | // available | |
126 | bool GetAddress(void **addr, size_t *len) const | |
127 | { | |
128 | if ( !m_address ) | |
129 | return false; | |
130 | ||
131 | if ( addr ) | |
132 | *addr = m_address; | |
133 | if ( len ) | |
134 | *len = m_length; | |
135 | ||
136 | return true; | |
137 | } | |
138 | ||
139 | // return the version of the DLL (may be empty if no version info) | |
140 | wxString GetVersion() const | |
141 | { | |
142 | return m_version; | |
143 | } | |
144 | ||
145 | private: | |
146 | wxString m_name, | |
147 | m_path, | |
148 | m_version; | |
149 | ||
150 | void *m_address; | |
151 | size_t m_length; | |
152 | ||
153 | friend class wxDynamicLibraryDetailsCreator; | |
154 | }; | |
155 | ||
156 | WX_DECLARE_USER_EXPORTED_OBJARRAY(wxDynamicLibraryDetails, | |
157 | wxDynamicLibraryDetailsArray, | |
158 | WXDLLIMPEXP_BASE); | |
159 | ||
160 | // ---------------------------------------------------------------------------- | |
161 | // wxDynamicLibrary: represents a handle to a DLL/shared object | |
162 | // ---------------------------------------------------------------------------- | |
1948bb32 VS |
163 | |
164 | class WXDLLIMPEXP_BASE wxDynamicLibrary | |
165 | { | |
166 | public: | |
4104ed92 VZ |
167 | // return a valid handle for the main program itself or NULL if back |
168 | // linking is not supported by the current platform (e.g. Win32) | |
1948bb32 VS |
169 | static wxDllType GetProgramHandle(); |
170 | ||
4104ed92 | 171 | // return the platform standard DLL extension (with leading dot) |
1948bb32 VS |
172 | static const wxChar *GetDllExt() { return ms_dllext; } |
173 | ||
4104ed92 | 174 | wxDynamicLibrary() : m_handle(0) { } |
1948bb32 VS |
175 | wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT) |
176 | : m_handle(0) | |
177 | { | |
178 | Load(libname, flags); | |
179 | } | |
1948bb32 | 180 | |
4104ed92 VZ |
181 | // NOTE: this class is (deliberately) not virtual, do not attempt |
182 | // to use it polymorphically. | |
183 | ~wxDynamicLibrary() { Unload(); } | |
1948bb32 | 184 | |
68379eaf | 185 | // return true if the library was loaded successfully |
1948bb32 VS |
186 | bool IsLoaded() const { return m_handle != 0; } |
187 | ||
4104ed92 | 188 | // load the library with the given name (full or not), return true if ok |
defbed48 | 189 | bool Load(const wxString& libname, int flags = wxDL_DEFAULT); |
1948bb32 | 190 | |
defbed48 VZ |
191 | // raw function for loading dynamic libs: always behaves as if |
192 | // wxDL_VERBATIM were specified and doesn't log error message if the | |
193 | // library couldn't be loaded but simply returns NULL | |
da55d064 VZ |
194 | static wxDllType RawLoad(const wxString& libname, int flags = wxDL_DEFAULT); |
195 | ||
4104ed92 VZ |
196 | // detach the library object from its handle, i.e. prevent the object from |
197 | // unloading the library in its dtor -- the caller is now responsible for | |
198 | // doing this | |
1948bb32 VS |
199 | wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; } |
200 | ||
169948a0 VZ |
201 | // unload the given library handle (presumably returned by Detach() before) |
202 | static void Unload(wxDllType handle); | |
203 | ||
4104ed92 | 204 | // unload the library, also done automatically in dtor |
169948a0 | 205 | void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } } |
1948bb32 | 206 | |
4104ed92 | 207 | // Return the raw handle from dlopen and friends. |
1948bb32 VS |
208 | wxDllType GetLibHandle() const { return m_handle; } |
209 | ||
a018a119 VZ |
210 | // check if the given symbol is present in the library, useful to verify if |
211 | // a loadable module is our plugin, for example, without provoking error | |
212 | // messages from GetSymbol() | |
213 | bool HasSymbol(const wxString& name) const | |
214 | { | |
215 | bool ok; | |
216 | DoGetSymbol(name, &ok); | |
217 | return ok; | |
218 | } | |
219 | ||
4104ed92 VZ |
220 | // resolve a symbol in a loaded DLL, such as a variable or function name. |
221 | // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to | |
222 | // export unmangled names) | |
223 | // | |
224 | // Since it is perfectly valid for the returned symbol to actually be NULL, | |
225 | // that is not always indication of an error. Pass and test the parameter | |
226 | // 'success' for a true indication of success or failure to load the | |
227 | // symbol. | |
228 | // | |
229 | // Returns a pointer to the symbol on success, or NULL if an error occurred | |
230 | // or the symbol wasn't found. | |
defbed48 | 231 | void *GetSymbol(const wxString& name, bool *success = NULL) const; |
1948bb32 | 232 | |
defbed48 VZ |
233 | // low-level version of GetSymbol() |
234 | static void *RawGetSymbol(wxDllType handle, const wxString& name); | |
235 | void *RawGetSymbol(const wxString& name) const | |
236 | { | |
fd6c9428 SN |
237 | #if defined (__WXPM__) || defined(__EMX__) |
238 | return GetSymbol(name); | |
239 | #else | |
defbed48 | 240 | return RawGetSymbol(m_handle, name); |
fd6c9428 | 241 | #endif |
defbed48 VZ |
242 | } |
243 | ||
93ed8ff7 VZ |
244 | #ifdef __WXMSW__ |
245 | // this function is useful for loading functions from the standard Windows | |
246 | // DLLs: such functions have an 'A' (in ANSI build) or 'W' (in Unicode, or | |
247 | // wide character build) suffix if they take string parameters | |
248 | static void *RawGetSymbolAorW(wxDllType handle, const wxString& name) | |
249 | { | |
250 | return RawGetSymbol | |
251 | ( | |
252 | handle, | |
253 | name + | |
254 | #if wxUSE_UNICODE | |
255 | L'W' | |
256 | #else | |
257 | 'A' | |
258 | #endif | |
259 | ); | |
260 | } | |
261 | ||
262 | void *GetSymbolAorW(const wxString& name) const | |
263 | { | |
264 | return RawGetSymbolAorW(m_handle, name); | |
265 | } | |
266 | #endif // __WXMSW__ | |
267 | ||
defbed48 VZ |
268 | // return all modules/shared libraries in the address space of this process |
269 | // | |
3103e8a9 | 270 | // returns an empty array if not implemented or an error occurred |
defbed48 | 271 | static wxDynamicLibraryDetailsArray ListLoaded(); |
0c32066b | 272 | |
1948bb32 VS |
273 | // return platform-specific name of dynamic library with proper extension |
274 | // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux) | |
275 | static wxString CanonicalizeName(const wxString& name, | |
276 | wxDynamicLibraryCategory cat = wxDL_LIBRARY); | |
277 | ||
77ffb593 | 278 | // return name of wxWidgets plugin (adds compiler and version info |
1948bb32 | 279 | // to the filename): |
169948a0 VZ |
280 | static wxString |
281 | CanonicalizePluginName(const wxString& name, | |
282 | wxPluginCategory cat = wxDL_PLUGIN_GUI); | |
1948bb32 VS |
283 | |
284 | // return plugin directory on platforms where it makes sense and empty | |
285 | // string on others: | |
286 | static wxString GetPluginsDirectory(); | |
287 | ||
1948bb32 | 288 | |
4104ed92 VZ |
289 | #if WXWIN_COMPATIBILITY_2_2 |
290 | operator bool() const { return IsLoaded(); } | |
291 | #endif | |
1948bb32 | 292 | |
4104ed92 | 293 | protected: |
defbed48 | 294 | // common part of GetSymbol() and HasSymbol() |
a018a119 VZ |
295 | void *DoGetSymbol(const wxString& name, bool *success = 0) const; |
296 | ||
da55d064 VZ |
297 | #ifdef wxHAVE_DYNLIB_ERROR |
298 | // log the error after a dlxxx() function failure | |
299 | static void Error(); | |
300 | #endif // wxHAVE_DYNLIB_ERROR | |
301 | ||
a018a119 | 302 | |
4104ed92 | 303 | // platform specific shared lib suffix. |
1948bb32 VS |
304 | static const wxChar *ms_dllext; |
305 | ||
4104ed92 | 306 | // the handle to DLL or NULL |
1948bb32 VS |
307 | wxDllType m_handle; |
308 | ||
4104ed92 VZ |
309 | // no copy ctor/assignment operators (or we'd try to unload the library |
310 | // twice) | |
1948bb32 VS |
311 | DECLARE_NO_COPY_CLASS(wxDynamicLibrary) |
312 | }; | |
313 | ||
314 | ||
a585ca5c | 315 | // ---------------------------------------------------------------------------- |
33a8563e | 316 | // wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code |
a585ca5c | 317 | // ---------------------------------------------------------------------------- |
3c1a88d8 | 318 | |
1948bb32 VS |
319 | #if WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER |
320 | ||
f3cb0d85 VZ |
321 | #include "wx/object.h" |
322 | ||
33a8563e VZ |
323 | /* |
324 | wxDllLoader is a class providing an interface similar to unix's dlopen(). | |
325 | It is used by wxDynamicLibrary wxLibrary and manages the actual loading of | |
326 | DLLs and the resolving of symbols in them. There are no instances of this | |
327 | class, it simply serves as a namespace for its static member functions. | |
a585ca5c | 328 | */ |
bddd7a8d | 329 | class WXDLLIMPEXP_BASE wxDllLoader |
a585ca5c | 330 | { |
3c1a88d8 | 331 | public: |
33a8563e VZ |
332 | /* |
333 | This function loads the shared library libname into memory. | |
334 | ||
335 | libname may be either the full path to the file or just the filename in | |
336 | which case the library is searched for in all standard locations | |
337 | (use GetDllExt() to construct the filename) | |
338 | ||
68379eaf WS |
339 | if success pointer is not NULL, it will be filled with true if everything |
340 | went ok and false otherwise | |
33a8563e | 341 | */ |
1948bb32 | 342 | static wxDllType LoadLibrary(const wxString& name, bool *success = NULL); |
68379eaf | 343 | |
33a8563e VZ |
344 | /* |
345 | This function unloads the shared library previously loaded with | |
346 | LoadLibrary | |
3c1a88d8 | 347 | */ |
3c1a88d8 | 348 | static void UnloadLibrary(wxDllType dll); |
33a8563e VZ |
349 | |
350 | /* | |
351 | This function returns a valid handle for the main program | |
352 | itself or NULL if back linking is not supported by the current platform | |
353 | (e.g. Win32). | |
354 | */ | |
1948bb32 | 355 | static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); } |
33a8563e VZ |
356 | |
357 | /* | |
358 | This function resolves a symbol in a loaded DLL, such as a | |
359 | variable or function name. | |
360 | ||
361 | dllHandle Handle of the DLL, as returned by LoadDll(). | |
362 | name Name of the symbol. | |
363 | ||
364 | Returns the pointer to the symbol or NULL on error. | |
3c1a88d8 | 365 | */ |
1948bb32 | 366 | static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0); |
3c1a88d8 | 367 | |
f6bcfd97 | 368 | // return the standard DLL extension (with leading dot) for this platform |
1948bb32 | 369 | static wxString GetDllExt() { return wxDynamicLibrary::GetDllExt(); } |
f6bcfd97 | 370 | |
3c1a88d8 | 371 | private: |
181b4068 | 372 | |
1948bb32 | 373 | wxDllLoader(); // forbid construction of objects |
33a8563e | 374 | }; |
181b4068 | 375 | |
1948bb32 | 376 | |
7b0bfbb2 | 377 | // ---------------------------------------------------------------------------- |
7a4b9130 | 378 | // wxLibrary |
7b0bfbb2 | 379 | // ---------------------------------------------------------------------------- |
7a4b9130 | 380 | |
1948bb32 VS |
381 | #include "wx/hash.h" |
382 | ||
bddd7a8d | 383 | class WXDLLIMPEXP_BASE wxLibrary : public wxObject |
7b0bfbb2 | 384 | { |
7b0bfbb2 | 385 | public: |
8a0d4cf6 | 386 | wxLibrary(wxDllType handle); |
33a8563e | 387 | virtual ~wxLibrary(); |
7a4b9130 | 388 | |
7b0bfbb2 VZ |
389 | // Get a symbol from the dynamic library |
390 | void *GetSymbol(const wxString& symbname); | |
7a4b9130 | 391 | |
7b0bfbb2 VZ |
392 | // Create the object whose classname is "name" |
393 | wxObject *CreateObject(const wxString& name); | |
7a4b9130 | 394 | |
7b0bfbb2 VZ |
395 | protected: |
396 | void PrepareClasses(wxClassInfo *first); | |
f4a8c29f | 397 | |
7b0bfbb2 | 398 | wxDllType m_handle; |
a585ca5c | 399 | |
33a8563e VZ |
400 | public: |
401 | wxHashTable classTable; | |
402 | }; | |
a585ca5c | 403 | |
7b0bfbb2 | 404 | // ---------------------------------------------------------------------------- |
7a4b9130 | 405 | // wxLibraries |
7b0bfbb2 VZ |
406 | // ---------------------------------------------------------------------------- |
407 | ||
bddd7a8d | 408 | class WXDLLIMPEXP_BASE wxLibraries |
7b0bfbb2 VZ |
409 | { |
410 | public: | |
411 | wxLibraries(); | |
412 | ~wxLibraries(); | |
7a4b9130 | 413 | |
7b0bfbb2 VZ |
414 | // caller is responsible for deleting the returned pointer if !NULL |
415 | wxLibrary *LoadLibrary(const wxString& basename); | |
7a4b9130 | 416 | |
7b0bfbb2 VZ |
417 | wxObject *CreateObject(const wxString& name); |
418 | ||
419 | protected: | |
420 | wxList m_loaded; | |
7a4b9130 GL |
421 | }; |
422 | ||
7b0bfbb2 | 423 | // ---------------------------------------------------------------------------- |
7a4b9130 | 424 | // Global variables |
7b0bfbb2 | 425 | // ---------------------------------------------------------------------------- |
7a4b9130 | 426 | |
bddd7a8d | 427 | extern WXDLLIMPEXP_DATA_BASE(wxLibraries) wxTheLibraries; |
7a4b9130 | 428 | |
1948bb32 VS |
429 | #endif // WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER |
430 | ||
7b0bfbb2 | 431 | // ---------------------------------------------------------------------------- |
7a4b9130 | 432 | // Interesting defines |
7b0bfbb2 | 433 | // ---------------------------------------------------------------------------- |
7a4b9130 | 434 | |
f4a8c29f | 435 | #define WXDLL_ENTRY_FUNCTION() \ |
ad8b3990 | 436 | extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \ |
1b733817 | 437 | const wxClassInfo *wxGetClassFirst() { \ |
856d2e52 | 438 | return wxClassInfo::GetFirst(); \ |
f4a8c29f | 439 | } |
7a4b9130 | 440 | |
8a0d4cf6 VZ |
441 | #endif // wxUSE_DYNLIB_CLASS |
442 | ||
7b0bfbb2 | 443 | #endif // _WX_DYNLIB_H__ |