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