File indexing completed on 2024-04-28 03:53:15

 /*
     This file is part of the KDE libraries
     SPDX-FileCopyrightText: 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
     SPDX-FileCopyrightText: 1999 Preston Brown <pbrown@kde.org>
     SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KCONFIGBACKEND_H
 #define KCONFIGBACKEND_H
 
 #include <QExplicitlySharedDataPointer>
 #include <QObject>
 #include <QString>
 
 #include <kconfigbase.h>
 #include <kconfigcore_export.h>
 class KConfigBackendPrivate;
 
 class KEntryMap;
 class QFile;
 class QByteArray;
 
 /**
  * \class KConfigBackend kconfigbackend_p.h <KConfigBackend>
  *
  * Provides the implementation for accessing configuration sources.
  *
  * KConfig only provides an INI backend, but this class can be used
  * to create plugins that allow access to other file formats and
  * configuration systems.
  *
  * \internal
  */
 class KConfigBackend : public QObject, public QSharedData
 {
     Q_OBJECT
 
 public:
     /**
      * Creates a new KConfig backend.
      *
      * If no @p system is given, or the given @p system is unknown, this method tries
      * to determine the correct backend to use.
      *
      * @param fileName      the absolute file name of the configuration file
      * @param system        the configuration system to use
      * @return a KConfigBackend object to be used with KConfig
      */
     static QExplicitlySharedDataPointer<KConfigBackend> create(const QString &fileName = QString(), const QString &system = QString());
 
     /**
      * Registers mappings from directories/files to configuration systems
      *
      * Allows you to tell KConfigBackend that create() should use a particular
      * backend for a particular file or directory.
      *
      * @warning currently does nothing
      *
      * @param entryMap the KEntryMap to build the mappings from
      */
     static void registerMappings(const KEntryMap &entryMap);
 
     /** Destroys the backend */
     ~KConfigBackend() override;
 
     /** Allows the behaviour of parseConfig() to be tuned */
     enum ParseOption {
         ParseGlobal = 1, /// entries should be marked as @em global
         ParseDefaults = 2, /// entries should be marked as @em default
         ParseExpansions = 4, /// entries are allowed to be marked as @em expandable
     };
     Q_FLAG(ParseOption)
     /// @typedef typedef QFlags<ParseOption> ParseOptions
     Q_DECLARE_FLAGS(ParseOptions, ParseOption)
 
     /** Allows the behaviour of writeConfig() to be tuned */
     enum WriteOption {
         WriteGlobal = 1 /// only write entries marked as "global"
     };
     Q_FLAG(WriteOption)
     /// @typedef typedef QFlags<WriteOption> WriteOptions
     Q_DECLARE_FLAGS(WriteOptions, WriteOption)
 
     /** Return value from parseConfig() */
     enum ParseInfo {
         ParseOk, /// the configuration was opened read/write
         ParseImmutable, /// the configuration is @em immutable
         ParseOpenError, /// the configuration could not be opened
     };
 
     /**
      * Read persistent storage
      *
      * @param locale the locale to read entries for (if the backend supports localized entries)
      * @param pWriteBackMap the KEntryMap where the entries are placed
      * @param options See ParseOptions
      * @return See ParseInfo
      */
     virtual ParseInfo parseConfig(const QByteArray &locale, KEntryMap &pWriteBackMap, ParseOptions options = ParseOptions()) = 0;
 
     /**
      * Write the @em dirty entries to permanent storage
      *
      * @param locale the locale to write entries for (if the backend supports localized entries)
      * @param entryMap the KEntryMap containing the config object's entries.
      * @param options See WriteOptions
      *
      * @return @c true if the write was successful, @c false if writing the configuration failed
      */
     virtual bool writeConfig(const QByteArray &locale, KEntryMap &entryMap, WriteOptions options) = 0;
 
     /**
      * If isWritable() returns false, writeConfig() will always fail.
      *
      * @return @c true if the configuration is writable, @c false if it is immutable
      */
     virtual bool isWritable() const = 0;
     /**
      * When isWritable() returns @c false, return an error message to
      * explain to the user why saving configuration will not work.
      *
      * The return value when isWritable() returns @c true is undefined.
      *
      * @returns a translated user-visible explanation for the configuration
      *          object not being writable
      */
     virtual QString nonWritableErrorMessage() const = 0;
     /**
      * @return the read/write status of the configuration object
      *
      * @see KConfigBase::AccessMode
      */
     virtual KConfigBase::AccessMode accessMode() const = 0;
     /**
      * Create the enclosing object of the configuration object
      *
      * For example, if the configuration object is a file, this should create
      * the parent directory.
      */
     virtual void createEnclosing() = 0;
 
     /**
      * Set the file path.
      *
      * @note @p path @b MUST be @em absolute.
      *
      * @param path the absolute file path
      */
     virtual void setFilePath(const QString &path) = 0;
 
     /**
      * Lock the file
      */
     virtual bool lock() = 0;
     /**
      * Release the lock on the file
      */
     virtual void unlock() = 0;
     /**
      * @return @c true if the file is locked, @c false if it is not locked
      */
     virtual bool isLocked() const = 0;
 
     /** @return the absolute path to the object */
     QString filePath() const;
 
 protected:
     KConfigBackend();
     void setLocalFilePath(const QString &file);
 
 private:
     KConfigBackendPrivate *const d;
 };
 
 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBackend::ParseOptions)
 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBackend::WriteOptions)
 
 #if 0 // TODO re-enable if the plugin loading code is re-enabled
 /**
  * Register a KConfig backend when it is contained in a loadable module
  */
 #define K_EXPORT_KCONFIGBACKEND(libname, classname) K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
 #endif
 
 #endif // KCONFIGBACKEND_H