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         @onlyfor{wxmsw}
 171     */
 172     void* GetSymbolAorW(const wxString& name) const;
 173
 174     /**
 175         Returns @true if the symbol with the given @a name is present in the
 176         dynamic library, @false otherwise. Unlike GetSymbol(), this function
 177         doesn't log an error message if the symbol is not found.
 178
 179         @since 2.5.4
 180     */
 181     bool HasSymbol(const wxString& name) const;
 182
 183     /**
 184         Returns @true if the library was successfully loaded, @false otherwise.
 185     */
 186     bool IsLoaded() const;
 187
 188     /**
 189         This static method returns a wxArray containing the details of all
 190         modules loaded into the address space of the current project. The array
 191         elements are objects of the type: wxDynamicLibraryDetails. The array
 192         will be empty if an error occurred.
 193
 194         This method is currently implemented only under Win32 and Linux and is
 195         useful mostly for diagnostics purposes.
 196     */
 197     static wxDynamicLibraryDetailsArray ListLoaded();
 198
 199     /**
 200         Loads DLL with the given @a name into memory. The @a flags argument can
 201         be a combination of the styles outlined in the class description.
 202
 203         Returns @true if the library was successfully loaded, @false otherwise.
 204     */
 205     bool Load(const wxString& name, int flags = wxDL_DEFAULT);
 206
 207     /**
 208         Unloads the library from memory. wxDynamicLibrary object automatically
 209         calls this method from its destructor if it had been successfully
 210         loaded.
 211     */
 212     void Unload();
 213     /**
 214         Unloads the library from memory. wxDynamicLibrary object automatically
 215         calls this method from its destructor if it had been successfully
 216         loaded.
 217
 218         This version of Unload() is only used if you need to keep the library
 219         in memory during a longer period of time than the scope of the
 220         wxDynamicLibrary object. In this case you may call Detach() and store
 221         the handle somewhere and call this static method later to unload it.
 222     */
 223     static void Unload(wxDllType handle);
 224 };
 225
 226
 227
 228 // ============================================================================
 229 // Global functions/macros
 230 // ============================================================================
 231
 232 /** @ingroup group_funcmacro_misc */
 233 //@{
 234
 235 /**
 236     When loading a function from a DLL you always have to cast the returned
 237     <tt>void *</tt> pointer to the correct type and, even more annoyingly, you
 238     have to repeat this type twice if you want to declare and define a function
 239     pointer all in one line.
 240
 241     This macro makes this slightly less painful by allowing you to specify the
 242     type only once, as the first parameter, and creating a variable of this
 243     type named after the function but with @c pfn prefix and initialized with
 244     the function @a name from the wxDynamicLibrary @a dynlib.
 245
 246     @param type
 247         The type of the function.
 248     @param name
 249         The name of the function to load, not a string (without quotes, it is
 250         quoted automatically by the macro).
 251     @param dynlib
 252         The library to load the function from.
 253
 254     @header{wx/dynlib.h}
 255 */
 256 #define wxDYNLIB_FUNCTION(type, name, dynlib)
 257
 258 //@}
 259