kdecore/config/kconfigbackend.h

   1 /*
   2    This file is part of the KDE libraries
   3    Copyright (c) 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
   4    Copyright (c) 1999 Preston Brown <pbrown@kde.org>
   5    Portions copyright (c) 1997 Matthias Kalle Dalheimer <kalle@kde.org>
   6
   7    This library is free software; you can redistribute it and/or
   8    modify it under the terms of the GNU Library General Public
   9    License as published by the Free Software Foundation; either
  10    version 2 of the License, or (at your option) any later version.
  11
  12    This library is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15    Library General Public License for more details.
  16
  17    You should have received a copy of the GNU Library General Public License
  18    along with this library; see the file COPYING.LIB.  If not, write to
  19    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20    Boston, MA 02110-1301, USA.
  21 */
  22
  23 #ifndef KCONFIGBACKEND_H
  24 #define KCONFIGBACKEND_H
  25
  26 #include <QtCore/QObject>
  27 #include <QtCore/QString>
  28
  29 #include <kdecore_export.h>
  30 #include <kconfigbase.h>
  31 #include <kgenericfactory.h>
  32 #include <ksharedptr.h>
  33
  34 class KEntryMap;
  35 class KComponentData;
  36 class QFile;
  37 class QByteArray;
  38 class QDateTime;
  39
  40 /**
  41  * \class KConfigBackend kconfigbackend.h <KConfigBackend>
  42  *
  43  * Provides the implementation for accessing configuration sources.
  44  *
  45  * KDELibs only provides an INI backend, but this class can be used
  46  * to create plugins that allow access to other file formats and
  47  * configuration systems.
  48  */
  49 class KDECORE_EXPORT KConfigBackend : public QObject, public KShared
  50 {
  51     Q_OBJECT
  52     Q_FLAGS(ParseOption)
  53     Q_FLAGS(WriteOption)
  54
  55 public:
  56     /**
  57      * Creates a new KConfig backend.
  58      *
  59      * If no @p system is given, or the given @p system is unknown, this method tries
  60      * to determine the correct backend to use.
  61      *
  62      * @param componentData the owning component
  63      * @param fileName      the absolute file name of the configuration file
  64      * @param system        the configuration system to use
  65      * @return a KConfigBackend object to be used with KConfig
  66      */
  67     static KSharedPtr<KConfigBackend> create(const KComponentData& componentData,
  68                                              const QString& fileName = QString(),
  69                                              const QString& system = QString());
  70
  71     /**
  72      * Registers mappings from directories/files to configuration systems
  73      *
  74      * Allows you to tell KConfigBackend that create() should use a particular
  75      * backend for a particular file or directory.
  76      *
  77      * @warning currently does nothing
  78      *
  79      * @param entryMap the KEntryMap to build the mappings from
  80      */
  81     static void registerMappings(const KEntryMap& entryMap);
  82
  83     /** Destroys the backend */
  84     virtual ~KConfigBackend();
  85
  86     /** Allows the behaviour of parseConfig() to be tuned */
  87     enum ParseOption {
  88         ParseGlobal = 1, /// entries should be marked as @em global
  89         ParseDefaults = 2, /// entries should be marked as @em default
  90         ParseExpansions = 4 /// entries are allowed to be marked as @em expandable
  91     };
  92     /// @typedef typedef QFlags<ParseOption> ParseOptions
  93     Q_DECLARE_FLAGS(ParseOptions, ParseOption)
  94
  95     /** Allows the behaviour of writeConfig() to be tuned */
  96     enum WriteOption {
  97         WriteGlobal = 1 /// only write entries marked as "global"
  98     };
  99     /// @typedef typedef QFlags<WriteOption> WriteOptions
 100     Q_DECLARE_FLAGS(WriteOptions, WriteOption)
 101
 102     /** Return value from parseConfig() */
 103     enum ParseInfo {
 104         ParseOk, /// the configuration was opened read/write
 105         ParseImmutable, /// the configuration is @em immutable
 106         ParseOpenError /// the configuration could not be opened
 107     };
 108
 109     /**
 110      * Read persistent storage
 111      *
 112      * @param locale the locale to read entries for (if the backend supports localized entries)
 113      * @param pWriteBackMap the KEntryMap where the entries are placed
 114      * @param options @see ParseOptions
 115      * @return @see ParseInfo
 116      */
 117     virtual ParseInfo parseConfig(const QByteArray& locale,
 118                                   KEntryMap& pWriteBackMap,
 119                                   ParseOptions options = ParseOptions()) = 0;
 120
 121     /**
 122      * Write the @em dirty entries to permanent storage
 123      *
 124      * @param locale the locale to write entries for (if the backend supports localized entries)
 125      * @param entryMap the KEntryMap containing the config object's entries.
 126      * @param options @see WriteOptions
 127      * @param data the component that requested the write
 128      *
 129      * @return @c true if the write was successful, @c false if writing the configuration failed
 130      */
 131     virtual bool writeConfig(const QByteArray& locale, KEntryMap& entryMap,
 132                              WriteOptions options, const KComponentData &data) = 0;
 133
 134     /**
 135      * If isWritable() returns false, writeConfig() will always fail.
 136      *
 137      * @return @c true if the configuration is writable, @c false if it is immutable
 138      */
 139     virtual bool isWritable() const = 0;
 140     /**
 141      * When isWritable() returns @c false, return an error message to
 142      * explain to the user why saving configuration will not work.
 143      *
 144      * The return value when isWritable() returns @c true is undefined.
 145      *
 146      * @returns a translated user-visible explanation for the configuration
 147      *          object not being writable
 148      */
 149     virtual QString nonWritableErrorMessage() const = 0;
 150     /**
 151      * @return the read/write status of the configuration object
 152      *
 153      * @see KConfigBase::AccessMode
 154      */
 155     virtual KConfigBase::AccessMode accessMode() const = 0;
 156     /**
 157      * Create the enclosing object of the configuration object
 158      *
 159      * For example, if the configuration object is a file, this should create
 160      * the parent directory.
 161      */
 162     virtual void createEnclosing() = 0;
 163
 164     /**
 165      * Set the file path.
 166      *
 167      * @note @p path @b MUST be @em absolute.
 168      *
 169      * @param path the absolute file path
 170      */
 171     virtual void setFilePath(const QString& path) = 0;
 172
 173     /**
 174      * Lock the file
 175      */
 176     virtual bool lock(const KComponentData& componentData) = 0;
 177     /**
 178      * Release the lock on the file
 179      */
 180     virtual void unlock() = 0;
 181     /**
 182      * @return @c true if the file is locked, @c false if it is not locked
 183      */
 184     virtual bool isLocked() const = 0;
 185
 186     /**
 187      * @return the date and time when the object was last modified
 188      */
 189     QDateTime lastModified() const;
 190     /** @return the absolute path to the object */
 191     QString filePath() const;
 192     /** @return the size of the object */
 193     qint64 size() const;
 194
 195 protected:
 196     KConfigBackend();
 197     void setLastModified(const QDateTime& dt);
 198     void setSize(qint64 sz);
 199     void setLocalFilePath(const QString& file);
 200
 201 private:
 202     class Private;
 203     Private *const d;
 204 };
 205
 206 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBackend::ParseOptions)
 207 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBackend::WriteOptions)
 208
 209 /**
 210  * Register a KConfig backend when it is contained in a loadable module
 211  */
 212 #define K_EXPORT_KCONFIGBACKEND(libname, classname) \
 213 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
 214 K_EXPORT_PLUGIN(factory("kconfigbackend_" #libname))
 215
 216
 217 #endif // KCONFIGBACKEND_H