interface/wx/dynlib.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dynlib.h
   3 // Purpose:     interface of wxDynamicLibrary and wxDynamicLibraryDetails
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDynamicLibraryDetails
  11
  12     This class is used for the objects returned by the
  13     wxDynamicLibrary::ListLoaded() method and contains the information about a
  14     single module loaded into the address space of the current process. A
  15     module in this context may be either a dynamic library or the main program
  16     itself.
  17
  18     @library{wxbase}
  19     @category{appmanagement}
  20 */
  21 class wxDynamicLibraryDetails
  22 {
  23 public:
  24     /**
  25         Retrieves the load address and the size of this module.
  26
  27         @param addr
  28             The pointer to the location to return load address in, may be
  29             @NULL.
  30         @param len
  31             Pointer to the location to return the size of this module in
  32             memory in, may be @NULL.
  33
  34         @return @true if the load address and module size were retrieved,
  35                  @false if this information is not available.
  36     */
  37     bool GetAddress(void* addr, size_t* len) const;
  38
  39     /**
  40         Returns the base name of this module, e.g. @c "kernel32.dll" or
  41         @c "libc-2.3.2.so".
  42     */
  43     wxString GetName() const;
  44
  45     /**
  46         Returns the full path of this module if available, e.g.
  47         @c "c:\windows\system32\kernel32.dll" or @c "/lib/libc-2.3.2.so".
  48     */
  49     wxString GetPath() const;
  50
  51     /**
  52         Returns the version of this module, e.g. @c "5.2.3790.0" or @c "2.3.2".
  53         The returned string is empty if the version information is not
  54         available.
  55     */
  56     wxString GetVersion() const;
  57 };
  58
  59
  60
  61 /**
  62     Dynamic library category used with wxDynamicLibrary::CanonicalizeName().
  63 */
  64 enum wxDynamicLibraryCategory
  65 {
  66     wxDL_LIBRARY,   ///< Standard library.
  67     wxDL_MODULE     ///< Loadable module/plugin.
  68 };
  69
  70 /**
  71     Dynamic library plugin category used with
  72     wxDynamicLibrary::CanonicalizePluginName().
  73 */
  74 enum wxPluginCategory
  75 {
  76     wxDL_PLUGIN_GUI,    ///< Plugin that uses GUI classes.
  77     wxDL_PLUGIN_BASE    ///< wxBase-only plugin.
  78 };
  79
  80 /**
  81     @class wxDynamicLibrary
  82
  83     wxDynamicLibrary is a class representing dynamically loadable library
  84     (Windows DLL, shared library under Unix etc.). Just create an object of
  85     this class to load a library and don't worry about unloading it -- it will
  86     be done in the objects destructor automatically.
  87
  88     The following flags can be used with wxDynamicLibrary() or Load():
  89
  90     @beginStyleTable
  91     @style{wxDL_LAZY}
  92            Equivalent of RTLD_LAZY under Unix, ignored elsewhere.
  93     @style{wxDL_NOW}
  94            Equivalent of RTLD_NOW under Unix, ignored elsewhere.
  95     @style{wxDL_GLOBAL}
  96            Equivalent of RTLD_GLOBAL under Unix, ignored elsewhere.
  97     @style{wxDL_VERBATIM}
  98            Don't try to append the appropriate extension to the library name
  99            (this is done by default).
 100     @style{wxDL_DEFAULT}
 101            Default flags, same as wxDL_NOW currently.
 102     @style{wxDL_QUIET}
 103            Don't log an error message if the library couldn't be loaded.
 104     @endStyleTable
 105
 106     @library{wxbase}
 107     @category{appmanagement}
 108 */
 109 class wxDynamicLibrary
 110 {
 111 public:
 112     /**
 113         Default constructor.
 114     */
 115     wxDynamicLibrary();
 116     /**
 117         Constructor. Calls Load() with the given @a name.
 118     */
 119     wxDynamicLibrary(const wxString& name, int flags = wxDL_DEFAULT);
 120
 121     /**
 122         Returns the platform-specific full name for the library called @a name.
 123         E.g. it adds a @c ".dll" extension under Windows and @c "lib" prefix
 124         and @c ".so", @c ".sl" or @c ".dylib" extension under Unix.
 125
 126         @see CanonicalizePluginName()
 127     */
 128     static wxString CanonicalizeName(const wxString& name,
 129                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 130
 131     /**
 132         This function does the same thing as CanonicalizeName() but for
 133         wxWidgets plugins. The only difference is that compiler and version
 134         information are added to the name to ensure that the plugin which is
 135         going to be loaded will be compatible with the main program.
 136     */
 137     static wxString CanonicalizePluginName(const wxString& name,
 138                                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 139
 140     /**
 141         Detaches this object from its library handle, i.e. the object will not
 142         unload the library any longer in its destructor but it is now the
 143         callers responsibility to do this using Unload().
 144     */
 145     wxDllType Detach();
 146
 147     /**
 148         Return a valid handle for the main program itself or @NULL if symbols
 149         from the main program can't be loaded on this platform.
 150     */
 151     static wxDllType GetProgramHandle();
 152
 153     /**
 154         Returns pointer to symbol @a name in the library or @NULL if the
 155         library contains no such symbol.
 156
 157         @see wxDYNLIB_FUNCTION()
 158     */
 159     void* GetSymbol(const wxString& name, bool* success = 0) const;
 160
 161     /**
 162         This function is available only under Windows as it is only useful when
 163         dynamically loading symbols from standard Windows DLLs. Such functions
 164         have either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide
 165         character build) suffix if they take string parameters. Using this
 166         function, you can use just the base name of the function and the
 167         correct suffix is appended automatically depending on the current
 168         build. Otherwise, this method is identical to GetSymbol().
 169     */
 170     void* GetSymbolAorW(const wxString& name) const;
 171
 172     /**
 173         Returns @true if the symbol with the given @a name is present in the
 174         dynamic library, @false otherwise. Unlike GetSymbol(), this function
 175         doesn't log an error message if the symbol is not found.
 176
 177         @since 2.5.4
 178     */
 179     bool HasSymbol(const wxString& name) const;
 180
 181     /**
 182         Returns @true if the library was successfully loaded, @false otherwise.
 183     */
 184     bool IsLoaded() const;
 185
 186     /**
 187         This static method returns a wxArray containing the details of all
 188         modules loaded into the address space of the current project. The array
 189         elements are objects of the type: wxDynamicLibraryDetails. The array
 190         will be empty if an error occurred.
 191
 192         This method is currently implemented only under Win32 and Linux and is
 193         useful mostly for diagnostics purposes.
 194     */
 195     static wxDynamicLibraryDetailsArray ListLoaded();
 196
 197     /**
 198         Loads DLL with the given @a name into memory. The @a flags argument can
 199         be a combination of the styles outlined in the class description.
 200
 201         Returns @true if the library was successfully loaded, @false otherwise.
 202     */
 203     bool Load(const wxString& name, int flags = wxDL_DEFAULT);
 204
 205     /**
 206         Unloads the library from memory. wxDynamicLibrary object automatically
 207         calls this method from its destructor if it had been successfully
 208         loaded.
 209     */
 210     void Unload();
 211     /**
 212         Unloads the library from memory. wxDynamicLibrary object automatically
 213         calls this method from its destructor if it had been successfully
 214         loaded.
 215
 216         This version of Unload() is only used if you need to keep the library
 217         in memory during a longer period of time than the scope of the
 218         wxDynamicLibrary object. In this case you may call Detach() and store
 219         the handle somewhere and call this static method later to unload it.
 220     */
 221     static void Unload(wxDllType handle);
 222 };
 223
 224
 225
 226 // ============================================================================
 227 // Global functions/macros
 228 // ============================================================================
 229
 230 /** @ingroup group_funcmacro_misc */
 231 //@{
 232
 233 /**
 234     When loading a function from a DLL you always have to cast the returned
 235     <tt>void *</tt> pointer to the correct type and, even more annoyingly, you
 236     have to repeat this type twice if you want to declare and define a function
 237     pointer all in one line.
 238
 239     This macro makes this slightly less painful by allowing you to specify the
 240     type only once, as the first parameter, and creating a variable of this
 241     type named after the function but with @c pfn prefix and initialized with
 242     the function @a name from the wxDynamicLibrary @a dynlib.
 243
 244     @param type
 245         The type of the function.
 246     @param name
 247         The name of the function to load, not a string (without quotes, it is
 248         quoted automatically by the macro).
 249     @param dynlib
 250         The library to load the function from.
 251
 252     @header{wx/dynlib.h}
 253 */
 254 #define wxDYNLIB_FUNCTION(type, name, dynlib)
 255
 256 //@}
 257