docs/latex/wx/dynlib.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        dynlib.tex
   3 %% Purpose:     wxDynamicLibrary and wxDynamicLibraryDetails documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     14.01.02 (extracted from dllload.tex)
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxDynamicLibrary}}\label{wxdynamiclibrary}
  13
  14 wxDynamicLibrary is a class representing dynamically loadable library
  15 (Windows DLL, shared library under Unix etc.). Just create an object of
  16 this class to load a library and don't worry about unloading it -- it will be
  17 done in the objects destructor automatically.
  18
  19 \wxheading{Derived from}
  20
  21 No base class.
  22
  23 \wxheading{Include files}
  24
  25 <wx/dynlib.h>
  26
  27 (only available if \texttt{wxUSE\_DYNLIB\_CLASS} is set to $1$)
  28
  29 \latexignore{\rtfignore{\wxheading{Members}}}
  30
  31 \membersection{wxDynamicLibrary::wxDynamicLibrary}\label{wxdynamiclibrarywxdynamiclibrary}
  32
  33 \func{}{wxDynamicLibrary}{\void}
  34
  35 \func{}{wxDynamicLibrary}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}}
  36
  37 Constructor. Second form calls \helpref{Load}{wxdynamiclibraryload}.
  38
  39
  40 \membersection{wxDynamicLibrary::CanonicalizeName}\label{wxdynamiclibrarycanonicalizename}
  41
  42 \func{static wxString}{CanonicalizeName}{\param{const wxString\& }{name}, \param{wxDynamicLibraryCategory}{ cat = wxDL\_LIBRARY}}
  43
  44 Returns the platform-specific full name for the library called \arg{name}. E.g.
  45 it adds a {\tt ".dll"} extension under Windows and {\tt "lib"} prefix and
  46 {\tt ".so"}, {\tt ".sl"} or maybe {\tt ".dylib"} extension under Unix.
  47
  48 The possible values for \arg{cat} are:
  49
  50 \begin{twocollist}
  51     \twocolitem{wxDL\_LIBRARY}{normal library}
  52     \twocolitem{wxDL\_MODULE}{a loadable module or plugin}
  53 \end{twocollist}
  54
  55 \wxheading{See also}
  56
  57 \helpref{CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname}
  58
  59
  60
  61 \membersection{wxDynamicLibrary::CanonicalizePluginName}\label{wxdynamiclibrarycanonicalizepluginname}
  62
  63 \func{static wxString}{CanonicalizePluginName}{\param{const wxString\& }{name}, \param{wxPluginCategory}{ cat = wxDL\_PLUGIN\_GUI}}
  64
  65 This function does the same thing as
  66 \helpref{CanonicalizeName}{wxdynamiclibrarycanonicalizename} but for wxWidgets
  67 plugins. The only difference is that compiler and version information are added
  68 to the name to ensure that the plugin which is going to be loaded will be
  69 compatible with the main program.
  70
  71 The possible values for \arg{cat} are:
  72
  73 \begin{twocollist}
  74     \twocolitem{wxDL\_PLUGIN\_GUI}{plugin which uses GUI classes (default)}
  75     \twocolitem{wxDL\_PLUGIN\_BASE}{plugin which only uses wxBase}
  76 \end{twocollist}
  77
  78
  79 \membersection{wxDynamicLibrary::Detach}\label{wxdynamiclibrarydetach}
  80
  81 \func{wxDllType}{Detach}{\void}
  82
  83 Detaches this object from its library handle, i.e. the object will not unload
  84 the library any longer in its destructor but it is now the callers
  85 responsibility to do this using \helpref{Unload}{wxdynamiclibraryunload}.
  86
  87
  88 \membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol}
  89
  90 \constfunc{void *}{GetSymbol}{\param{const wxString\& }{name}}
  91
  92 Returns pointer to symbol {\it name} in the library or NULL if the library
  93 contains no such symbol.
  94
  95 \wxheading{See also}
  96
  97 \helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}
  98
  99
 100 \membersection{wxDynamicLibrary::GetSymbolAorW}\label{wxdynamiclibrarygetsymbolaorw}
 101
 102 \constfunc{void *}{GetSymbolAorW}{\param{const wxString\& }{name}}
 103
 104 This function is available only under Windows as it is only useful when
 105 dynamically loading symbols from standard Windows DLLs. Such functions have
 106 either \texttt{'A'} (in ANSI build) or \texttt{'W'} (in Unicode, or wide
 107 character build) suffix if they take string parameters. Using this function you
 108 can use just the base name of the function and the correct suffix is appende
 109 automatically depending on the current build. Otherwise, this method is
 110 identical to \helpref{GetSymbol}{wxdynamiclibrarygetsymbol}.
 111
 112
 113 \membersection{wxDynamicLibrary::GetProgramHandle}\label{wxdynamiclibrarygetprogramhandle}
 114
 115 \func{static wxDllType}{GetProgramHandle}{\void}
 116
 117 Return a valid handle for the main program itself or \texttt{NULL} if symbols
 118 from the main program can't be loaded on this platform.
 119
 120
 121 \membersection{wxDynamicLibrary::HasSymbol}\label{wxdynamiclibraryhassymbol}
 122
 123 \constfunc{bool}{HasSymbol}{\param{const wxString\& }{name}}
 124
 125 Returns \true if the symbol with the given \arg{name} is present in the dynamic
 126 library, \false otherwise. Unlike \helpref{GetSymbol}{wxdynamiclibrarygetsymbol},
 127 this function doesn't log an error message if the symbol is not found.
 128
 129 \newsince{2.5.4}
 130
 131
 132 \membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded}
 133
 134 \constfunc{bool}{IsLoaded}{\void}
 135
 136 Returns \true if the library was successfully loaded, \false otherwise.
 137
 138
 139 \membersection{wxDynamicLibrary::ListLoaded}\label{wxdynamiclibrarylistloaded}
 140
 141 \func{static wxDynamicLibraryDetailsArray}{ListLoaded}{\void}
 142
 143 This static method returns an \helpref{array}{wxarray} containing the details
 144 of all modules loaded into the address space of the current project, the array
 145 elements are object of \texttt{wxDynamicLibraryDetails} class. The array will
 146 be empty if an error occurred.
 147
 148 This method is currently implemented only under Win32 and Linux and is useful
 149 mostly for diagnostics purposes.
 150
 151
 152 \membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload}
 153
 154 \func{bool}{Load}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}}
 155
 156 Loads DLL with the given \arg{name} into memory. The \arg{flags} argument can
 157 be a combination of the following bits:
 158
 159 \begin{twocollist}
 160 \twocolitem{wxDL\_LAZY}{equivalent of RTLD\_LAZY under Unix, ignored elsewhere}
 161 \twocolitem{wxDL\_NOW}{equivalent of RTLD\_NOW under Unix, ignored elsewhere}
 162 \twocolitem{wxDL\_GLOBAL}{equivalent of RTLD\_GLOBAL under Unix, ignored elsewhere}
 163 \twocolitem{wxDL\_VERBATIM}{don't try to append the appropriate extension to
 164 the library name (this is done by default).}
 165 \twocolitem{wxDL\_DEFAULT}{default flags, same as wxDL\_NOW currently}
 166 \end{twocollist}
 167
 168 Returns \true if the library was successfully loaded, \false otherwise.
 169
 170
 171 \membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload}
 172
 173 \func{void}{Unload}{\void}
 174
 175 \func{static void}{Unload}{\param{wxDllType }{handle}}
 176
 177 Unloads the library from memory. wxDynamicLibrary object automatically calls
 178 this method from its destructor if it had been successfully loaded.
 179
 180 The second version is only used if you need to keep the library in memory
 181 during a longer period of time than the scope of the wxDynamicLibrary object.
 182 In this case you may call \helpref{Detach}{wxdynamiclibrarydetach} and store
 183 the handle somewhere and call this static method later to unload it.
 184
 185 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 186
 187 \section{\class{wxDynamicLibraryDetails}}\label{wxdynamiclibrarydetails}
 188
 189 This class is used for the objects returned by
 190 \helpref{wxDynamicLibrary::ListLoaded}{wxdynamiclibrarylistloaded} method and
 191 contains the information about a single module loaded into the address space of
 192 the current process. A module in this context may be either a dynamic library
 193 or the main program itself.
 194
 195 \wxheading{Derived from}
 196
 197 No base class.
 198
 199 \wxheading{Include files}
 200
 201 <wx/dynlib.h>
 202
 203 (only available if \texttt{wxUSE\_DYNLIB\_CLASS} is set to $1$)
 204
 205 \latexignore{\rtfignore{\wxheading{Members}}}
 206
 207 \membersection{wxDynamicLibraryDetails::GetName}\label{wxdynamiclibrarygetname}
 208
 209 \constfunc{wxString}{GetName}{\void}
 210
 211 Returns the base name of this module, e.g. \texttt{kernel32.dll} or
 212 \texttt{libc-2.3.2.so}.
 213
 214
 215 \membersection{wxDynamicLibraryDetails::GetPath}\label{wxdynamiclibrarygetpath}
 216
 217 \constfunc{wxString}{GetPath}{\void}
 218
 219 Returns the full path of this module if available, e.g.
 220 \texttt{c:$\backslash$windows$\backslash$system32$\backslash$kernel32.dll} or
 221 \texttt{/lib/libc-2.3.2.so}.
 222
 223
 224 \membersection{wxDynamicLibraryDetails::GetAddress}\label{wxdynamiclibrarygetaddress}
 225
 226 \constfunc{bool}{GetAddress}{\param{void **}{addr}, \param{size\_t }{*len}}
 227
 228 Retrieves the load address and the size of this module.
 229
 230 \wxheading{Parameters}
 231
 232 \docparam{addr}{the pointer to the location to return load address in, may be
 233 \texttt{NULL}}
 234
 235 \docparam{len}{pointer to the location to return the size of this module in
 236 memory in, may be \texttt{NULL}}
 237
 238 \wxheading{Return value}
 239
 240 \true if the load address and module size were retrieved, \false if this
 241 information is not available.
 242
 243
 244 \membersection{wxDynamicLibraryDetails::GetVersion}\label{wxdynamiclibrarygetversion}
 245
 246 \constfunc{wxString}{GetVersion}{\void}
 247
 248 Returns the version of this module, e.g. \texttt{5.2.3790.0} or
 249 \texttt{2.3.2}. The returned string is empty if the version information is not
 250 available.
 251