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 | */ |
55 | class 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 |
62 | public: |
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 | |
291 | private: |
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.