]> git.saurik.com Git - wxWidgets.git/blame_incremental - include/wx/dynlib.h
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / include / wx / dynlib.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: wx/dynlib.h
3// Purpose: Dynamic library loading classes
4// Author: Guilhem Lavaux, Vadim Zeitlin, Vaclav Slavik
5// Modified by:
6// Created: 20/07/98
7// RCS-ID: $Id$
8// Copyright: (c) 1998 Guilhem Lavaux
9// Licence: wxWindows licence
10/////////////////////////////////////////////////////////////////////////////
11
12#ifndef _WX_DYNLIB_H__
13#define _WX_DYNLIB_H__
14
15#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
16# pragma interface "dynlib.h"
17#endif
18
19#include "wx/setup.h"
20
21#if wxUSE_DYNLIB_CLASS
22
23#include "wx/string.h"
24
25// FIXME: can this go in private.h or something too??
26#if defined(__WXPM__) || defined(__EMX__)
27#define INCL_DOS
28#include <os2.h>
29#endif
30
31#ifdef __WXMSW__
32#include "wx/msw/private.h"
33#endif
34
35// ----------------------------------------------------------------------------
36// conditional compilation
37// ----------------------------------------------------------------------------
38
39// Note: WXPM/EMX has to be tested first, since we want to use
40// native version, even if configure detected presence of DLOPEN.
41#if defined(__WXPM__) || defined(__EMX__) || defined(__WINDOWS__)
42 typedef HMODULE wxDllType;
43#elif defined(HAVE_DLOPEN)
44 #include <dlfcn.h>
45 typedef void *wxDllType;
46#elif defined(HAVE_SHL_LOAD)
47 #include <dl.h>
48 typedef shl_t wxDllType;
49#elif defined(__DARWIN__)
50 typedef void *wxDllType;
51#elif defined(__WXMAC__)
52 #include <CodeFragments.h>
53 typedef CFragConnectionID wxDllType;
54#else
55 #error "Dynamic Loading classes can't be compiled on this platform, sorry."
56#endif
57
58// ----------------------------------------------------------------------------
59// constants
60// ----------------------------------------------------------------------------
61
62enum wxDLFlags
63{
64 wxDL_LAZY = 0x00000001, // resolve undefined symbols at first use
65 wxDL_NOW = 0x00000002, // resolve undefined symbols on load
66 wxDL_GLOBAL = 0x00000004, // export extern symbols to subsequently
67 // loaded libs.
68 wxDL_VERBATIM = 0x00000008, // Attempt to load the supplied library
69 // name without appending the usual dll
70 // filename extension.
71
72 wxDL_NOSHARE = 0x00000010, // load new DLL, don't reuse already loaded
73
74 // FIXME: why? (VZ)
75#ifdef __osf__
76 wxDL_DEFAULT = wxDL_LAZY
77#else
78 wxDL_DEFAULT = wxDL_LAZY | wxDL_GLOBAL
79#endif
80};
81
82enum wxDynamicLibraryCategory
83{
84 wxDL_LIBRARY, // standard library
85 wxDL_MODULE // loadable module/plugin
86};
87
88enum wxPluginCategory
89{
90 wxDL_PLUGIN_GUI, // plugin that uses GUI classes
91 wxDL_PLUGIN_BASE // wxBase-only plugin
92};
93
94// ----------------------------------------------------------------------------
95// macros
96// ----------------------------------------------------------------------------
97
98// when loading a function from a DLL you always have to cast the returned
99// "void *" pointer to the correct type and, even more annoyingly, you have to
100// repeat this type twice if you want to declare and define a function pointer
101// all in one line
102//
103// this macro makes this slightly less painful by allowing you to specify the
104// type only once, as the first parameter, and creating a variable of this type
105// called "pfn<name>" initialized with the "name" from the "dynlib"
106#define wxDYNLIB_FUNCTION(type, name, dynlib) \
107 type pfn ## name = (type)(dynlib).GetSymbol(_T(#name))
108
109// ---------------------------------------------------------------------------
110// wxDynamicLibrary
111// ---------------------------------------------------------------------------
112
113class WXDLLIMPEXP_BASE wxDynamicLibrary
114{
115public:
116 // return a valid handle for the main program itself or NULL if back
117 // linking is not supported by the current platform (e.g. Win32)
118 static wxDllType GetProgramHandle();
119
120 // return the platform standard DLL extension (with leading dot)
121 static const wxChar *GetDllExt() { return ms_dllext; }
122
123 wxDynamicLibrary() : m_handle(0) { }
124 wxDynamicLibrary(const wxString& libname, int flags = wxDL_DEFAULT)
125 : m_handle(0)
126 {
127 Load(libname, flags);
128 }
129
130 // NOTE: this class is (deliberately) not virtual, do not attempt
131 // to use it polymorphically.
132 ~wxDynamicLibrary() { Unload(); }
133
134 // return TRUE if the library was loaded successfully
135 bool IsLoaded() const { return m_handle != 0; }
136
137 // load the library with the given name (full or not), return true if ok
138 bool Load(wxString libname, int flags = wxDL_DEFAULT);
139
140 // detach the library object from its handle, i.e. prevent the object from
141 // unloading the library in its dtor -- the caller is now responsible for
142 // doing this
143 wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; }
144
145 // unload the given library handle (presumably returned by Detach() before)
146 static void Unload(wxDllType handle);
147
148 // unload the library, also done automatically in dtor
149 void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } }
150
151 // Return the raw handle from dlopen and friends.
152 wxDllType GetLibHandle() const { return m_handle; }
153
154 // resolve a symbol in a loaded DLL, such as a variable or function name.
155 // 'name' is the (possibly mangled) name of the symbol. (use extern "C" to
156 // export unmangled names)
157 //
158 // Since it is perfectly valid for the returned symbol to actually be NULL,
159 // that is not always indication of an error. Pass and test the parameter
160 // 'success' for a true indication of success or failure to load the
161 // symbol.
162 //
163 // Returns a pointer to the symbol on success, or NULL if an error occurred
164 // or the symbol wasn't found.
165 void *GetSymbol(const wxString& name, bool *success = 0) const;
166
167
168 // return platform-specific name of dynamic library with proper extension
169 // and prefix (e.g. "foo.dll" on Windows or "libfoo.so" on Linux)
170 static wxString CanonicalizeName(const wxString& name,
171 wxDynamicLibraryCategory cat = wxDL_LIBRARY);
172
173 // return name of wxWidgets plugin (adds compiler and version info
174 // to the filename):
175 static wxString
176 CanonicalizePluginName(const wxString& name,
177 wxPluginCategory cat = wxDL_PLUGIN_GUI);
178
179 // return plugin directory on platforms where it makes sense and empty
180 // string on others:
181 static wxString GetPluginsDirectory();
182
183
184#if WXWIN_COMPATIBILITY_2_2
185 operator bool() const { return IsLoaded(); }
186#endif
187
188protected:
189 // platform specific shared lib suffix.
190 static const wxChar *ms_dllext;
191
192 // the handle to DLL or NULL
193 wxDllType m_handle;
194
195 // no copy ctor/assignment operators (or we'd try to unload the library
196 // twice)
197 DECLARE_NO_COPY_CLASS(wxDynamicLibrary)
198};
199
200
201// ----------------------------------------------------------------------------
202// wxDllLoader: low level DLL functions, use wxDynamicLibrary in your code
203// ----------------------------------------------------------------------------
204
205#if WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
206
207/*
208 wxDllLoader is a class providing an interface similar to unix's dlopen().
209 It is used by wxDynamicLibrary wxLibrary and manages the actual loading of
210 DLLs and the resolving of symbols in them. There are no instances of this
211 class, it simply serves as a namespace for its static member functions.
212*/
213class WXDLLIMPEXP_BASE wxDllLoader
214{
215public:
216 /*
217 This function loads the shared library libname into memory.
218
219 libname may be either the full path to the file or just the filename in
220 which case the library is searched for in all standard locations
221 (use GetDllExt() to construct the filename)
222
223 if success pointer is not NULL, it will be filled with TRUE if everything
224 went ok and FALSE otherwise
225 */
226 static wxDllType LoadLibrary(const wxString& name, bool *success = NULL);
227
228 /*
229 This function unloads the shared library previously loaded with
230 LoadLibrary
231 */
232 static void UnloadLibrary(wxDllType dll);
233
234 /*
235 This function returns a valid handle for the main program
236 itself or NULL if back linking is not supported by the current platform
237 (e.g. Win32).
238 */
239 static wxDllType GetProgramHandle() { return wxDynamicLibrary::GetProgramHandle(); }
240
241 /*
242 This function resolves a symbol in a loaded DLL, such as a
243 variable or function name.
244
245 dllHandle Handle of the DLL, as returned by LoadDll().
246 name Name of the symbol.
247
248 Returns the pointer to the symbol or NULL on error.
249 */
250 static void *GetSymbol(wxDllType dllHandle, const wxString &name, bool *success = 0);
251
252 // return the standard DLL extension (with leading dot) for this platform
253 static wxString GetDllExt() { return wxDynamicLibrary::GetDllExt(); }
254
255private:
256
257 wxDllLoader(); // forbid construction of objects
258};
259
260
261// ----------------------------------------------------------------------------
262// wxLibrary
263// ----------------------------------------------------------------------------
264
265#include "wx/hash.h"
266
267class WXDLLIMPEXP_BASE wxLibrary : public wxObject
268{
269public:
270 wxLibrary(wxDllType handle);
271 virtual ~wxLibrary();
272
273 // Get a symbol from the dynamic library
274 void *GetSymbol(const wxString& symbname);
275
276 // Create the object whose classname is "name"
277 wxObject *CreateObject(const wxString& name);
278
279protected:
280 void PrepareClasses(wxClassInfo *first);
281
282 wxDllType m_handle;
283
284public:
285 wxHashTable classTable;
286};
287
288// ----------------------------------------------------------------------------
289// wxLibraries
290// ----------------------------------------------------------------------------
291
292class WXDLLIMPEXP_BASE wxLibraries
293{
294public:
295 wxLibraries();
296 ~wxLibraries();
297
298 // caller is responsible for deleting the returned pointer if !NULL
299 wxLibrary *LoadLibrary(const wxString& basename);
300
301 wxObject *CreateObject(const wxString& name);
302
303protected:
304 wxList m_loaded;
305};
306
307// ----------------------------------------------------------------------------
308// Global variables
309// ----------------------------------------------------------------------------
310
311extern WXDLLIMPEXP_DATA_BASE(wxLibraries) wxTheLibraries;
312
313#endif // WXWIN_COMPATIBILITY_2_2 && wxUSE_DYNAMIC_LOADER
314
315// ----------------------------------------------------------------------------
316// Interesting defines
317// ----------------------------------------------------------------------------
318
319#define WXDLL_ENTRY_FUNCTION() \
320extern "C" WXEXPORT const wxClassInfo *wxGetClassFirst(); \
321const wxClassInfo *wxGetClassFirst() { \
322 return wxClassInfo::GetFirst(); \
323}
324
325#endif // wxUSE_DYNLIB_CLASS
326
327#endif // _WX_DYNLIB_H__