workspace/libs/plasma/dataenginemanager.h

   1 /*
   2  *   Copyright 2006-2007 Aaron Seigo <aseigo@kde.org>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU Library General Public License as
   6  *   published by the Free Software Foundation; either version 2, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program is distributed in the hope that it will be useful,
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *   GNU General Public License for more details
  13  *
  14  *   You should have received a copy of the GNU Library General Public
  15  *   License along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  */
  19
  20 #ifndef PLASMA_DATAENGINEMANAGER_H
  21 #define PLASMA_DATAENGINEMANAGER_H
  22
  23 #include <QtCore/QHash>
  24 #include <plasma/dataengine.h>
  25
  26 namespace Plasma
  27 {
  28
  29 /**
  30  * @brief DataEngine loader and life time manager
  31  *
  32  * Plasma::DataEngineManager provides facilities for listing, loading and
  33  * according to reference count unloading of DataEngines.
  34  **/
  35 class PLASMA_EXPORT DataEngineManager: public QObject
  36 {
  37     Q_OBJECT
  38     public:
  39         /**
  40          * Singleton pattern accessor.
  41          */
  42         static DataEngineManager* self();
  43
  44         /**
  45          * Default constructor. Usually the singleton method self() is the
  46          * preferred access mechanism.
  47          */
  48         DataEngineManager();
  49         ~DataEngineManager();
  50
  51         /**
  52          * Returns a data engine object if one is loaded and available.
  53          * On failure, the fallback NullEngine (which does nothing and
  54          * !isValid()) is returned.
  55          *
  56          * @param name the name of the engine
  57          */
  58         Plasma::DataEngine* get(const QString& name) const;
  59
  60         /**
  61          * Loads a data engine and increases the reference count on it.
  62          * This should be called once per object (or set of objects) using the
  63          * DataEngine. Afterwards, dataEngine should be used or the return
  64          * value cached. Call unloadDataEngine when finished with the engine.
  65          *
  66          * @param name the name of the engine
  67          * @return the data engine that was loaded, or the NullEngine on failure.
  68          */
  69         Plasma::DataEngine* load(const QString& name);
  70
  71         /**
  72          * Decreases the reference count on the engine. If the count reaches
  73          * zero, then the engine is deleted to save resources.
  74          */
  75         void unload(const QString& name);
  76
  77         /**
  78          * Returns a listing of all known engines by name
  79          */
  80         static QStringList knownEngines();
  81
  82     private:
  83         class Private;
  84         Private* const d;
  85 };
  86
  87 } // namespace Plasma
  88
  89 #endif // multiple inclusion guard