1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
/*
This file is part of the KDE libraries
Copyright (c) 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
Copyright (c) 1999 Preston Brown <pbrown@kde.org>
Portions copyright (c) 1997 Matthias Kalle Dalheimer <kalle@kde.org>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
#ifndef KCONFIGBACKEND_H
#define KCONFIGBACKEND_H
#include <QtCore/QObject>
#include <QtCore/QString>
#include <QExplicitlySharedDataPointer>
#include <kconfigcore_export.h>
#include <kconfigbase.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 */
virtual ~KConfigBackend();
/** 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
|
