interface/dynlib.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dynlib.h
   3 // Purpose:     interface of wxDynamicLibraryDetails
   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) const;
  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() const;
  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() const;
  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() const;
  59 };
  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         For example, this function will return @c ".dll" under Windows or (usually)
 135         @c ".so" under Unix.
 136     */
 137     static wxString GetDllExt();
 138
 139     /**
 140         This function returns a valid handle for the main program itself. Notice that
 141         the @NULL return value is valid for some systems (i.e. doesn't mean that
 142         the function failed).
 143         @note This function is Unix specific. It will always fail under Windows
 144         or OS/2.
 145     */
 146     wxDllType GetProgramHandle();
 147
 148     /**
 149         This function resolves a symbol in a loaded DLL, such as a variable or
 150         function name.
 151         Returned value will be @NULL if the symbol was not found in the DLL or if
 152         an error occurred.
 153
 154         @param dllHandle
 155             Valid handle previously returned by
 156             LoadLibrary
 157         @param name
 158             Name of the symbol.
 159     */
 160     void* GetSymbol(wxDllType dllHandle, const wxString& name);
 161
 162     /**
 163         This function loads a shared library into memory, with @a libname being the
 164         name of the library: it may be either the full name including path and
 165         (platform-dependent) extension, just the basename (no path and no extension)
 166         or a basename with extension. In the last two cases, the library will be
 167         searched in all standard locations.
 168         Returns a handle to the loaded DLL. Use @a success parameter to test if it
 169         is valid. If the handle is valid, the library must be unloaded later with
 170         UnloadLibrary().
 171
 172         @param libname
 173             Name of the shared object to load.
 174         @param success
 175             May point to a bool variable which will be set to @true or
 176             @false; may also be @NULL.
 177     */
 178     wxDllType LoadLibrary(const wxString& libname,
 179                           bool* success = NULL);
 180
 181     /**
 182         This function unloads the shared library. The handle @a dllhandle must have
 183         been returned by LoadLibrary() previously.
 184     */
 185     void UnloadLibrary(wxDllType dllhandle);
 186 };
 187
 188
 189
 190 /**
 191     @class wxDynamicLibrary
 192     @wxheader{dynlib.h}
 193
 194     wxDynamicLibrary is a class representing dynamically loadable library
 195     (Windows DLL, shared library under Unix etc.). Just create an object of
 196     this class to load a library and don't worry about unloading it -- it will be
 197     done in the objects destructor automatically.
 198
 199     @library{wxbase}
 200     @category{FIXME}
 201
 202     @see wxDynamicLibrary::CanonicalizePluginName
 203 */
 204 class wxDynamicLibrary
 205 {
 206 public:
 207     //@{
 208     /**
 209         Constructor. Second form calls Load().
 210     */
 211     wxDynamicLibrary();
 212     wxDynamicLibrary(const wxString& name,
 213                      int flags = wxDL_DEFAULT);
 214     //@}
 215
 216     /**
 217         Returns the platform-specific full name for the library called @e name. E.g.
 218         it adds a @c ".dll" extension under Windows and @c "lib" prefix and
 219         @c ".so", @c ".sl" or maybe @c ".dylib" extension under Unix.
 220         The possible values for @a cat are:
 221
 222
 223         wxDL_LIBRARY
 224
 225         normal library
 226
 227         wxDL_MODULE
 228
 229         a loadable module or plugin
 230
 231         @see CanonicalizePluginName()
 232     */
 233     static wxString CanonicalizeName(const wxString& name,
 234                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 235
 236     /**
 237         This function does the same thing as
 238         CanonicalizeName() but for wxWidgets
 239         plugins. The only difference is that compiler and version information are added
 240         to the name to ensure that the plugin which is going to be loaded will be
 241         compatible with the main program.
 242         The possible values for @a cat are:
 243
 244
 245         wxDL_PLUGIN_GUI
 246
 247         plugin which uses GUI classes (default)
 248
 249         wxDL_PLUGIN_BASE
 250
 251         plugin which only uses wxBase
 252     */
 253     static wxString CanonicalizePluginName(const wxString& name,
 254                                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 255
 256     /**
 257         Detaches this object from its library handle, i.e. the object will not unload
 258         the library any longer in its destructor but it is now the callers
 259         responsibility to do this using Unload().
 260     */
 261     wxDllType Detach();
 262
 263     /**
 264         Return a valid handle for the main program itself or @NULL if symbols
 265         from the main program can't be loaded on this platform.
 266     */
 267     static wxDllType GetProgramHandle();
 268
 269     /**
 270         Returns pointer to symbol @a name in the library or @NULL if the library
 271         contains no such symbol.
 272
 273         @see wxDYNLIB_FUNCTION()
 274     */
 275     void* GetSymbol(const wxString& name) const;
 276
 277     /**
 278         This function is available only under Windows as it is only useful when
 279         dynamically loading symbols from standard Windows DLLs. Such functions have
 280         either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide
 281         character build) suffix if they take string parameters. Using this function you
 282         can use just the base name of the function and the correct suffix is appende
 283         automatically depending on the current build. Otherwise, this method is
 284         identical to GetSymbol().
 285     */
 286     void* GetSymbolAorW(const wxString& name) const;
 287
 288     /**
 289         Returns @true if the symbol with the given @a name is present in the dynamic
 290         library, @false otherwise. Unlike GetSymbol(),
 291         this function doesn't log an error message if the symbol is not found.
 292
 293         @wxsince{2.5.4}
 294     */
 295     bool HasSymbol(const wxString& name) const;
 296
 297     /**
 298         Returns @true if the library was successfully loaded, @false otherwise.
 299     */
 300     bool IsLoaded() const;
 301
 302     /**
 303         This static method returns an array() containing the details
 304         of all modules loaded into the address space of the current project, the array
 305         elements are object of @c wxDynamicLibraryDetails class. The array will
 306         be empty if an error occurred.
 307         This method is currently implemented only under Win32 and Linux and is useful
 308         mostly for diagnostics purposes.
 309     */
 310     static wxDynamicLibraryDetailsArray ListLoaded();
 311
 312     /**
 313         Loads DLL with the given @a name into memory. The @a flags argument can
 314         be a combination of the following bits:
 315
 316         wxDL_LAZY
 317
 318         equivalent of RTLD_LAZY under Unix, ignored elsewhere
 319
 320         wxDL_NOW
 321
 322         equivalent of RTLD_NOW under Unix, ignored elsewhere
 323
 324         wxDL_GLOBAL
 325
 326         equivalent of RTLD_GLOBAL under Unix, ignored elsewhere
 327
 328         wxDL_VERBATIM
 329
 330         don't try to append the appropriate extension to
 331         the library name (this is done by default).
 332
 333         wxDL_DEFAULT
 334
 335         default flags, same as wxDL_NOW currently
 336
 337         wxDL_QUIET
 338
 339         don't log an error message if the library couldn't be
 340         loaded.
 341
 342         Returns @true if the library was successfully loaded, @false otherwise.
 343     */
 344     bool Load(const wxString& name, int flags = wxDL_DEFAULT);
 345
 346     //@{
 347     /**
 348         Unloads the library from memory. wxDynamicLibrary object automatically calls
 349         this method from its destructor if it had been successfully loaded.
 350         The second version is only used if you need to keep the library in memory
 351         during a longer period of time than the scope of the wxDynamicLibrary object.
 352         In this case you may call Detach() and store
 353         the handle somewhere and call this static method later to unload it.
 354     */
 355     void Unload();
 356     static void Unload(wxDllType handle);
 357     //@}
 358 };
 359
 360
 361
 362 // ============================================================================
 363 // Global functions/macros
 364 // ============================================================================
 365
 366 /** @ingroup group_funcmacro_misc */
 367 //@{
 368
 369 /**
 370     When loading a function from a DLL you always have to cast the returned
 371     <tt>void *</tt> pointer to the correct type and, even more annoyingly, you
 372     have to repeat this type twice if you want to declare and define a function
 373     pointer all in one line.
 374
 375     This macro makes this slightly less painful by allowing you to specify the
 376     type only once, as the first parameter, and creating a variable of this
 377     type named after the function but with @c pfn prefix and initialized with
 378     the function @a name from the wxDynamicLibrary @a dynlib.
 379
 380     @param type
 381         The type of the function.
 382     @param name
 383         The name of the function to load, not a string (without quotes, it is
 384         quoted automatically by the macro).
 385     @param dynlib
 386         The library to load the function from.
 387
 388     @header{wx/dynlib.h}
 389 */
 390 #define wxDYNLIB_FUNCTION(type, name, dynlib)
 391
 392 //@}
 393