summaryrefslogtreecommitdiffabout
path: root/microkde/kdecore/klibloader.h
Unidiff
Diffstat (limited to 'microkde/kdecore/klibloader.h') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/kdecore/klibloader.h10
1 files changed, 5 insertions, 5 deletions
diff --git a/microkde/kdecore/klibloader.h b/microkde/kdecore/klibloader.h
index ed57109..53d146e 100644
--- a/microkde/kdecore/klibloader.h
+++ b/microkde/kdecore/klibloader.h
@@ -1,178 +1,178 @@
1/* This file is part of the KDE libraries 1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Torben Weis <weis@kde.org> 2 Copyright (C) 1999 Torben Weis <weis@kde.org>
3 3
4 This library is free software; you can redistribute it and/or 4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public 5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation. 6 License version 2 as published by the Free Software Foundation.
7 7
8 This library is distributed in the hope that it will be useful, 8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of 9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details. 11 Library General Public License for more details.
12 12
13 You should have received a copy of the GNU Library General Public License 13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to 14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, 15 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
16 Boston, MA 02111-1307, USA. 16 Boston, MA 02111-1307, USA.
17*/ 17*/
18#ifndef KLIBLOADER_H 18#ifndef KLIBLOADER_H
19#define KLIBLOADER_H 19#define KLIBLOADER_H
20 20
21#include <qobject.h> 21#include <qobject.h>
22#include <qstring.h> 22#include <qstring.h>
23#include <qstringlist.h> 23#include <qstringlist.h>
24#include <qasciidict.h> 24#include <q3asciidict.h>
25#include <qptrlist.h> 25#include <q3ptrlist.h>
26#include <kglobal.h> 26#include <kglobal.h>
27 27
28#include <stdlib.h> // For backwards compatibility 28#include <stdlib.h> // For backwards compatibility
29 29
30class KInstance; 30class KInstance;
31class QTimer; 31class QTimer;
32class KLibrary; 32class KLibrary;
33class KLibFactory; 33class KLibFactory;
34class KLibFactoryPrivate; 34class KLibFactoryPrivate;
35class KLibLoaderPrivate; 35class KLibLoaderPrivate;
36class KLibraryPrivate; 36class KLibraryPrivate;
37 37
38class QLibrary; 38class QLibrary;
39 39
40#define K_EXPORT_COMPONENT_FACTORY( libname, factory ) \ 40#define K_EXPORT_COMPONENT_FACTORY( libname, factory ) \
41 extern "C" { void *init_##libname() { return new factory; } } 41 extern "C" { void *init_##libname() { return new factory; } }
42 42
43/** 43/**
44 * @short Represents a dynamically loaded library. 44 * @short Represents a dynamically loaded library.
45 * 45 *
46 * KLibrary allows you to look up symbols of the shared library. 46 * KLibrary allows you to look up symbols of the shared library.
47 * Use @ref KLibLoader to create a new instance of KLibrary. 47 * Use @ref KLibLoader to create a new instance of KLibrary.
48 * 48 *
49 * @see KLibLoader 49 * @see KLibLoader
50 * @author Torben Weis <weis@kde.org> 50 * @author Torben Weis <weis@kde.org>
51 */ 51 */
52class KLibrary : public QObject 52class KLibrary : public QObject
53{ 53{
54 friend class KLibLoader; 54 friend class KLibLoader;
55 friend class QAsciiDict<KLibrary>; 55 friend class Q3AsciiDict<KLibrary>;
56 56
57 Q_OBJECT 57 Q_OBJECT
58public: 58public:
59 /** 59 /**
60 * @internal 60 * @internal
61 * Don't create KLibrary objects on your own. Instead use @ref KLibLoader. 61 * Don't create KLibrary objects on your own. Instead use @ref KLibLoader.
62 */ 62 */
63//US KLibrary( const QString& libname, const QString& filename, void * handle ); 63//US KLibrary( const QString& libname, const QString& filename, void * handle );
64 KLibrary( const QString& libname, const QString& filename, QLibrary* handle ); 64 KLibrary( const QString& libname, const QString& filename, QLibrary* handle );
65 65
66 /** 66 /**
67 * Returns the name of the library. 67 * Returns the name of the library.
68 * @return The name of the library like "libkspread". 68 * @return The name of the library like "libkspread".
69 */ 69 */
70 QString name() const; 70 QString name() const;
71 71
72 /** 72 /**
73 * Returns the file name of the library. 73 * Returns the file name of the library.
74 * @return The filename of the library, for example "/opt/kde2&/lib/libkspread.la" 74 * @return The filename of the library, for example "/opt/kde2&/lib/libkspread.la"
75 */ 75 */
76 QString fileName() const; 76 QString fileName() const;
77 77
78 /** 78 /**
79 * Returns the factory of the library. 79 * Returns the factory of the library.
80 * @return The factory of the library if there is any, otherwise 0 80 * @return The factory of the library if there is any, otherwise 0
81 */ 81 */
82 KLibFactory* factory(); 82 KLibFactory* factory();
83 83
84 /** 84 /**
85 * Looks up a symbol from the library. This is a very low level 85 * Looks up a symbol from the library. This is a very low level
86 * function that you usually don't want to use. Usually you should 86 * function that you usually don't want to use. Usually you should
87 * check using @ref hasSymbol() whether the symbol actually exists, 87 * check using @ref hasSymbol() whether the symbol actually exists,
88 * otherwise a warning will be printed. 88 * otherwise a warning will be printed.
89 * @param name the name of the symbol to look up 89 * @param name the name of the symbol to look up
90 * @return the address of the symbol, or 0 if it does not exist 90 * @return the address of the symbol, or 0 if it does not exist
91 * @see #hasSymbol 91 * @see #hasSymbol
92 */ 92 */
93 void* symbol( const char* name ) const; 93 void* symbol( const char* name ) const;
94 94
95 /** 95 /**
96 * Looks up a symbol from the library. This is a very low level 96 * Looks up a symbol from the library. This is a very low level
97 * function that you usually don't want to use. 97 * function that you usually don't want to use.
98 * Unlike @ref symbol(), this method doesn't warn if the symbol doesn't exist, 98 * Unlike @ref symbol(), this method doesn't warn if the symbol doesn't exist,
99 * so if the symbol might or might not exist, better use hasSymbol() before symbol(). 99 * so if the symbol might or might not exist, better use hasSymbol() before symbol().
100 * @param name the name of the symbol to check 100 * @param name the name of the symbol to check
101 * @return true if the symbol exists 101 * @return true if the symbol exists
102 * @since 3.1 102 * @since 3.1
103 */ 103 */
104 bool hasSymbol( const char* name ) const; 104 bool hasSymbol( const char* name ) const;
105 105
106 /** 106 /**
107 * Unloads the library. 107 * Unloads the library.
108 * This typically results in the deletion of this object. You should 108 * This typically results in the deletion of this object. You should
109 * not reference its pointer after calling this function. 109 * not reference its pointer after calling this function.
110 */ 110 */
111 void unload() const; 111 void unload() const;
112 112
113private slots: 113private slots:
114 void slotObjectCreated( QObject *obj ); 114 void slotObjectCreated( QObject *obj );
115 void slotObjectDestroyed(); 115 void slotObjectDestroyed();
116 void slotTimeout(); 116 void slotTimeout();
117 117
118private: 118private:
119 /** 119 /**
120 * @internal 120 * @internal
121 * Don't destruct KLibrary objects yourself. Instead use @ref unload() instead. 121 * Don't destruct KLibrary objects yourself. Instead use @ref unload() instead.
122 */ 122 */
123 ~KLibrary(); 123 ~KLibrary();
124 124
125 QString m_libname; 125 QString m_libname;
126 QString m_filename; 126 QString m_filename;
127 KLibFactory* m_factory; 127 KLibFactory* m_factory;
128//US void * m_handle; 128//US void * m_handle;
129 QLibrary* m_handle; 129 QLibrary* m_handle;
130 QPtrList<QObject> m_objs; 130 Q3PtrList<QObject> m_objs;
131 QTimer *m_timer; 131 QTimer *m_timer;
132 KLibraryPrivate *d; 132 KLibraryPrivate *d;
133}; 133};
134 134
135class KLibWrapPrivate; 135class KLibWrapPrivate;
136 136
137/** 137/**
138 * The KLibLoader allows you to load libraries dynamically at runtime. 138 * The KLibLoader allows you to load libraries dynamically at runtime.
139 * Dependent libraries are loaded automatically. 139 * Dependent libraries are loaded automatically.
140 * 140 *
141 * KLibLoader follows the singleton pattern. You can not create multiple 141 * KLibLoader follows the singleton pattern. You can not create multiple
142 * instances. Use @ref self() to get a pointer to the loader. 142 * instances. Use @ref self() to get a pointer to the loader.
143 * 143 *
144 * @see KLibrary 144 * @see KLibrary
145 * @author Torben Weis <weis@kde.org> 145 * @author Torben Weis <weis@kde.org>
146 */ 146 */
147class KLibLoader : public QObject 147class KLibLoader : public QObject
148{ 148{
149 friend class KLibrary; 149 friend class KLibrary;
150 150
151 Q_OBJECT 151 Q_OBJECT
152public: 152public:
153 /** 153 /**
154 * You should NEVER destruct an instance of KLibLoader 154 * You should NEVER destruct an instance of KLibLoader
155 * until you know what you are doing. This will release 155 * until you know what you are doing. This will release
156 * the loaded libraries. 156 * the loaded libraries.
157 */ 157 */
158 ~KLibLoader(); 158 ~KLibLoader();
159 159
160 /** 160 /**
161 * Loads and initializes a library. Loading a library multiple times is 161 * Loads and initializes a library. Loading a library multiple times is
162 * handled gracefully. 162 * handled gracefully.
163 * 163 *
164 * This is a convenience function that returns the factory immediately 164 * This is a convenience function that returns the factory immediately
165 * @param libname This is the library name without extension. Usually that is something like 165 * @param libname This is the library name without extension. Usually that is something like
166 * "libkspread". The function will then search for a file named 166 * "libkspread". The function will then search for a file named
167 * "libkspread.la" in the KDE library paths. 167 * "libkspread.la" in the KDE library paths.
168 * The *.la files are created by libtool and contain 168 * The *.la files are created by libtool and contain
169 * important information especially about the libraries dependencies 169 * important information especially about the libraries dependencies
170 * on other shared libs. Loading a "libfoo.so" could not solve the 170 * on other shared libs. Loading a "libfoo.so" could not solve the
171 * dependencies problem. 171 * dependencies problem.
172 * 172 *
173 * You can, however, give a library name ending in ".so" 173 * You can, however, give a library name ending in ".so"
174 * (or whatever is used on your platform), and the library 174 * (or whatever is used on your platform), and the library
175 * will be loaded without resolving dependencies. USE WITH CARE :) 175 * will be loaded without resolving dependencies. USE WITH CARE :)
176 * @return the @ref KLibFactory, or 0 if the library does not exist or it does 176 * @return the @ref KLibFactory, or 0 if the library does not exist or it does
177 * not have a factory 177 * not have a factory
178 * @see #library 178 * @see #library
@@ -242,97 +242,97 @@ public:
242 * The *.la files are created by libtool and contain 242 * The *.la files are created by libtool and contain
243 * important information especially about the libraries dependencies 243 * important information especially about the libraries dependencies
244 * on other shared libs. Loading a "libfoo.so" could not solve the 244 * on other shared libs. Loading a "libfoo.so" could not solve the
245 * dependencies problem. 245 * dependencies problem.
246 * 246 *
247 * You can, however, give a library name ending in ".so" 247 * You can, however, give a library name ending in ".so"
248 * (or whatever is used on your platform), and the library 248 * (or whatever is used on your platform), and the library
249 * will be loaded without resolving dependencies. USE WITH CARE :) 249 * will be loaded without resolving dependencies. USE WITH CARE :)
250 */ 250 */
251 virtual void unloadLibrary( const char *libname ); 251 virtual void unloadLibrary( const char *libname );
252 252
253 /** 253 /**
254 * Returns a pointer to the factory. Use this function to get an instance 254 * Returns a pointer to the factory. Use this function to get an instance
255 * of KLibLoader. 255 * of KLibLoader.
256 * @return a pointer to the loader. If no loader exists until now 256 * @return a pointer to the loader. If no loader exists until now
257 * then one is created. 257 * then one is created.
258 */ 258 */
259 static KLibLoader* self(); 259 static KLibLoader* self();
260 260
261 /** 261 /**
262 * @internal 262 * @internal
263 * Internal Method, called by the KApplication destructor. 263 * Internal Method, called by the KApplication destructor.
264 * Do not call it. 264 * Do not call it.
265 * This is what makes it possible to rely on ~KLibFactory 265 * This is what makes it possible to rely on ~KLibFactory
266 * being called in all cases, whether the library is unloaded 266 * being called in all cases, whether the library is unloaded
267 * while the application is running or when exiting. 267 * while the application is running or when exiting.
268 */ 268 */
269 static void cleanUp(); 269 static void cleanUp();
270 270
271 /** 271 /**
272 * Helper method which looks for a library in the standard paths 272 * Helper method which looks for a library in the standard paths
273 * ("module" and "lib" resources). 273 * ("module" and "lib" resources).
274 * Made public for code that doesn't use KLibLoader itself, but still 274 * Made public for code that doesn't use KLibLoader itself, but still
275 * wants to open modules. 275 * wants to open modules.
276 * @param name of the library. If it is not a path, the function searches in 276 * @param name of the library. If it is not a path, the function searches in
277 * the "module" and "lib" resources. If there is no extension, 277 * the "module" and "lib" resources. If there is no extension,
278 * ".la" will be appended. 278 * ".la" will be appended.
279 * @param instance a KInstance used to get the standard paths 279 * @param instance a KInstance used to get the standard paths
280 */ 280 */
281 static QString findLibrary( const char * name/*US , const KInstance * instance = KGlobal::instance()*/ ); 281 static QString findLibrary( const char * name/*US , const KInstance * instance = KGlobal::instance()*/ );
282 282
283protected: 283protected:
284 KLibLoader( QObject* parent = 0, const char* name = 0 ); 284 KLibLoader( QObject* parent = 0, const char* name = 0 );
285 285
286private slots: 286private slots:
287 void slotLibraryDestroyed(); 287 void slotLibraryDestroyed();
288private: 288private:
289 void close_pending( KLibWrapPrivate * ); 289 void close_pending( KLibWrapPrivate * );
290 QAsciiDict<KLibWrapPrivate> m_libs; 290 Q3AsciiDict<KLibWrapPrivate> m_libs;
291 291
292 static KLibLoader* s_self; 292 static KLibLoader* s_self;
293 293
294protected: 294protected:
295 virtual void virtual_hook( int id, void* data ); 295 virtual void virtual_hook( int id, void* data );
296private: 296private:
297 KLibLoaderPrivate *d; 297 KLibLoaderPrivate *d;
298}; 298};
299 299
300/** 300/**
301 * If you develop a library that is to be loaded dynamically at runtime, then 301 * If you develop a library that is to be loaded dynamically at runtime, then
302 * you should return a pointer to your factory. The K_EXPORT_COMPONENT_FACTORY 302 * you should return a pointer to your factory. The K_EXPORT_COMPONENT_FACTORY
303 * macro is provided for this purpose: 303 * macro is provided for this purpose:
304 * <pre> 304 * <pre>
305 * K_EXPORT_COMPONENT_FACTORY( libkspread, KSpreadFactory ) 305 * K_EXPORT_COMPONENT_FACTORY( libkspread, KSpreadFactory )
306 * </pre> 306 * </pre>
307 * 307 *
308 * The first macro argument is the name of your library, the second specifies the name 308 * The first macro argument is the name of your library, the second specifies the name
309 * of your factory. 309 * of your factory.
310 * 310 *
311 * In the constructor of your factory you should create an instance of @ref KInstance 311 * In the constructor of your factory you should create an instance of @ref KInstance
312 * like this: 312 * like this:
313 * <pre> 313 * <pre>
314 * s_global = new KInstance( "kspread" ); 314 * s_global = new KInstance( "kspread" );
315 * </pre> 315 * </pre>
316 * This @ref KInstance is comparable to @ref KGlobal used by normal applications. 316 * This @ref KInstance is comparable to @ref KGlobal used by normal applications.
317 * It allows you to find resource files (images, XML, sound etc.) belonging 317 * It allows you to find resource files (images, XML, sound etc.) belonging
318 * to the library. 318 * to the library.
319 * 319 *
320 * If you want to load a library, use @ref KLibLoader. You can query @ref KLibLoader 320 * If you want to load a library, use @ref KLibLoader. You can query @ref KLibLoader
321 * directly for a pointer to the libraries factory by using the @ref KLibLoader::factory() 321 * directly for a pointer to the libraries factory by using the @ref KLibLoader::factory()
322 * function. 322 * function.
323 * 323 *
324 * The KLibFactory is used to create the components, the library has to offer. 324 * The KLibFactory is used to create the components, the library has to offer.
325 * The factory of KSpread for example will create instances of KSpreadDoc, 325 * The factory of KSpread for example will create instances of KSpreadDoc,
326 * while the Konqueror factory will create KonqView widgets. 326 * while the Konqueror factory will create KonqView widgets.
327 * All objects created by the factory must be derived from @ref QObject, since @ref QObject 327 * All objects created by the factory must be derived from @ref QObject, since @ref QObject
328 * offers type safe casting. 328 * offers type safe casting.
329 * 329 *
330 * KLibFactory is an abstract class. Reimplement the @ref 330 * KLibFactory is an abstract class. Reimplement the @ref
331 * createObject() method to give it functionality. 331 * createObject() method to give it functionality.
332 * 332 *
333 * @author Torben Weis <weis@kde.org> 333 * @author Torben Weis <weis@kde.org>
334 */ 334 */
335class KLibFactory : public QObject 335class KLibFactory : public QObject
336{ 336{
337 Q_OBJECT 337 Q_OBJECT
338public: 338public: