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