Warning: That file was not part of the compilation database. It may have many parsing errors.

1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Torben Weis <weis@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
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
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18#ifndef KLIBLOADER_H
19#define KLIBLOADER_H
20
21#include <kglobal.h>
22
23#include <QtCore/QObject>
24#include <QtCore/QStringList>
25#include <QtCore/QHash>
26#include <QtCore/QLibrary>
27#include <QtCore/QtPlugin>
28
29#include "kpluginfactory.h"
30#include "kpluginloader.h"
31#include "klibrary.h"
32
33#ifndef KDE_NO_DEPRECATED
34
35# define K_EXPORT_COMPONENT_FACTORY( libname, factory ) \
36 extern "C" { KDE_EXPORT KPluginFactory *init_##libname() { return new factory; } }
37
38/**
39 * \class KLibLoader klibloader.h <KLibLoader>
40 *
41 * The KLibLoader allows you to load libraries dynamically at runtime.
42 * Dependent libraries are loaded automatically.
43 *
44 * KLibLoader follows the singleton pattern. You can not create multiple
45 * instances. Use self() to get a pointer to the loader.
46 *
47 * @deprecated You have two other possibilites:
48 * - KPluginLoader or KService::createInstance for plugins
49 * - KLibrary for other libraries
50 *
51 * @see KLibrary
52 * @see KPluginLoader
53 * @author Torben Weis <weis@kde.org>
54 */
55class KDECORE_EXPORT KLibLoader : public QObject //krazy:exclude=dpointer (private class is kept as a global static)
56{
57 friend class KLibrary;
58 friend class KLibraryPrivate;
59 friend class KLibLoaderPrivate;
60
61 Q_OBJECT
62public:
63 /**
64 * Loads and initializes a library. Loading a library multiple times is
65 * handled gracefully.
66 *
67 * This is a convenience function that returns the factory immediately
68 * @param libname This is the library name without extension. Usually that is something like
69 * "libkspread". The function will then search for a file named
70 * "libkspread.la" in the KDE library paths.
71 * The *.la files are created by libtool and contain
72 * important information especially about the libraries dependencies
73 * on other shared libs. Loading a "libfoo.so" could not solve the
74 * dependencies problem.
75 *
76 * You can, however, give a library name ending in ".so"
77 * (or whatever is used on your platform), and the library
78 * will be loaded without resolving dependencies. Use with caution.
79 * @param loadHint provides more control over how the library is loaded
80 * @return the KPluginFactory, or 0 if the library does not exist or it does
81 * not have a factory
82 * @see library
83 */
84 KPluginFactory* factory( const QString &libname, QLibrary::LoadHints loadHint = 0);
85
86 /**
87 * Loads and initializes a library. Loading a library multiple times is
88 * handled gracefully.
89 *
90 * @param libname This is the library name without extension. Usually that is something like
91 * "libkspread". The function will then search for a file named
92 * "libkspread.la" in the KDE library paths.
93 * The *.la files are created by libtool and contain
94 * important information especially about the libraries dependencies
95 * on other shared libs. Loading a "libfoo.so" could not solve the
96 * dependencies problem.
97 *
98 * You can, however, give a library name ending in ".so"
99 * (or whatever is used on your platform), and the library
100 * will be loaded without resolving dependencies. Use with caution.
101 * @param loadHint provides more control over how the library is loaded
102 * @return KLibrary is invalid (0) when the library couldn't be dlopened. in such
103 * a case you can retrieve the error message by calling KLibLoader::lastErrorMessage()
104 *
105 * @see factory
106 */
107 KLibrary* library( const QString &libname, QLibrary::LoadHints loadHint = 0 );
108
109 /**
110 * Returns an error message that can be useful to debug the problem.
111 * Returns QString() if the last call to library() was successful.
112 * You can call this function more than once. The error message is only
113 * reset by a new call to library().
114 * @return the last error message, or QString() if there was no error
115 */
116 QString lastErrorMessage() const;
117
118 /**
119 * Unloads the library with the given name.
120 * @param libname This is the library name without extension. Usually that is something like
121 * "libkspread". The function will then search for a file named
122 * "libkspread.la" in the KDE library paths.
123 * The *.la files are created by libtool and contain
124 * important information especially about the libraries dependencies
125 * on other shared libs. Loading a "libfoo.so" could not solve the
126 * dependencies problem.
127 *
128 * You can, however, give a library name ending in ".so"
129 * (or whatever is used on your platform), and the library
130 * will be loaded without resolving dependencies. Use with caution.
131 */
132 void unloadLibrary( const QString &libname );
133
134 /**
135 * Returns a pointer to the factory.
136 *
137 * Use this function to get an instance of KLibLoader.
138 *
139 * @return a pointer to the loader. If no loader exists until now
140 * then one is created.
141 *
142 * @deprecated use KPluginLoader instead
143 */
144 static KDE_DEPRECATED KLibLoader* self();
145
146 /**
147 * Helper method which looks for a library in the standard paths
148 * ("module" and "lib" resources).
149 * Made public for code that doesn't use KLibLoader itself, but still
150 * wants to open modules.
151 * @param libname of the library. If it is not a path, the function searches in
152 * the "module" and "lib" resources. If there is no extension,
153 * ".la" will be appended.
154 * @param cData a KComponentData used to get the standard paths
155 * @return the name of the library if it was found, an empty string otherwise
156 */
157 static QString findLibrary(const QString &libname, const KComponentData &cData = KGlobal::mainComponent());
158
159 /**
160 * This enum type defines the possible error cases that can happen
161 * when loading a component.
162 *
163 * Use errorString() to convert the error code to a human-readable string
164 */
165 enum ComponentLoadingError {
166 ErrNoLibrary = 1, /*< the specified library could not be loaded. Use KLibLoader::lastErrorMessage for details*/
167 ErrNoFactory, /*< the library does not export a factory */
168 ErrNoComponent, /*< the factory does not support creating components of the specified type */
169 ErrServiceProvidesNoLibrary, /*< the specified service provides no shared library (when using KService) */
170 ErrNoServiceFound /*< no service implementing the given servicetype and fullfilling the given constraint expression can be found (when using KServiceTypeTrader) */
171 };
172
173 /**
174 * Converts a numerical error code into a human-readable error message
175 *
176 * @param componentLoadingError the error code, as set using the @p error
177 * parameter of createInstance()
178 * @return the translated error message describing the error represented
179 * by @p componentLoadingError
180 *
181 * @see ComponentLoadingError
182 */
183 static QString errorString( int componentLoadingError );
184
185
186 /**
187 * This template allows to load the specified library and ask the
188 * factory to create an instance of the given template type.
189 *
190 * @param keyword the keyword for the plugin - see KPluginFactory::registerPlugin()
191 * @param libname the library to open
192 * @param parent the parent object (see QObject constructor)
193 * @param args a list of string arguments, passed to the factory and possibly
194 * to the component (see KPluginFactory)
195 * @param error if not null, the int will be set to 0 on success or one of the
196 * error codes defined by ComponentLoadingError if there was an error
197 * @return a pointer to the newly created object or a null pointer if the
198 * factory was unable to create an object of the given type
199 * @deprecated Use KService::createInstance() or KPluginLoader instead
200 */
201 template <typename T>
202 static KDE_DEPRECATED T *createInstance(const QString &keyword, const QString &libname, QObject *parent = 0,
203 const QVariantList &args = QVariantList(),
204 int *error = 0 )
205 {
206 KLibrary *library = KLibLoader::self()->library( libname );
207 if ( !library )
208 {
209 if ( error )
210 *error = ErrNoLibrary;
211 return 0;
212 }
213 KPluginFactory *factory = library->factory();
214 if ( !factory )
215 {
216 library->unload();
217 if ( error )
218 *error = ErrNoFactory;
219 return 0;
220 }
221 QObject *object = factory->template create<T>(keyword, parent, args);
222 T *res = qobject_cast<T *>( object );
223 if ( !res )
224 {
225 delete object;
226 library->unload();
227 if ( error )
228 *error = ErrNoComponent;
229 }
230 return res;
231 }
232
233 /**
234 * This template allows to load the specified library and ask the
235 * factory to create an instance of the given template type.
236 *
237 * @param libname the library to open
238 * @param parent the parent object (see QObject constructor)
239 * @param args a list of string arguments, passed to the factory and possibly
240 * to the component (see KPluginFactory)
241 * @param error if not null, the int will be set to 0 on success or one of the
242 * error codes defined by ComponentLoadingError if there was an error
243 * @return a pointer to the newly created object or a null pointer if the
244 * factory was unable to create an object of the given type
245 * @deprecated Use KService::createInstance() or KPluginLoader instead
246 */
247 template <typename T>
248 static KDE_DEPRECATED T *createInstance( const QString &libname, QObject *parent = 0,
249 const QVariantList &args = QVariantList(),
250 int *error = 0 )
251 {
252 return createInstance<T>(QString(), libname, parent, args, error);
253 }
254
255 /**
256 * @deprecated Use one of the other createInstance methods or
257 * KPluginLoader or KService::createInstance instead
258 */
259 template <typename T>
260 static KDE_DEPRECATED T *createInstance( const QString &libname, QObject *parent,
261 const QStringList &args,
262 int *error = 0 )
263 {
264 KLibrary *library = KLibLoader::self()->library( libname );
265 if ( !library )
266 {
267 if ( error )
268 *error = ErrNoLibrary;
269 return 0;
270 }
271 KPluginFactory *factory = library->factory();
272 if ( !factory )
273 {
274 library->unload();
275 if ( error )
276 *error = ErrNoFactory;
277 return 0;
278 }
279 QObject *object = factory->template create<T>(parent, args);
280 T *res = qobject_cast<T *>( object );
281 if ( !res )
282 {
283 delete object;
284 library->unload();
285 if ( error )
286 *error = ErrNoComponent;
287 }
288 return res;
289 }
290
291private:
292 ~KLibLoader();
293
294 KLibLoader();
295};
296
297#endif
298#endif
299

Warning: That file was not part of the compilation database. It may have many parsing errors.