docs/latex/wx/dllload.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        dllload.tex
   3 %% Purpose:     wxDllLoader documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     02.04.00
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxDllLoader}}\label{wxdllloader}
  13
  14 wxDllLoader is a class providing an interface similar to Unix's {\tt
  15 dlopen()}. It is used by the wxLibrary framework and manages the actual
  16 loading of shared libraries and the resolving of symbols in them. There are no
  17 instances of this class, it simply serves as a namespace for its static member
  18 functions.
  19
  20 Please note that class \helpref{wxDynamicLibrary}{wxdynamiclibrary} provides
  21 alternative, friendlier interface to wxDllLoader.
  22
  23 The terms {\it DLL} and {\it shared library/object} will both be used in the
  24 documentation to refer to the same thing: a {\tt .dll} file under Windows or
  25 {\tt .so} or {\tt .sl} one under Unix.
  26
  27 Example of using this class to dynamically load {\tt strlen()} function:
  28
  29 \begin{verbatim}
  30 #if defined(__WXMSW__)
  31     static const wxChar *LIB_NAME = _T("kernel32");
  32     static const wxChar *FUNC_NAME = _T("lstrlenA");
  33 #elif defined(__UNIX__)
  34     static const wxChar *LIB_NAME = _T("/lib/libc-2.0.7.so");
  35     static const wxChar *FUNC_NAME = _T("strlen");
  36 #endif
  37
  38     wxDllType dllHandle = wxDllLoader::LoadLibrary(LIB_NAME);
  39     if ( !dllHandle )
  40     {
  41         ... error ...
  42     }
  43     else
  44     {
  45         typedef int (*strlenType)(char *);
  46         strlenType pfnStrlen = (strlenType)wxDllLoader::GetSymbol(dllHandle, FUNC_NAME);
  47         if ( !pfnStrlen )
  48         {
  49             ... error ...
  50         }
  51         else
  52         {
  53             if ( pfnStrlen("foo") != 3 )
  54             {
  55                 ... error ...
  56             }
  57             else
  58             {
  59                 ... ok! ...
  60             }
  61         }
  62
  63         wxDllLoader::UnloadLibrary(dllHandle);
  64     }
  65 \end{verbatim}
  66
  67 \wxheading{Derived from}
  68
  69 No base class
  70
  71 \wxheading{Include files}
  72
  73 <wx/dynlib.h>
  74
  75 \wxheading{Data structures}
  76
  77 This header defines a platfrom-dependent {\tt wxDllType} typedef which stores
  78 a handle to a loaded DLLs on the given platform.
  79
  80 \latexignore{\rtfignore{\wxheading{Members}}}
  81
  82 \membersection{wxDllLoader::GetDllExt}\label{wxdllloadergetdllext}
  83
  84 \func{static wxString}{GetDllExt}{\void}
  85
  86 Returns the string containing the usual extension for shared libraries for the
  87 given systems (including the leading dot if not empty).
  88
  89 For example, this function will return {\tt ".dll"} under Windows or (usually)
  90 {\tt ".so"} under Unix.
  91
  92 \membersection{wxDllLoader::GetProgramHandle}\label{wxdllloadergetprogramhandle}
  93
  94 \func{wxDllType}{GetProgramHandle}{\void}
  95
  96 This function returns a valid handle for the main program itself. Notice that
  97 the {\tt NULL} return value is valid for some systems (i.e. doesn't mean that
  98 the function failed).
  99
 100 {\bf NB:} This function is Unix specific. It will always fail under Windows
 101 or OS/2.
 102
 103 \membersection{wxDllLoader::GetSymbol}\label{wxdllloadergetsymbol}
 104
 105 \func{void *}{GetSymbol}{\param{wxDllType }{dllHandle}, \param{const wxString\& }{name}}
 106
 107 This function resolves a symbol in a loaded DLL, such as a variable or
 108 function name.
 109
 110 Returned value will be {\tt NULL} if the symbol was not found in the DLL or if
 111 an error occured.
 112
 113 \wxheading{Parameters}
 114
 115 \docparam{dllHandle}{Valid handle previously returned by
 116 \helpref{LoadLibrary}{wxdllloaderloadlibrary}}
 117
 118 \docparam{name}{Name of the symbol.}
 119
 120 \membersection{wxDllLoader::LoadLibrary}\label{wxdllloaderloadlibrary}
 121
 122 \func{wxDllType}{LoadLibrary}{\param{const wxString \& }{libname}, \param{bool* }{success = NULL}}
 123
 124 This function loads a shared library into memory, with {\it libname} being the
 125 name of the library: it may be either the full name including path and
 126 (platform-dependent) extenesion, just the basename (no path and no extension)
 127 or a basename with extentsion. In the last two cases, the library will be
 128 searched in all standard locations.
 129
 130 Returns a handle to the loaded DLL. Use {\it success} parameter to test if it
 131 is valid. If the handle is valid, the library must be unloaded later with
 132 \helpref{UnloadLibrary}{wxdllloaderunloadlibrary}.
 133
 134 \wxheading{Parameters}
 135
 136 \docparam{libname}{Name of the shared object to load.}
 137
 138 \docparam{success}{May point to a bool variable which will be set to TRUE or
 139 FALSE; may also be {\tt NULL}.}
 140
 141 \membersection{wxDllLoader::UnloadLibrary}\label{wxdllloaderunloadlibrary}
 142
 143 \func{void}{UnloadLibrary}{\param{wxDllType }{dllhandle}}
 144
 145 This function unloads the shared library. The handle {\it dllhandle} must have
 146 been returned by \helpref{LoadLibrary}{wxdllloaderloadlibrary} previously.
 147
 148 \section{\class{wxDynamicLibrary}}\label{wxdynamiclibrary}
 149
 150 wxDynamicLibrary is a class representing dynamically loadable library
 151 (Windows DLL, shared library under Unix etc.). It is implemented as a wrapper
 152 to \helpref{wxDllLoader}{wxdllloader}.
 153
 154 \wxheading{See also}
 155
 156 \helpref{wxDllLoader}{wxdllloader}
 157
 158 \membersection{wxDynamicLibrary::wxDynamicLibrary}\label{wxdynamiclibrarywxdynamiclibrary}
 159
 160 \func{}{wxDynamicLibrary}{\void}
 161
 162 \func{}{wxDynamicLibrary}{\param{const wxString\& }{name}}
 163
 164 Constructor. Second form calls \helpref{Load}{wxdynamiclibraryload}.
 165
 166 \membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded}
 167
 168 \constfunc{bool}{IsLoaded}{\void}
 169
 170 Returns TRUE if the library was successfully loaded, FALSE otherwise.
 171
 172 \membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload}
 173
 174 \func{bool}{Load}{\param{const wxString\& }{name}}
 175
 176 Loads DLL into memory.
 177
 178 Returns TRUE if the library was successfully loaded, FALSE otherwise.
 179
 180 \membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload}
 181
 182 \func{void}{Unload}{\void}
 183
 184 Unloads the library from memory.
 185
 186 \membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol}
 187
 188 \constfunc{void*}{GetSymbol}{\param{const wxString\& }{name}}
 189
 190 Returns pointer to symbol {\it name} in the library or NULL if the library
 191 contains no such symbol.