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