interface/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     @wxheader{dynlib.h}
  12
  13     This class is used for the objects returned by the
  14     wxDynamicLibrary::ListLoaded() method and contains the information about a
  15     single module loaded into the address space of the current process. A
  16     module in this context may be either a dynamic library or the main program
  17     itself.
  18
  19     @library{wxbase}
  20     @category{appmanagement}
  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         @return @true if the load address and module size were retrieved,
  36                  @false 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 @c "/lib/libc-2.3.2.so".
  49     */
  50     wxString GetPath() const;
  51
  52     /**
  53         Returns the version of this module, e.g. @c "5.2.3790.0" or @c "2.3.2".
  54         The returned string is empty if the version information is not
  55         available.
  56     */
  57     wxString GetVersion() const;
  58 };
  59
  60
  61
  62 /**
  63     Dynamic library category used with wxDynamicLibrary::CanonicalizeName().
  64 */
  65 enum wxDynamicLibraryCategory
  66 {
  67     wxDL_LIBRARY,   ///< Standard library.
  68     wxDL_MODULE     ///< Loadable module/plugin.
  69 };
  70
  71 /**
  72     Dynamic library plugin category used with
  73     wxDynamicLibrary::CanonicalizePluginName().
  74 */
  75 enum wxPluginCategory
  76 {
  77     wxDL_PLUGIN_GUI,    ///< Plugin that uses GUI classes.
  78     wxDL_PLUGIN_BASE    ///< wxBase-only plugin.
  79 };
  80
  81 /**
  82     @class wxDynamicLibrary
  83     @wxheader{dynlib.h}
  84
  85     wxDynamicLibrary is a class representing dynamically loadable library
  86     (Windows DLL, shared library under Unix etc.). Just create an object of
  87     this class to load a library and don't worry about unloading it -- it will
  88     be done in the objects destructor automatically.
  89
  90     The following flags can be used with wxDynamicLibrary() or Load():
  91
  92     @beginStyleTable
  93     @style{wxDL_LAZY}
  94            Equivalent of RTLD_LAZY under Unix, ignored elsewhere.
  95     @style{wxDL_NOW}
  96            Equivalent of RTLD_NOW under Unix, ignored elsewhere.
  97     @style{wxDL_GLOBAL}
  98            Equivalent of RTLD_GLOBAL under Unix, ignored elsewhere.
  99     @style{wxDL_VERBATIM}
 100            Don't try to append the appropriate extension to the library name
 101            (this is done by default).
 102     @style{wxDL_DEFAULT}
 103            Default flags, same as wxDL_NOW currently.
 104     @style{wxDL_QUIET}
 105            Don't log an error message if the library couldn't be loaded.
 106     @endStyleTable
 107
 108     @library{wxbase}
 109     @category{appmanagement}
 110 */
 111 class wxDynamicLibrary
 112 {
 113 public:
 114     /**
 115         Default constructor.
 116     */
 117     wxDynamicLibrary();
 118     /**
 119         Constructor. Calls Load() with the given @a name.
 120     */
 121     wxDynamicLibrary(const wxString& name, int flags = wxDL_DEFAULT);
 122
 123     /**
 124         Returns the platform-specific full name for the library called @a name.
 125         E.g. it adds a @c ".dll" extension under Windows and @c "lib" prefix
 126         and @c ".so", @c ".sl" or @c ".dylib" extension under Unix.
 127
 128         @see CanonicalizePluginName()
 129     */
 130     static wxString CanonicalizeName(const wxString& name,
 131                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 132
 133     /**
 134         This function does the same thing as CanonicalizeName() but for
 135         wxWidgets plugins. The only difference is that compiler and version
 136         information are added to the name to ensure that the plugin which is
 137         going to be loaded will be compatible with the main program.
 138     */
 139     static wxString CanonicalizePluginName(const wxString& name,
 140                                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 141
 142     /**
 143         Detaches this object from its library handle, i.e. the object will not
 144         unload the library any longer in its destructor but it is now the
 145         callers responsibility to do this using Unload().
 146     */
 147     wxDllType Detach();
 148
 149     /**
 150         Return a valid handle for the main program itself or @NULL if symbols
 151         from the main program can't be loaded on this platform.
 152     */
 153     static wxDllType GetProgramHandle();
 154
 155     /**
 156         Returns pointer to symbol @a name in the library or @NULL if the
 157         library contains no such symbol.
 158
 159         @see wxDYNLIB_FUNCTION()
 160     */
 161     void* GetSymbol(const wxString& name) const;
 162
 163     /**
 164         This function is available only under Windows as it is only useful when
 165         dynamically loading symbols from standard Windows DLLs. Such functions
 166         have either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide
 167         character build) suffix if they take string parameters. Using this
 168         function, you can use just the base name of the function and the
 169         correct suffix is appended automatically depending on the current
 170         build. Otherwise, this method is identical to GetSymbol().
 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