]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/dynlib.tex
cleanup
[wxWidgets.git] / docs / latex / wx / dynlib.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: dynlib.tex
3 %% Purpose: wxDynamicLibrary and wxDynamicLibraryDetails documentation
4 %% Author: Vadim Zeitlin
5 %% Modified by:
6 %% Created: 14.01.02 (extracted from dllload.tex)
7 %% RCS-ID: $Id$
8 %% Copyright: (c) Vadim Zeitlin
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxDynamicLibrary}}\label{wxdynamiclibrary}
13
14 wxDynamicLibrary is a class representing dynamically loadable library
15 (Windows DLL, shared library under Unix etc.). Just create an object of
16 this class to load a library and don't worry about unloading it -- it will be
17 done in the objects destructor automatically.
18
19 \wxheading{Derived from}
20
21 No base class.
22
23 \wxheading{Include files}
24
25 <wx/dynlib.h>
26
27 \wxheading{Library}
28
29 \helpref{wxBase}{librarieslist}
30
31 (only available if \texttt{wxUSE\_DYNLIB\_CLASS} is set to $1$)
32
33 \latexignore{\rtfignore{\wxheading{Members}}}
34
35 \membersection{wxDynamicLibrary::wxDynamicLibrary}\label{wxdynamiclibrarywxdynamiclibrary}
36
37 \func{}{wxDynamicLibrary}{\void}
38
39 \func{}{wxDynamicLibrary}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}}
40
41 Constructor. Second form calls \helpref{Load}{wxdynamiclibraryload}.
42
43
44 \membersection{wxDynamicLibrary::CanonicalizeName}\label{wxdynamiclibrarycanonicalizename}
45
46 \func{static wxString}{CanonicalizeName}{\param{const wxString\& }{name}, \param{wxDynamicLibraryCategory}{ cat = wxDL\_LIBRARY}}
47
48 Returns the platform-specific full name for the library called \arg{name}. E.g.
49 it adds a {\tt ".dll"} extension under Windows and {\tt "lib"} prefix and
50 {\tt ".so"}, {\tt ".sl"} or maybe {\tt ".dylib"} extension under Unix.
51
52 The possible values for \arg{cat} are:
53
54 \begin{twocollist}
55 \twocolitem{wxDL\_LIBRARY}{normal library}
56 \twocolitem{wxDL\_MODULE}{a loadable module or plugin}
57 \end{twocollist}
58
59 \wxheading{See also}
60
61 \helpref{CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname}
62
63
64
65 \membersection{wxDynamicLibrary::CanonicalizePluginName}\label{wxdynamiclibrarycanonicalizepluginname}
66
67 \func{static wxString}{CanonicalizePluginName}{\param{const wxString\& }{name}, \param{wxPluginCategory}{ cat = wxDL\_PLUGIN\_GUI}}
68
69 This function does the same thing as
70 \helpref{CanonicalizeName}{wxdynamiclibrarycanonicalizename} but for wxWidgets
71 plugins. The only difference is that compiler and version information are added
72 to the name to ensure that the plugin which is going to be loaded will be
73 compatible with the main program.
74
75 The possible values for \arg{cat} are:
76
77 \begin{twocollist}
78 \twocolitem{wxDL\_PLUGIN\_GUI}{plugin which uses GUI classes (default)}
79 \twocolitem{wxDL\_PLUGIN\_BASE}{plugin which only uses wxBase}
80 \end{twocollist}
81
82
83 \membersection{wxDynamicLibrary::Detach}\label{wxdynamiclibrarydetach}
84
85 \func{wxDllType}{Detach}{\void}
86
87 Detaches this object from its library handle, i.e. the object will not unload
88 the library any longer in its destructor but it is now the callers
89 responsibility to do this using \helpref{Unload}{wxdynamiclibraryunload}.
90
91
92 \membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol}
93
94 \constfunc{void *}{GetSymbol}{\param{const wxString\& }{name}}
95
96 Returns pointer to symbol {\it name} in the library or NULL if the library
97 contains no such symbol.
98
99 \wxheading{See also}
100
101 \helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction}
102
103
104 \membersection{wxDynamicLibrary::GetSymbolAorW}\label{wxdynamiclibrarygetsymbolaorw}
105
106 \constfunc{void *}{GetSymbolAorW}{\param{const wxString\& }{name}}
107
108 This function is available only under Windows as it is only useful when
109 dynamically loading symbols from standard Windows DLLs. Such functions have
110 either \texttt{'A'} (in ANSI build) or \texttt{'W'} (in Unicode, or wide
111 character build) suffix if they take string parameters. Using this function you
112 can use just the base name of the function and the correct suffix is appende
113 automatically depending on the current build. Otherwise, this method is
114 identical to \helpref{GetSymbol}{wxdynamiclibrarygetsymbol}.
115
116
117 \membersection{wxDynamicLibrary::GetProgramHandle}\label{wxdynamiclibrarygetprogramhandle}
118
119 \func{static wxDllType}{GetProgramHandle}{\void}
120
121 Return a valid handle for the main program itself or \texttt{NULL} if symbols
122 from the main program can't be loaded on this platform.
123
124
125 \membersection{wxDynamicLibrary::HasSymbol}\label{wxdynamiclibraryhassymbol}
126
127 \constfunc{bool}{HasSymbol}{\param{const wxString\& }{name}}
128
129 Returns \true if the symbol with the given \arg{name} is present in the dynamic
130 library, \false otherwise. Unlike \helpref{GetSymbol}{wxdynamiclibrarygetsymbol},
131 this function doesn't log an error message if the symbol is not found.
132
133 \newsince{2.5.4}
134
135
136 \membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded}
137
138 \constfunc{bool}{IsLoaded}{\void}
139
140 Returns \true if the library was successfully loaded, \false otherwise.
141
142
143 \membersection{wxDynamicLibrary::ListLoaded}\label{wxdynamiclibrarylistloaded}
144
145 \func{static wxDynamicLibraryDetailsArray}{ListLoaded}{\void}
146
147 This static method returns an \helpref{array}{wxarray} containing the details
148 of all modules loaded into the address space of the current project, the array
149 elements are object of \texttt{wxDynamicLibraryDetails} class. The array will
150 be empty if an error occurred.
151
152 This method is currently implemented only under Win32 and Linux and is useful
153 mostly for diagnostics purposes.
154
155
156 \membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload}
157
158 \func{bool}{Load}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}}
159
160 Loads DLL with the given \arg{name} into memory. The \arg{flags} argument can
161 be a combination of the following bits:
162
163 \begin{twocollist}
164 \twocolitem{wxDL\_LAZY}{equivalent of RTLD\_LAZY under Unix, ignored elsewhere}
165 \twocolitem{wxDL\_NOW}{equivalent of RTLD\_NOW under Unix, ignored elsewhere}
166 \twocolitem{wxDL\_GLOBAL}{equivalent of RTLD\_GLOBAL under Unix, ignored elsewhere}
167 \twocolitem{wxDL\_VERBATIM}{don't try to append the appropriate extension to
168 the library name (this is done by default).}
169 \twocolitem{wxDL\_DEFAULT}{default flags, same as wxDL\_NOW currently}
170 \end{twocollist}
171
172 Returns \true if the library was successfully loaded, \false otherwise.
173
174
175 \membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload}
176
177 \func{void}{Unload}{\void}
178
179 \func{static void}{Unload}{\param{wxDllType }{handle}}
180
181 Unloads the library from memory. wxDynamicLibrary object automatically calls
182 this method from its destructor if it had been successfully loaded.
183
184 The second version is only used if you need to keep the library in memory
185 during a longer period of time than the scope of the wxDynamicLibrary object.
186 In this case you may call \helpref{Detach}{wxdynamiclibrarydetach} and store
187 the handle somewhere and call this static method later to unload it.
188
189 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
190
191 \section{\class{wxDynamicLibraryDetails}}\label{wxdynamiclibrarydetails}
192
193 This class is used for the objects returned by
194 \helpref{wxDynamicLibrary::ListLoaded}{wxdynamiclibrarylistloaded} method and
195 contains the information about a single module loaded into the address space of
196 the current process. A module in this context may be either a dynamic library
197 or the main program itself.
198
199 \wxheading{Derived from}
200
201 No base class.
202
203 \wxheading{Include files}
204
205 <wx/dynlib.h>
206
207 \wxheading{Library}
208
209 \helpref{wxBase}{librarieslist}
210
211 (only available if \texttt{wxUSE\_DYNLIB\_CLASS} is set to $1$)
212
213 \latexignore{\rtfignore{\wxheading{Members}}}
214
215 \membersection{wxDynamicLibraryDetails::GetName}\label{wxdynamiclibrarygetname}
216
217 \constfunc{wxString}{GetName}{\void}
218
219 Returns the base name of this module, e.g. \texttt{kernel32.dll} or
220 \texttt{libc-2.3.2.so}.
221
222
223 \membersection{wxDynamicLibraryDetails::GetPath}\label{wxdynamiclibrarygetpath}
224
225 \constfunc{wxString}{GetPath}{\void}
226
227 Returns the full path of this module if available, e.g.
228 \texttt{c:$\backslash$windows$\backslash$system32$\backslash$kernel32.dll} or
229 \texttt{/lib/libc-2.3.2.so}.
230
231
232 \membersection{wxDynamicLibraryDetails::GetAddress}\label{wxdynamiclibrarygetaddress}
233
234 \constfunc{bool}{GetAddress}{\param{void **}{addr}, \param{size\_t }{*len}}
235
236 Retrieves the load address and the size of this module.
237
238 \wxheading{Parameters}
239
240 \docparam{addr}{the pointer to the location to return load address in, may be
241 \texttt{NULL}}
242
243 \docparam{len}{pointer to the location to return the size of this module in
244 memory in, may be \texttt{NULL}}
245
246 \wxheading{Return value}
247
248 \true if the load address and module size were retrieved, \false if this
249 information is not available.
250
251
252 \membersection{wxDynamicLibraryDetails::GetVersion}\label{wxdynamiclibrarygetversion}
253
254 \constfunc{wxString}{GetVersion}{\void}
255
256 Returns the version of this module, e.g. \texttt{5.2.3790.0} or
257 \texttt{2.3.2}. The returned string is empty if the version information is not
258 available.
259