]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/dllload.tex
Updated docs for wxGrid::SelectBlock
[wxWidgets.git] / docs / latex / wx / dllload.tex
... / ...
CommitLineData
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
14wxDllLoader is a class providing an interface similar to Unix's {\tt
15dlopen()}. It is used by the wxLibrary framework and manages the actual
16loading of shared libraries and the resolving of symbols in them. There are no
17instances of this class, it simply serves as a namespace for its static member
18functions.
19
20The terms {\it DLL} and {\it shared library/object} will both be used in the
21documentation to refer to the same thing: a {\tt .dll} file under Windows or
22{\tt .so} or {\tt .sl} one under Unix.
23
24Example 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
66No base class
67
68\wxheading{Include files}
69
70<wx/dynlib.h>
71
72\wxheading{Data structures}
73
74This header defines a platfrom-dependent {\tt wxDllType} typedef which stores
75a 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
83Returns the string containing the usual extension for shared libraries for the
84given systems (including the leading dot if not empty).
85
86For 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
93This function returns a valid handle for the main program itself. Notice that
94the {\tt NULL} return value is valid for some systems (i.e. doesn't mean that
95the function failed).
96
97{\bf NB:} This function is Unix specific. It will always fail under Windows
98or OS/2.
99
100\membersection{wxDllLoader::GetSymbol}\label{wxdllloadergetsymbol}
101
102\func{void *}{GetSymbol}{\param{wxDllType }{dllHandle}, \param{const wxString\& }{name}}
103
104This function resolves a symbol in a loaded DLL, such as a variable or
105function name.
106
107Returned value will be {\tt NULL} if the symbol was not found in the DLL or if
108an 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
121This function loads a shared library into memory, with {\it libname} being the
122name 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)
124or a basename with extentsion. In the last two cases, the library will be
125searched in all standard locations.
126
127Returns a handle to the loaded DLL. Use {\it success} parameter to test if it
128is 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
136FALSE; may also be {\tt NULL}.}
137
138\membersection{wxDllLoader::UnloadLibrary}\label{wxdllloaderunloadlibrary}
139
140\func{void}{UnloadLibrary}{\param{wxDllType }{dllhandle}}
141
142This function unloads the shared library. The handle {\it dllhandle} must have
143been returned by \helpref{LoadLibrary}{wxdllloaderloadlibrary} previously.
144
145