1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
4 SPDX-FileCopyrightText: 1999 Preston Brown <pbrown@kde.org>
5 SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#ifndef KCONFIGBACKEND_H
11#define KCONFIGBACKEND_H
12
13#include <QExplicitlySharedDataPointer>
14#include <QObject>
15#include <QString>
16
17#include <kconfigbase.h>
18#include <kconfigcore_export.h>
19class KConfigBackendPrivate;
20
21class KEntryMap;
22class QFile;
23class QByteArray;
24
25/**
26 * \class KConfigBackend kconfigbackend_p.h <KConfigBackend>
27 *
28 * Provides the implementation for accessing configuration sources.
29 *
30 * KConfig only provides an INI backend, but this class can be used
31 * to create plugins that allow access to other file formats and
32 * configuration systems.
33 *
34 * \internal
35 */
36class KConfigBackend : public QObject, public QSharedData
37{
38 Q_OBJECT
39
40public:
41 /**
42 * Creates a new KConfig backend.
43 *
44 * If no @p system is given, or the given @p system is unknown, this method tries
45 * to determine the correct backend to use.
46 *
47 * @param fileName the absolute file name of the configuration file
48 * @param system the configuration system to use
49 * @return a KConfigBackend object to be used with KConfig
50 */
51 static QExplicitlySharedDataPointer<KConfigBackend> create(const QString &fileName = QString(), const QString &system = QString());
52
53 /**
54 * Registers mappings from directories/files to configuration systems
55 *
56 * Allows you to tell KConfigBackend that create() should use a particular
57 * backend for a particular file or directory.
58 *
59 * @warning currently does nothing
60 *
61 * @param entryMap the KEntryMap to build the mappings from
62 */
63 static void registerMappings(const KEntryMap &entryMap);
64
65 /** Destroys the backend */
66 ~KConfigBackend() override;
67
68 /** Allows the behaviour of parseConfig() to be tuned */
69 enum ParseOption {
70 ParseGlobal = 1, /// entries should be marked as @em global
71 ParseDefaults = 2, /// entries should be marked as @em default
72 ParseExpansions = 4, /// entries are allowed to be marked as @em expandable
73 };
74 Q_FLAG(ParseOption)
75 /// @typedef typedef QFlags<ParseOption> ParseOptions
76 Q_DECLARE_FLAGS(ParseOptions, ParseOption)
77
78 /** Allows the behaviour of writeConfig() to be tuned */
79 enum WriteOption {
80 WriteGlobal = 1 /// only write entries marked as "global"
81 };
82 Q_FLAG(WriteOption)
83 /// @typedef typedef QFlags<WriteOption> WriteOptions
84 Q_DECLARE_FLAGS(WriteOptions, WriteOption)
85
86 /** Return value from parseConfig() */
87 enum ParseInfo {
88 ParseOk, /// the configuration was opened read/write
89 ParseImmutable, /// the configuration is @em immutable
90 ParseOpenError, /// the configuration could not be opened
91 };
92
93 /**
94 * Read persistent storage
95 *
96 * @param locale the locale to read entries for (if the backend supports localized entries)
97 * @param pWriteBackMap the KEntryMap where the entries are placed
98 * @param options See ParseOptions
99 * @return See ParseInfo
100 */
101 virtual ParseInfo parseConfig(const QByteArray &locale, KEntryMap &pWriteBackMap, ParseOptions options = ParseOptions()) = 0;
102
103 /**
104 * Write the @em dirty entries to permanent storage
105 *
106 * @param locale the locale to write entries for (if the backend supports localized entries)
107 * @param entryMap the KEntryMap containing the config object's entries.
108 * @param options See WriteOptions
109 *
110 * @return @c true if the write was successful, @c false if writing the configuration failed
111 */
112 virtual bool writeConfig(const QByteArray &locale, KEntryMap &entryMap, WriteOptions options) = 0;
113
114 /**
115 * If isWritable() returns false, writeConfig() will always fail.
116 *
117 * @return @c true if the configuration is writable, @c false if it is immutable
118 */
119 virtual bool isWritable() const = 0;
120 /**
121 * When isWritable() returns @c false, return an error message to
122 * explain to the user why saving configuration will not work.
123 *
124 * The return value when isWritable() returns @c true is undefined.
125 *
126 * @returns a translated user-visible explanation for the configuration
127 * object not being writable
128 */
129 virtual QString nonWritableErrorMessage() const = 0;
130 /**
131 * @return the read/write status of the configuration object
132 *
133 * @see KConfigBase::AccessMode
134 */
135 virtual KConfigBase::AccessMode accessMode() const = 0;
136 /**
137 * Create the enclosing object of the configuration object
138 *
139 * For example, if the configuration object is a file, this should create
140 * the parent directory.
141 */
142 virtual void createEnclosing() = 0;
143
144 /**
145 * Set the file path.
146 *
147 * @note @p path @b MUST be @em absolute.
148 *
149 * @param path the absolute file path
150 */
151 virtual void setFilePath(const QString &path) = 0;
152
153 /**
154 * Lock the file
155 */
156 virtual bool lock() = 0;
157 /**
158 * Release the lock on the file
159 */
160 virtual void unlock() = 0;
161 /**
162 * @return @c true if the file is locked, @c false if it is not locked
163 */
164 virtual bool isLocked() const = 0;
165
166 /** @return the absolute path to the object */
167 QString filePath() const;
168
169protected:
170 KConfigBackend();
171 void setLocalFilePath(const QString &file);
172
173private:
174 KConfigBackendPrivate *const d;
175};
176
177Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBackend::ParseOptions)
178Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBackend::WriteOptions)
179
180#if 0 // TODO re-enable if the plugin loading code is re-enabled
181/**
182 * Register a KConfig backend when it is contained in a loadable module
183 */
184#define K_EXPORT_KCONFIGBACKEND(libname, classname) K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
185#endif
186
187#endif // KCONFIGBACKEND_H
188

source code of kconfig/src/core/kconfigbackend_p.h