kopete/libkopete/kopetepluginmanager.h

   1 /*
   2     kopetepluginmanager.h - Kopete Plugin Loader
   3
   4     Copyright (c) 2002-2003 by Duncan Mac-Vicar Prett <duncan@kde.org>
   5     Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
   6
   7     Kopete    (c) 2002-2003 by the Kopete developers  <kopete-devel@kde.org>
   8
   9     *************************************************************************
  10     *                                                                       *
  11     * This library is free software; you can redistribute it and/or         *
  12     * modify it under the terms of the GNU Lesser General Public            *
  13     * License as published by the Free Software Foundation; either          *
  14     * version 2 of the License, or (at your option) any later version.      *
  15     *                                                                       *
  16     *************************************************************************
  17 */
  18
  19 #ifndef KOPETEPLUGINMANAGER_H
  20 #define KOPETEPLUGINMANAGER_H
  21
  22 #include <QtCore/QObject>
  23 #include <QtCore/QList>
  24 #include "kopete_export.h"
  25
  26 class KPluginInfo;
  27
  28 namespace Kopete
  29 {
  30
  31 class Plugin;
  32 typedef QList<Plugin*> PluginList;
  33 class PluginManagerPrivate;
  34
  35 /**
  36  * @author Duncan Mac-Vicar Prett <duncan@kde.org>
  37  * @author Martijn Klingens <klingens@kde.org>
  38  */
  39 class KOPETE_EXPORT PluginManager : public QObject
  40 {
  41         friend class PluginManagerPrivate;
  42         Q_OBJECT
  43         Q_ENUMS( PluginLoadMode )
  44
  45 public:
  46         /**
  47          * Retrieve the plugin loader instance.
  48          */
  49         static PluginManager* self();
  50
  51         /**
  52          * Returns a list of all available plugins for the given category.
  53          * Currently there are two categories, "Plugins" and "Protocols", but
  54          * you can add your own categories if you want.
  55          *
  56          * If you pass an empty string you get the complete list of ALL plugins.
  57          *
  58          * You can query all information on the plugins through the KPluginInfo
  59          * interface.
  60          */
  61         QList<KPluginInfo> availablePlugins( const QString &category = QString() ) const;
  62
  63         /**
  64          * Returns a list of all plugins that are actually loaded.
  65          * If you omit the category you get all, otherwise it's a filtered list.
  66          * See also @ref availablePlugins().
  67          */
  68         PluginList loadedPlugins( const QString &category = QString() ) const;
  69
  70         /**
  71          * @brief Search by plugin name. This is the key used as X-KDE-PluginInfo-Name in
  72          * the .desktop file, e.g. "kopete_jabber"
  73          *
  74          * @return The @ref Kopete::Plugin object found by the search, or a null
  75          * pointer if the plugin is not loaded.
  76          *
  77          * If you want to also load the plugin you can better use @ref loadPlugin, which returns
  78          * the pointer to the plugin if it's already loaded.
  79          */
  80         Plugin *plugin( const QString &pluginName ) const;
  81
  82         /**
  83          * @return the KPluginInfo for the specified plugin
  84          */
  85         KPluginInfo pluginInfo( const Kopete::Plugin *plugin ) const;
  86
  87
  88         /**
  89          * Shuts down the plugin manager on Kopete shutdown, but first
  90          * unloads all plugins asynchronously.
  91          *
  92          * After 3 seconds all plugins should be removed; what's still left
  93          * by then is unloaded through a hard delete instead.
  94          *
  95          * Note that this call also derefs the plugin manager from the event
  96          * loop, so do NOT call this method when not terminating Kopete!
  97          */
  98         void shutdown();
  99
 100         /**
 101          * Enable a plugin.
 102          *
 103          * This marks a plugin as enabled in the config file, so loadAll()
 104          * can pick it up later.
 105          *
 106          * This method does not actually load a plugin, it only edits the
 107          * config file.
 108          *
 109          * @param name is the name of the plugin as it is listed in the .desktop
 110          * file in the X-KDE-Library field.
 111          * @param enabled sets whether or not the plugin is enabled
 112          *
 113          * Returns false when no appropriate plugin can be found.
 114          */
 115         bool setPluginEnabled( const QString &name, bool enabled = true );
 116
 117         /**
 118          * This method check if all the plugins are loaded.
 119          * @return true if all the plugins are loaded.
 120          */
 121         bool isAllPluginsLoaded() const;
 122
 123         /**
 124          * Plugin loading mode. Used by @ref loadPlugin(). Code that doesn't want to block
 125          * the GUI and/or lot a lot of plugins at once should use asynchronous loading (@c LoadAsync).
 126          * The default is synchronous loading (@c LoadSync).
 127          */
 128         enum PluginLoadMode { LoadSync, LoadAsync };
 129
 130 public slots:
 131         /**
 132          * @brief Load a single plugin by plugin name. Returns an existing plugin
 133          * if one is already loaded in memory.
 134          *
 135          * If mode is set to Async, the plugin will be queued and loaded in
 136          * the background. This method will return a null pointer. To get
 137          * the loaded plugin you can track the @ref pluginLoaded() signal.
 138          *
 139          * See also @ref plugin().
 140          */
 141         Plugin *loadPlugin( const QString &pluginId, PluginLoadMode mode = LoadSync );
 142
 143         /**
 144          * @brief Unload the plugin specified by @p pluginName
 145          */
 146         bool unloadPlugin( const QString &pluginName );
 147
 148         /**
 149          * @brief Loads all the enabled plugins. Also used to reread the
 150          * config file when the configuration has changed.
 151          */
 152         void loadAllPlugins();
 153
 154 signals:
 155         /**
 156          * @brief Signals a new plugin has just been loaded.
 157          */
 158         void pluginLoaded( Kopete::Plugin *plugin );
 159
 160         /**
 161          * @brief Signals a plugin has just been unloaded.
 162          */
 163         void pluginUnloaded( const QString &pluginName );
 164
 165         /**
 166          * @brief All plugins have been loaded by the plugin manager.
 167          *
 168          * This signal is emitted exactly ONCE, when the plugin manager has emptied
 169          * its plugin queue for the first time. This means that if you call an async
 170          * loadPlugin() before loadAllPlugins() this signal is probably emitted after
 171          * the initial call completes, unless you are quick enough to fill the queue
 172          * before it completes, which is a dangerous race you shouldn't count upon :)
 173          *
 174          * The signal is delayed one event loop iteration through a singleShot timer,
 175          * but that is not guaranteed to be enough for account instantiation. You may
 176          * need an additional timer for it in the code if you want to programmatically
 177          * act on it.
 178          *
 179          * If you use the signal for enabling/disabling GUI objects there is little
 180          * chance a user is able to activate them in the short while that's remaining,
 181          * the slow part of the code is over now and the remaining processing time
 182          * is neglectable for the user.
 183          */
 184         void allPluginsLoaded();
 185
 186 private slots:
 187         /**
 188          * @brief Cleans up some references if the plugin is destroyed
 189          */
 190         void slotPluginDestroyed( QObject *plugin );
 191
 192         /**
 193          * shutdown() starts a timer, when it fires we force all plugins
 194          * to be unloaded here by deref()-ing the event loop to trigger the plugin
 195          * manager's destruction
 196          */
 197         void slotShutdownTimeout();
 198
 199         /**
 200          * Common entry point to deref() the KApplication. Used both by the clean
 201          * shutdown and the timeout condition of slotShutdownTimeout()
 202          */
 203         void slotShutdownDone();
 204
 205         /**
 206          * Emitted by a Kopete::Plugin when it's ready for unload
 207          */
 208         void slotPluginReadyForUnload();
 209
 210         /**
 211          * Load a plugin from our queue. Does nothing if the queue is empty.
 212          * Schedules itself again if more plugins are pending.
 213          */
 214         void slotLoadNextPlugin();
 215
 216 private:
 217         /**
 218          * @internal
 219          *
 220          * The internal method for loading plugins.
 221          * Called by @ref loadPlugin directly or through the queue for async plugin
 222          * loading.
 223          */
 224         Plugin * loadPluginInternal( const QString &pluginId );
 225
 226         /**
 227          * @internal
 228          *
 229          * Find the KPluginInfo structure by key. Reduces some code duplication.
 230          *
 231          * Returns a null pointer when no plugin info is found.
 232          */
 233         KPluginInfo infoForPluginId( const QString &pluginId ) const;
 234
 235         PluginManager();
 236         ~PluginManager();
 237
 238 };
 239
 240 }
 241
 242 #endif // KOPETEPLUGINMANAGER_H
 243
 244 // vim: set noet ts=4 sts=4 sw=4: