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: dllload.tex 33428 2005-04-08 14:34:30Z MW $ 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 15not compiled in by default in version 2.6 and will be removed in 2.8. Please 16use \helpref{wxDynamicLibrary}{wxdynamiclibrary} instead. 17 18 19wxDllLoader is a class providing an interface similar to Unix's {\tt 20dlopen()}. It is used by the wxLibrary framework and manages the actual 21loading of shared libraries and the resolving of symbols in them. There are no 22instances of this class, it simply serves as a namespace for its static member 23functions. 24 25Please note that class \helpref{wxDynamicLibrary}{wxdynamiclibrary} provides 26alternative, friendlier interface to wxDllLoader. 27 28The terms {\it DLL} and {\it shared library/object} will both be used in the 29documentation to refer to the same thing: a {\tt .dll} file under Windows or 30{\tt .so} or {\tt .sl} one under Unix. 31 32Example 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 74No base class 75 76\wxheading{Include files} 77 78<wx/dynlib.h> 79 80\wxheading{Data structures} 81 82This header defines a platform-dependent {\tt wxDllType} typedef which stores 83a 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 91Returns the string containing the usual extension for shared libraries for the 92given systems (including the leading dot if not empty). 93 94For 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 101This function returns a valid handle for the main program itself. Notice that 102the {\tt NULL} return value is valid for some systems (i.e. doesn't mean that 103the function failed). 104 105{\bf NB:} This function is Unix specific. It will always fail under Windows 106or OS/2. 107 108\membersection{wxDllLoader::GetSymbol}\label{wxdllloadergetsymbol} 109 110\func{void *}{GetSymbol}{\param{wxDllType }{dllHandle}, \param{const wxString\& }{name}} 111 112This function resolves a symbol in a loaded DLL, such as a variable or 113function name. 114 115Returned value will be {\tt NULL} if the symbol was not found in the DLL or if 116an 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 129This function loads a shared library into memory, with {\it libname} being the 130name 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) 132or a basename with extension. In the last two cases, the library will be 133searched in all standard locations. 134 135Returns a handle to the loaded DLL. Use {\it success} parameter to test if it 136is 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 144false; may also be {\tt NULL}.} 145 146\membersection{wxDllLoader::UnloadLibrary}\label{wxdllloaderunloadlibrary} 147 148\func{void}{UnloadLibrary}{\param{wxDllType }{dllhandle}} 149 150This function unloads the shared library. The handle {\it dllhandle} must have 151been returned by \helpref{LoadLibrary}{wxdllloaderloadlibrary} previously. 152 153