1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: documentation for wxDynamicLibraryDetails class
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxDynamicLibraryDetails
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.
22 class wxDynamicLibraryDetails
26 Retrieves the load address and the size of this module.
29 the pointer to the location to return load address in, may be
33 pointer to the location to return the size of this module in
34 memory in, may be @NULL
36 @returns @true if the load address and module size were retrieved, @false
37 if this information is not available.
39 bool GetAddress(void ** addr
, size_t len
);
42 Returns the base name of this module, e.g. @c kernel32.dll or
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.
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
59 wxString
GetVersion();
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.
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
77 Please note that class wxDynamicLibrary provides
78 alternative, friendlier interface to wxDllLoader.
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.
84 Example of using this class to dynamically load the @c strlen() function:
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");
95 wxDllType dllHandle = wxDllLoader::LoadLibrary(LIB_NAME);
102 typedef int (*strlenType)(char *);
103 strlenType pfnStrlen = (strlenType)wxDllLoader::GetSymbol(dllHandle,
111 if ( pfnStrlen("foo") != 3 )
121 wxDllLoader::UnloadLibrary(dllHandle);
126 @category{appmanagement}
132 Returns the string containing the usual extension for shared libraries for the
133 given systems (including the leading dot if not empty).
135 For example, this function will return @c ".dll" under Windows or (usually)
138 static wxString
GetDllExt();
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).
145 @b NB: This function is Unix specific. It will always fail under Windows
148 wxDllType
GetProgramHandle();
151 This function resolves a symbol in a loaded DLL, such as a variable or
154 Returned value will be @NULL if the symbol was not found in the DLL or if
158 Valid handle previously returned by
164 void * GetSymbol(wxDllType dllHandle
, const wxString
& name
);
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.
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
178 Name of the shared object to load.
181 May point to a bool variable which will be set to @true or
182 @false; may also be @NULL.
184 wxDllType
LoadLibrary(const wxString
& libname
,
185 bool* success
= @NULL
);
188 This function unloads the shared library. The handle @e dllhandle must have
189 been returned by LoadLibrary() previously.
191 void UnloadLibrary(wxDllType dllhandle
);
196 @class wxDynamicLibrary
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.
208 wxDynamicLibrary::CanonicalizePluginName
210 class wxDynamicLibrary
215 Constructor. Second form calls Load().
218 wxDynamicLibrary(const wxString
& name
,
219 int flags
= wxDL_DEFAULT
);
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.
227 The possible values for @e cat are:
241 a loadable module or plugin
244 @sa CanonicalizePluginName()
246 static wxString
CanonicalizeName(const wxString
& name
,
247 wxDynamicLibraryCategory cat
= wxDL_LIBRARY
);
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.
256 The possible values for @e cat are:
263 plugin which uses GUI classes (default)
270 plugin which only uses wxBase
272 static wxString
CanonicalizePluginName(const wxString
& name
,
273 wxPluginCategory cat
= wxDL_PLUGIN_GUI
);
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().
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.
286 static wxDllType
GetProgramHandle();
289 Returns pointer to symbol @e name in the library or @NULL if the library
290 contains no such symbol.
292 @sa wxDYNLIB_FUNCTION
294 void * GetSymbol(const wxString
& name
);
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().
305 void * GetSymbolAorW(const wxString
& name
);
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.
312 This function is new since wxWidgets version 2.5.4
314 bool HasSymbol(const wxString
& name
);
317 Returns @true if the library was successfully loaded, @false otherwise.
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.
327 This method is currently implemented only under Win32 and Linux and is useful
328 mostly for diagnostics purposes.
330 static wxDynamicLibraryDetailsArray
ListLoaded();
333 Loads DLL with the given @e name into memory. The @e flags argument can
334 be a combination of the following bits:
339 equivalent of RTLD_LAZY under Unix, ignored elsewhere
344 equivalent of RTLD_NOW under Unix, ignored elsewhere
349 equivalent of RTLD_GLOBAL under Unix, ignored elsewhere
354 don't try to append the appropriate extension to
355 the library name (this is done by default).
360 default flags, same as wxDL_NOW currently
365 don't log an error message if the library couldn't be
368 Returns @true if the library was successfully loaded, @false otherwise.
370 bool Load(const wxString
& name
, int flags
= wxDL_DEFAULT
);
374 Unloads the library from memory. wxDynamicLibrary object automatically calls
375 this method from its destructor if it had been successfully loaded.
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.
383 static void Unload(wxDllType handle
);
388 // ============================================================================
389 // Global functions/macros
390 // ============================================================================
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
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
405 the type of the function
408 the name of the function to load, not a string (without quotes,
409 it is quoted automatically by the macro)
412 the library to load the function from
414 #define wxDYNLIB_FUNCTION(type, name, dynlib) /* implementation is private */