interface/wx/dynlib.h

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