← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/dynlib.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
interface/wx/dynlib.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        dynlib.h
 
3
// Purpose:     interface of wxDynamicLibrary and wxDynamicLibraryDetails
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: dynlib.h 64940 2010-07-13 13:29:13Z VZ $
 
6
// Licence:     wxWindows licence
 
7
/////////////////////////////////////////////////////////////////////////////
 
8
 
 
9
/**
 
10
    @class wxDynamicLibraryDetails
 
11
 
 
12
    This class is used for the objects returned by the
 
13
    wxDynamicLibrary::ListLoaded() method and contains the information about a
 
14
    single module loaded into the address space of the current process. A
 
15
    module in this context may be either a dynamic library or the main program
 
16
    itself.
 
17
 
 
18
    @library{wxbase}
 
19
    @category{appmanagement}
 
20
*/
 
21
class wxDynamicLibraryDetails
 
22
{
 
23
public:
 
24
    /**
 
25
        Retrieves the load address and the size of this module.
 
26
 
 
27
        @param addr
 
28
            The pointer to the location to return load address in, may be
 
29
            @NULL.
 
30
        @param len
 
31
            Pointer to the location to return the size of this module in
 
32
            memory in, may be @NULL.
 
33
 
 
34
        @return @true if the load address and module size were retrieved,
 
35
                 @false if this information is not available.
 
36
    */
 
37
    bool GetAddress(void* addr, size_t* len) const;
 
38
 
 
39
    /**
 
40
        Returns the base name of this module, e.g. @c "kernel32.dll" or
 
41
        @c "libc-2.3.2.so".
 
42
    */
 
43
    wxString GetName() const;
 
44
 
 
45
    /**
 
46
        Returns the full path of this module if available, e.g.
 
47
        @c "c:\windows\system32\kernel32.dll" or @c "/lib/libc-2.3.2.so".
 
48
    */
 
49
    wxString GetPath() const;
 
50
 
 
51
    /**
 
52
        Returns the version of this module, e.g. @c "5.2.3790.0" or @c "2.3.2".
 
53
        The returned string is empty if the version information is not
 
54
        available.
 
55
    */
 
56
    wxString GetVersion() const;
 
57
};
 
58
 
 
59
 
 
60
 
 
61
/**
 
62
    Dynamic library category used with wxDynamicLibrary::CanonicalizeName().
 
63
*/
 
64
enum wxDynamicLibraryCategory
 
65
{
 
66
    wxDL_LIBRARY,   ///< Standard library.
 
67
    wxDL_MODULE     ///< Loadable module/plugin.
 
68
};
 
69
 
 
70
/**
 
71
    Dynamic library plugin category used with
 
72
    wxDynamicLibrary::CanonicalizePluginName().
 
73
*/
 
74
enum wxPluginCategory
 
75
{
 
76
    wxDL_PLUGIN_GUI,    ///< Plugin that uses GUI classes.
 
77
    wxDL_PLUGIN_BASE    ///< wxBase-only plugin.
 
78
};
 
79
 
 
80
/**
 
81
    @class wxDynamicLibrary
 
82
 
 
83
    wxDynamicLibrary is a class representing dynamically loadable library
 
84
    (Windows DLL, shared library under Unix etc). Just create an object of
 
85
    this class to load a library and don't worry about unloading it -- it will
 
86
    be done in the objects destructor automatically.
 
87
 
 
88
    The following flags can be used with wxDynamicLibrary() or Load():
 
89
 
 
90
    @beginStyleTable
 
91
    @style{wxDL_LAZY}
 
92
           Equivalent of RTLD_LAZY under Unix, ignored elsewhere.
 
93
    @style{wxDL_NOW}
 
94
           Equivalent of RTLD_NOW under Unix, ignored elsewhere.
 
95
    @style{wxDL_GLOBAL}
 
96
           Equivalent of RTLD_GLOBAL under Unix, ignored elsewhere.
 
97
    @style{wxDL_VERBATIM}
 
98
           Don't try to append the appropriate extension to the library name
 
99
           (this is done by default).
 
100
    @style{wxDL_DEFAULT}
 
101
           Default flags, same as wxDL_NOW currently.
 
102
    @style{wxDL_QUIET}
 
103
           Don't log an error message if the library couldn't be loaded.
 
104
    @endStyleTable
 
105
 
 
106
    @library{wxbase}
 
107
    @category{appmanagement}
 
108
*/
 
109
class wxDynamicLibrary
 
110
{
 
111
public:
 
112
    /**
 
113
        Default constructor.
 
114
    */
 
115
    wxDynamicLibrary();
 
116
    /**
 
117
        Constructor. Calls Load() with the given @a name.
 
118
    */
 
119
    wxDynamicLibrary(const wxString& name, int flags = wxDL_DEFAULT);
 
120
 
 
121
    /**
 
122
        Returns the platform-specific full name for the library called @a name.
 
123
        E.g. it adds a @c ".dll" extension under Windows and @c "lib" prefix
 
124
        and @c ".so", @c ".sl" or @c ".dylib" extension under Unix.
 
125
 
 
126
        @see CanonicalizePluginName()
 
127
    */
 
128
    static wxString CanonicalizeName(const wxString& name,
 
129
                                     wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 
130
 
 
131
    /**
 
132
        This function does the same thing as CanonicalizeName() but for
 
133
        wxWidgets plugins. The only difference is that compiler and version
 
134
        information are added to the name to ensure that the plugin which is
 
135
        going to be loaded will be compatible with the main program.
 
136
    */
 
137
    static wxString CanonicalizePluginName(const wxString& name,
 
138
                                           wxPluginCategory cat = wxDL_PLUGIN_GUI);
 
139
 
 
140
    /**
 
141
        Detaches this object from its library handle, i.e. the object will not
 
142
        unload the library any longer in its destructor but it is now the
 
143
        callers responsibility to do this using Unload().
 
144
    */
 
145
    wxDllType Detach();
 
146
 
 
147
    /**
 
148
        Return a valid handle for the main program itself or @NULL if symbols
 
149
        from the main program can't be loaded on this platform.
 
150
    */
 
151
    static wxDllType GetProgramHandle();
 
152
 
 
153
    /**
 
154
        Returns pointer to symbol @a name in the library or @NULL if the
 
155
        library contains no such symbol.
 
156
 
 
157
        @see wxDYNLIB_FUNCTION()
 
158
    */
 
159
    void* GetSymbol(const wxString& name, bool* success = 0) const;
 
160
 
 
161
    /**
 
162
        This function is available only under Windows as it is only useful when
 
163
        dynamically loading symbols from standard Windows DLLs. Such functions
 
164
        have either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide
 
165
        character build) suffix if they take string parameters. Using this
 
166
        function, you can use just the base name of the function and the
 
167
        correct suffix is appended automatically depending on the current
 
168
        build. Otherwise, this method is identical to GetSymbol().
 
169
 
 
170
        @onlyfor{wxmsw}
 
171
    */
 
172
    void* GetSymbolAorW(const wxString& name) const;
 
173
 
 
174
    /**
 
175
        Returns @true if the symbol with the given @a name is present in the
 
176
        dynamic library, @false otherwise. Unlike GetSymbol(), this function
 
177
        doesn't log an error message if the symbol is not found.
 
178
 
 
179
        @since 2.5.4
 
180
    */
 
181
    bool HasSymbol(const wxString& name) const;
 
182
 
 
183
    /**
 
184
        Returns @true if the library was successfully loaded, @false otherwise.
 
185
    */
 
186
    bool IsLoaded() const;
 
187
 
 
188
    /**
 
189
        This static method returns a wxArray containing the details of all
 
190
        modules loaded into the address space of the current project. The array
 
191
        elements are objects of the type: wxDynamicLibraryDetails. The array
 
192
        will be empty if an error occurred.
 
193
 
 
194
        This method is currently implemented only under Win32 and Linux and is
 
195
        useful mostly for diagnostics purposes.
 
196
    */
 
197
    static wxDynamicLibraryDetailsArray ListLoaded();
 
198
 
 
199
    /**
 
200
        Loads DLL with the given @a name into memory. The @a flags argument can
 
201
        be a combination of the styles outlined in the class description.
 
202
 
 
203
        Returns @true if the library was successfully loaded, @false otherwise.
 
204
    */
 
205
    bool Load(const wxString& name, int flags = wxDL_DEFAULT);
 
206
 
 
207
    /**
 
208
        Unloads the library from memory. wxDynamicLibrary object automatically
 
209
        calls this method from its destructor if it had been successfully
 
210
        loaded.
 
211
    */
 
212
    void Unload();
 
213
    /**
 
214
        Unloads the library from memory. wxDynamicLibrary object automatically
 
215
        calls this method from its destructor if it had been successfully
 
216
        loaded.
 
217
 
 
218
        This version of Unload() is only used if you need to keep the library
 
219
        in memory during a longer period of time than the scope of the
 
220
        wxDynamicLibrary object. In this case you may call Detach() and store
 
221
        the handle somewhere and call this static method later to unload it.
 
222
    */
 
223
    static void Unload(wxDllType handle);
 
224
};
 
225
 
 
226
 
 
227
 
 
228
// ============================================================================
 
229
// Global functions/macros
 
230
// ============================================================================
 
231
 
 
232
/** @addtogroup group_funcmacro_misc */
 
233
//@{
 
234
 
 
235
/**
 
236
    When loading a function from a DLL you always have to cast the returned
 
237
    <tt>void *</tt> pointer to the correct type and, even more annoyingly, you
 
238
    have to repeat this type twice if you want to declare and define a function
 
239
    pointer all in one line.
 
240
 
 
241
    This macro makes this slightly less painful by allowing you to specify the
 
242
    type only once, as the first parameter, and creating a variable of this
 
243
    type named after the function but with @c pfn prefix and initialized with
 
244
    the function @a name from the wxDynamicLibrary @a dynlib.
 
245
 
 
246
    @param type
 
247
        The type of the function.
 
248
    @param name
 
249
        The name of the function to load, not a string (without quotes, it is
 
250
        quoted automatically by the macro).
 
251
    @param dynlib
 
252
        The library to load the function from.
 
253
 
 
254
    @header{wx/dynlib.h}
 
255
*/
 
256
#define wxDYNLIB_FUNCTION(type, name, dynlib)
 
257
 
 
258
//@}
 
259