]> git.saurik.com Git - wxWidgets.git/blob - interface/dynlib.h
8f389f34a10034a65f49b1c0786905fe30ca9163
[wxWidgets.git] / interface / dynlib.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: dynlib.h
3 // Purpose: documentation for wxDynamicLibraryDetails class
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxDynamicLibraryDetails
11 @wxheader{dynlib.h}
12
13 This class is used for the objects returned by
14 wxDynamicLibrary::ListLoaded method and
15 contains the information about a single module loaded into the address space of
16 the current process. A module in this context may be either a dynamic library
17 or the main program itself.
18
19 @library{wxbase}
20 @category{FIXME}
21 */
22 class wxDynamicLibraryDetails
23 {
24 public:
25 /**
26 Retrieves the load address and the size of this module.
27
28 @param addr
29 the pointer to the location to return load address in, may be
30 @NULL
31
32 @param len
33 pointer to the location to return the size of this module in
34 memory in, may be @NULL
35
36 @returns @true if the load address and module size were retrieved, @false
37 if this information is not available.
38 */
39 bool GetAddress(void ** addr, size_t len);
40
41 /**
42 Returns the base name of this module, e.g. @c kernel32.dll or
43 @c libc-2.3.2.so.
44 */
45 wxString GetName();
46
47 /**
48 Returns the full path of this module if available, e.g.
49 @c c:\windows\system32\kernel32.dll or
50 @c /lib/libc-2.3.2.so.
51 */
52 wxString GetPath();
53
54 /**
55 Returns the version of this module, e.g. @c 5.2.3790.0 or
56 @c 2.3.2. The returned string is empty if the version information is not
57 available.
58 */
59 wxString GetVersion();
60 };
61
62
63 /**
64 @class wxDllLoader
65 @wxheader{dynlib.h}
66
67 @b Deprecation note: This class is deprecated since version 2.4 and is
68 not compiled in by default in version 2.6 and will be removed in 2.8. Please
69 use wxDynamicLibrary instead.
70
71 wxDllLoader is a class providing an interface similar to Unix's @c dlopen(). It
72 is used by the wxLibrary framework and manages the actual
73 loading of shared libraries and the resolving of symbols in them. There are no
74 instances of this class, it simply serves as a namespace for its static member
75 functions.
76
77 Please note that class wxDynamicLibrary provides
78 alternative, friendlier interface to wxDllLoader.
79
80 The terms @e DLL and @e shared library/object will both be used in the
81 documentation to refer to the same thing: a @c .dll file under Windows or
82 @c .so or @c .sl one under Unix.
83
84 Example of using this class to dynamically load the @c strlen() function:
85
86 @code
87 #if defined(__WXMSW__)
88 static const wxChar *LIB_NAME = _T("kernel32");
89 static const wxChar *FUNC_NAME = _T("lstrlenA");
90 #elif defined(__UNIX__)
91 static const wxChar *LIB_NAME = _T("/lib/libc-2.0.7.so");
92 static const wxChar *FUNC_NAME = _T("strlen");
93 #endif
94
95 wxDllType dllHandle = wxDllLoader::LoadLibrary(LIB_NAME);
96 if ( !dllHandle )
97 {
98 ... error ...
99 }
100 else
101 {
102 typedef int (*strlenType)(char *);
103 strlenType pfnStrlen = (strlenType)wxDllLoader::GetSymbol(dllHandle,
104 FUNC_NAME);
105 if ( !pfnStrlen )
106 {
107 ... error ...
108 }
109 else
110 {
111 if ( pfnStrlen("foo") != 3 )
112 {
113 ... error ...
114 }
115 else
116 {
117 ... ok! ...
118 }
119 }
120
121 wxDllLoader::UnloadLibrary(dllHandle);
122 }
123 @endcode
124
125 @library{wxbase}
126 @category{appmanagement}
127 */
128 class wxDllLoader
129 {
130 public:
131 /**
132 Returns the string containing the usual extension for shared libraries for the
133 given systems (including the leading dot if not empty).
134
135 For example, this function will return @c ".dll" under Windows or (usually)
136 @c ".so" under Unix.
137 */
138 static wxString GetDllExt();
139
140 /**
141 This function returns a valid handle for the main program itself. Notice that
142 the @NULL return value is valid for some systems (i.e. doesn't mean that
143 the function failed).
144
145 @b NB: This function is Unix specific. It will always fail under Windows
146 or OS/2.
147 */
148 wxDllType GetProgramHandle();
149
150 /**
151 This function resolves a symbol in a loaded DLL, such as a variable or
152 function name.
153
154 Returned value will be @NULL if the symbol was not found in the DLL or if
155 an error occurred.
156
157 @param dllHandle
158 Valid handle previously returned by
159 LoadLibrary
160
161 @param name
162 Name of the symbol.
163 */
164 void * GetSymbol(wxDllType dllHandle, const wxString& name);
165
166 /**
167 This function loads a shared library into memory, with @e libname being the
168 name of the library: it may be either the full name including path and
169 (platform-dependent) extension, just the basename (no path and no extension)
170 or a basename with extension. In the last two cases, the library will be
171 searched in all standard locations.
172
173 Returns a handle to the loaded DLL. Use @e success parameter to test if it
174 is valid. If the handle is valid, the library must be unloaded later with
175 UnloadLibrary().
176
177 @param libname
178 Name of the shared object to load.
179
180 @param success
181 May point to a bool variable which will be set to @true or
182 @false; may also be @NULL.
183 */
184 wxDllType LoadLibrary(const wxString & libname,
185 bool* success = @NULL);
186
187 /**
188 This function unloads the shared library. The handle @e dllhandle must have
189 been returned by LoadLibrary() previously.
190 */
191 void UnloadLibrary(wxDllType dllhandle);
192 };
193
194
195 /**
196 @class wxDynamicLibrary
197 @wxheader{dynlib.h}
198
199 wxDynamicLibrary is a class representing dynamically loadable library
200 (Windows DLL, shared library under Unix etc.). Just create an object of
201 this class to load a library and don't worry about unloading it -- it will be
202 done in the objects destructor automatically.
203
204 @library{wxbase}
205 @category{FIXME}
206
207 @seealso
208 wxDynamicLibrary::CanonicalizePluginName
209 */
210 class wxDynamicLibrary
211 {
212 public:
213 //@{
214 /**
215 Constructor. Second form calls Load().
216 */
217 wxDynamicLibrary();
218 wxDynamicLibrary(const wxString& name,
219 int flags = wxDL_DEFAULT);
220 //@}
221
222 /**
223 Returns the platform-specific full name for the library called @e name. E.g.
224 it adds a @c ".dll" extension under Windows and @c "lib" prefix and
225 @c ".so", @c ".sl" or maybe @c ".dylib" extension under Unix.
226
227 The possible values for @e cat are:
228
229
230
231 wxDL_LIBRARY
232
233
234 normal library
235
236
237
238 wxDL_MODULE
239
240
241 a loadable module or plugin
242
243
244 @sa CanonicalizePluginName()
245 */
246 static wxString CanonicalizeName(const wxString& name,
247 wxDynamicLibraryCategory cat = wxDL_LIBRARY);
248
249 /**
250 This function does the same thing as
251 CanonicalizeName() but for wxWidgets
252 plugins. The only difference is that compiler and version information are added
253 to the name to ensure that the plugin which is going to be loaded will be
254 compatible with the main program.
255
256 The possible values for @e cat are:
257
258
259
260 wxDL_PLUGIN_GUI
261
262
263 plugin which uses GUI classes (default)
264
265
266
267 wxDL_PLUGIN_BASE
268
269
270 plugin which only uses wxBase
271 */
272 static wxString CanonicalizePluginName(const wxString& name,
273 wxPluginCategory cat = wxDL_PLUGIN_GUI);
274
275 /**
276 Detaches this object from its library handle, i.e. the object will not unload
277 the library any longer in its destructor but it is now the callers
278 responsibility to do this using Unload().
279 */
280 wxDllType Detach();
281
282 /**
283 Return a valid handle for the main program itself or @NULL if symbols
284 from the main program can't be loaded on this platform.
285 */
286 static wxDllType GetProgramHandle();
287
288 /**
289 Returns pointer to symbol @e name in the library or @NULL if the library
290 contains no such symbol.
291
292 @sa wxDYNLIB_FUNCTION
293 */
294 void * GetSymbol(const wxString& name);
295
296 /**
297 This function is available only under Windows as it is only useful when
298 dynamically loading symbols from standard Windows DLLs. Such functions have
299 either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide
300 character build) suffix if they take string parameters. Using this function you
301 can use just the base name of the function and the correct suffix is appende
302 automatically depending on the current build. Otherwise, this method is
303 identical to GetSymbol().
304 */
305 void * GetSymbolAorW(const wxString& name);
306
307 /**
308 Returns @true if the symbol with the given @e name is present in the dynamic
309 library, @false otherwise. Unlike GetSymbol(),
310 this function doesn't log an error message if the symbol is not found.
311
312 This function is new since wxWidgets version 2.5.4
313 */
314 bool HasSymbol(const wxString& name);
315
316 /**
317 Returns @true if the library was successfully loaded, @false otherwise.
318 */
319 bool IsLoaded();
320
321 /**
322 This static method returns an array containing the details
323 of all modules loaded into the address space of the current project, the array
324 elements are object of @c wxDynamicLibraryDetails class. The array will
325 be empty if an error occurred.
326
327 This method is currently implemented only under Win32 and Linux and is useful
328 mostly for diagnostics purposes.
329 */
330 static wxDynamicLibraryDetailsArray ListLoaded();
331
332 /**
333 Loads DLL with the given @e name into memory. The @e flags argument can
334 be a combination of the following bits:
335
336 wxDL_LAZY
337
338
339 equivalent of RTLD_LAZY under Unix, ignored elsewhere
340
341 wxDL_NOW
342
343
344 equivalent of RTLD_NOW under Unix, ignored elsewhere
345
346 wxDL_GLOBAL
347
348
349 equivalent of RTLD_GLOBAL under Unix, ignored elsewhere
350
351 wxDL_VERBATIM
352
353
354 don't try to append the appropriate extension to
355 the library name (this is done by default).
356
357 wxDL_DEFAULT
358
359
360 default flags, same as wxDL_NOW currently
361
362 wxDL_QUIET
363
364
365 don't log an error message if the library couldn't be
366 loaded.
367
368 Returns @true if the library was successfully loaded, @false otherwise.
369 */
370 bool Load(const wxString& name, int flags = wxDL_DEFAULT);
371
372 //@{
373 /**
374 Unloads the library from memory. wxDynamicLibrary object automatically calls
375 this method from its destructor if it had been successfully loaded.
376
377 The second version is only used if you need to keep the library in memory
378 during a longer period of time than the scope of the wxDynamicLibrary object.
379 In this case you may call Detach() and store
380 the handle somewhere and call this static method later to unload it.
381 */
382 void Unload();
383 static void Unload(wxDllType handle);
384 //@}
385 };
386
387
388 // ============================================================================
389 // Global functions/macros
390 // ============================================================================
391
392 /**
393 When loading a function from a DLL you always have to cast the returned
394 @c void * pointer to the correct type and, even more annoyingly, you have to
395 repeat this type twice if you want to declare and define a function pointer all
396 in one line
397
398 This macro makes this slightly less painful by allowing you to specify the
399 type only once, as the first parameter, and creating a variable of this type
400 named after the function but with @c pfn prefix and initialized with the
401 function @e name from the wxDynamicLibrary
402 @e dynlib.
403
404 @param type
405 the type of the function
406
407 @param name
408 the name of the function to load, not a string (without quotes,
409 it is quoted automatically by the macro)
410
411 @param dynlib
412 the library to load the function from
413 */
414 #define wxDYNLIB_FUNCTION(type, name, dynlib) /* implementation is private */
415