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 \textbf{Deprecation note: } This class is deprecated since version 2.4 and is
  15 not compiled in by default in version 2.6 and will be removed in 2.8. Please
  16 use \helpref{wxDynamicLibrary}{wxdynamiclibrary} instead.
  17
  18
  19 wxDllLoader is a class providing an interface similar to Unix's {\tt
  20 dlopen()}. It is used by the wxLibrary framework and manages the actual
  21 loading of shared libraries and the resolving of symbols in them. There are no
  22 instances of this class, it simply serves as a namespace for its static member
  23 functions.
  24
  25 Please note that class \helpref{wxDynamicLibrary}{wxdynamiclibrary} provides
  26 alternative, friendlier interface to wxDllLoader.
  27
  28 The terms {\it DLL} and {\it shared library/object} will both be used in the
  29 documentation to refer to the same thing: a {\tt .dll} file under Windows or
  30 {\tt .so} or {\tt .sl} one under Unix.
  31
  32 Example of using this class to dynamically load the {\tt strlen()} function:
  33
  34 \begin{verbatim}
  35 #if defined(__WXMSW__)
  36     static const wxChar *LIB_NAME = _T("kernel32");
  37     static const wxChar *FUNC_NAME = _T("lstrlenA");
  38 #elif defined(__UNIX__)
  39     static const wxChar *LIB_NAME = _T("/lib/libc-2.0.7.so");
  40     static const wxChar *FUNC_NAME = _T("strlen");
  41 #endif
  42
  43     wxDllType dllHandle = wxDllLoader::LoadLibrary(LIB_NAME);
  44     if ( !dllHandle )
  45     {
  46         ... error ...
  47     }
  48     else
  49     {
  50         typedef int (*strlenType)(char *);
  51         strlenType pfnStrlen = (strlenType)wxDllLoader::GetSymbol(dllHandle, FUNC_NAME);
  52         if ( !pfnStrlen )
  53         {
  54             ... error ...
  55         }
  56         else
  57         {
  58             if ( pfnStrlen("foo") != 3 )
  59             {
  60                 ... error ...
  61             }
  62             else
  63             {
  64                 ... ok! ...
  65             }
  66         }
  67
  68         wxDllLoader::UnloadLibrary(dllHandle);
  69     }
  70 \end{verbatim}
  71
  72 \wxheading{Derived from}
  73
  74 No base class
  75
  76 \wxheading{Include files}
  77
  78 <wx/dynlib.h>
  79
  80 \wxheading{Data structures}
  81
  82 This header defines a platform-dependent {\tt wxDllType} typedef which stores
  83 a handle to a loaded DLLs on the given platform.
  84
  85 \latexignore{\rtfignore{\wxheading{Members}}}
  86
  87 \membersection{wxDllLoader::GetDllExt}\label{wxdllloadergetdllext}
  88
  89 \func{static wxString}{GetDllExt}{\void}
  90
  91 Returns the string containing the usual extension for shared libraries for the
  92 given systems (including the leading dot if not empty).
  93
  94 For example, this function will return {\tt ".dll"} under Windows or (usually)
  95 {\tt ".so"} under Unix.
  96
  97 \membersection{wxDllLoader::GetProgramHandle}\label{wxdllloadergetprogramhandle}
  98
  99 \func{wxDllType}{GetProgramHandle}{\void}
 100
 101 This function returns a valid handle for the main program itself. Notice that
 102 the {\tt NULL} return value is valid for some systems (i.e. doesn't mean that
 103 the function failed).
 104
 105 {\bf NB:} This function is Unix specific. It will always fail under Windows
 106 or OS/2.
 107
 108 \membersection{wxDllLoader::GetSymbol}\label{wxdllloadergetsymbol}
 109
 110 \func{void *}{GetSymbol}{\param{wxDllType }{dllHandle}, \param{const wxString\& }{name}}
 111
 112 This function resolves a symbol in a loaded DLL, such as a variable or
 113 function name.
 114
 115 Returned value will be {\tt NULL} if the symbol was not found in the DLL or if
 116 an error occurred.
 117
 118 \wxheading{Parameters}
 119
 120 \docparam{dllHandle}{Valid handle previously returned by
 121 \helpref{LoadLibrary}{wxdllloaderloadlibrary}}
 122
 123 \docparam{name}{Name of the symbol.}
 124
 125 \membersection{wxDllLoader::LoadLibrary}\label{wxdllloaderloadlibrary}
 126
 127 \func{wxDllType}{LoadLibrary}{\param{const wxString \& }{libname}, \param{bool* }{success = NULL}}
 128
 129 This function loads a shared library into memory, with {\it libname} being the
 130 name of the library: it may be either the full name including path and
 131 (platform-dependent) extension, just the basename (no path and no extension)
 132 or a basename with extension. In the last two cases, the library will be
 133 searched in all standard locations.
 134
 135 Returns a handle to the loaded DLL. Use {\it success} parameter to test if it
 136 is valid. If the handle is valid, the library must be unloaded later with
 137 \helpref{UnloadLibrary}{wxdllloaderunloadlibrary}.
 138
 139 \wxheading{Parameters}
 140
 141 \docparam{libname}{Name of the shared object to load.}
 142
 143 \docparam{success}{May point to a bool variable which will be set to true or
 144 false; may also be {\tt NULL}.}
 145
 146 \membersection{wxDllLoader::UnloadLibrary}\label{wxdllloaderunloadlibrary}
 147
 148 \func{void}{UnloadLibrary}{\param{wxDllType }{dllhandle}}
 149
 150 This function unloads the shared library. The handle {\it dllhandle} must have
 151 been returned by \helpref{LoadLibrary}{wxdllloaderloadlibrary} previously.
 152