← Back to branch summary

~ubuntu-dev/wxwidgets2.6/upstream-debian

« back to all changes in this revision

Viewing changes to docs/latex/wx/dllload.tex

  • Committer: Daniel T Chen
  • Date: 2006-06-26 10:15:11 UTC
  • Revision ID: crimsun@ubuntu.com-20060626101511-a4436cec4c6d9b35
Import Debian 2.6.3.2.1

Show diffs side-by-side

added added

removed removed

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