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

1/* This file is part of the KDE project
2 Copyright (C) 2007 Bernhard Loos <nhuh.put@web.de>
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 KDECORE_KPLUGINLOADER_H
19#define KDECORE_KPLUGINLOADER_H
20
21#include <kglobal.h>
22#include <kdeversion.h>
23#include <kexportplugin.h>
24
25#include <QtCore/QPluginLoader>
26#include <QtCore/QtPlugin>
27
28
29class KComponentData;
30class KPluginFactory;
31class KService;
32
33class KPluginLoaderPrivate;
34
35/**
36 * \class KPluginLoader kpluginloader.h <KPluginLoader>
37 *
38 * This class can be used to dynamically load a plugin library at runtime.
39 *
40 * This class makes sure that the Qt and KDE versions used to compile this library aren't newer than
41 * the ones currently used.
42 *
43 *
44 * This class is reentrant, you can load plugins from different threads. You can also have multiple
45 * PluginLoaders for one library without negative effects.
46 * The object obtained with factory() or the inherited method QPluginLoader::instance() is
47 * cached inside the library. If you call factory() or instance() multiple times, you will always get
48 * the same object, even from different threads and different KPluginLoader instances.
49 * You can delete this object easily, a new one will be created if factory() or instance() is called
50 * afterwards. factory() uses instance() internally.
51 *
52 * KPluginLoader inherits QPluginLoader::unload(). It is safe to call this method if you loaded a plugin
53 * and decide not to use it for some reason. But as soon as you start to use the factory from the plugin,
54 * you should stay away from it. It's nearly impossible to keep track of all objects created directly or
55 * indirectly from the plugin and all other pointers into plugin code. Using unload() in this case is asking
56 * for trouble. If you really need to unload your plugins, you have to take care to convert the clipboard
57 * content to text, because the plugin could have registered a custom mime source. You also have to delete
58 * the factory of the plugin, otherwise you will create a leak.
59 * The destructor of KPluginLoader doesn't call unload.
60 *
61 * Sample code:
62 * \code
63 * KPluginLoader loader( ...library or kservice... );
64 * KPluginFactory* factory = loader.factory();
65 * if (!factory) {
66 * kWarning() << "Error loading plugin:" << loader.errorString();
67 * } else {
68 * MyInterface* obj = factory->create<MyInterface>();
69 * if (!obj) {
70 * kWarning() << "Error creating object";
71 * }
72 * }
73 * \endcode
74 *
75 * \see KPluginFactory
76 *
77 * \author Bernhard Loos <nhuh.put@web.de>
78 */
79class KDECORE_EXPORT KPluginLoader : public QPluginLoader
80{
81 Q_OBJECT
82 Q_PROPERTY(QString fileName READ fileName) // KDE5: REMOVE?
83 Q_PROPERTY(QString pluginName READ pluginName) // KDE5: REMOVE?
84public:
85 /**
86 * Used this constructor to load a plugin with a given library name. Plugin libraries shouldn't have a 'lib' prefix.
87 *
88 * errorString() will be set if problems are encountered.
89 *
90 * \param plugin The name of the plugin library.
91 * \param componentdata The KStandardDirs object from componentdata is used to search the library.
92 * \param parent A parent object.
93 */
94 explicit KPluginLoader(const QString &plugin, const KComponentData &componentdata = KGlobal::mainComponent(), QObject *parent = 0);
95
96 /**
97 * Used this constructor to load a plugin from a service. The service must contain a library.
98 *
99 * errorString() will be set if problems are encountered.
100 *
101 * \param service The service for which the library should be loaded.
102 * \param componentdata The KStandardDirs object from componentdata is used to search the library.
103 * \param parent A parent object.
104 */
105 explicit KPluginLoader(const KService &service, const KComponentData &componentdata = KGlobal::mainComponent(), QObject *parent = 0);
106
107 /**
108 * Destroys the plugin loader.
109 */
110 ~KPluginLoader();
111
112 /**
113 * Used to obtain the factory object of the plugin. You have to give a class which inherits KPluginFactory
114 * to K_EXPORT_PLUGIN to use this method.
115 *
116 * \returns The factory of the plugin or 0 on error.
117 */
118 KPluginFactory *factory();
119
120 /**
121 * The name of this plugin as given to the constructor.
122 * \returns the plugin name
123 */
124 QString pluginName() const;
125
126 /**
127 * Queries the plugin version.
128 * \returns The version given to K_EXPORT_PLUGIN_VERSION or (quint32) -1 if not set.
129 */
130 quint32 pluginVersion() const;
131
132 /**
133 * Queries the last error.
134 * \returns The description of the last error.
135 */
136 QString errorString() const;
137
138 bool isLoaded() const;
139
140protected:
141 /**
142 * Performs the loading of the plugin.
143 */
144 bool load();
145private:
146 Q_DECLARE_PRIVATE(KPluginLoader)
147 Q_DISABLE_COPY(KPluginLoader)
148
149 using QPluginLoader::setFileName;
150
151 KPluginLoaderPrivate *const d_ptr;
152};
153
154
155#endif
156

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