Debian Codegraph @

docs/global/dconfigfile.zh_CN.dox

raw
1 /*!
2 @~chinese
3 @file include/global/dconfigfile.h
4 @ingroup dglobal
5
6 @class Dtk::Core::DConfigFile dconfigfile.h
7 @brief 规范配置文件读写的相关接口的配置文件实现
8 @details
9 ## 概述
10
11 规范配置文件读写的相关接口的配置文件实现
12
13 项目目录结构如下:
14 ```bash
15 ├── CMakeLists.txt
16 ├── config
17 │ └── example.json
18 └── main.cpp
19 ```
20
21 ## CMakeLists.txt
22 ```cmake
23 cmake_minimum_required(VERSION 3.1.0) # 指定cmake最低版本
24
25 project(dconfigfile-example VERSION 1.0.0 LANGUAGES CXX) # 指定项目名称, 版本, 语言 cxx就是c++
26
27 set(CMAKE_CXX_STANDARD 11) # 指定c++标准
28 set(CMAKE_CXX_STANDARD_REQUIRED ON) # 指定c++标准要求,至少为11以上
29
30 set(CMAKE_AUTOMOC ON) # 支持qt moc
31 set(CMAKE_AUTORCC ON) # 支持qt资源文件
32 set(CMAKE_AUTOUIC ON) # 支持qt ui文件(非必须)
33
34 set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # 支持 clangd
35
36 if (CMAKE_VERSION VERSION_LESS "3.7.0") # 如果cmake版本小于3.7.0
37 set(CMAKE_INCLUDE_CURRENT_DIR ON) # 设置包含当前目录
38 endif()
39
40 find_package(Qt5 REQUIRED COMPONENTS Core) # 寻找Qt5组件Core
41 find_package(Dtk REQUIRED COMPONENTS Core) # 寻找Dtk组件Core
42
43 add_executable(${PROJECT_NAME} # 生成可执行文件
44 main.cpp
45 )
46
47 target_link_libraries(${PROJECT_NAME} PRIVATE # 添加需要链接的共享库
48 Qt5::Core
49 dtkcore
50 )
51
52 # dtk_add_config_meta_files函数,部署一些"meta"的配置。
53 # 函数定义在dtkcore的cmake目录下
54 # APPID 应用的ID
55 # FILES 需要部署的文件。
56 dtk_add_config_meta_files(
57 APPID ${PROJECT_NAME}
58 FILES ./config/example.json
59 )
60 ```
61
62 ## example.json
63 ```json
64 {
65 "magic": "dsg.config.meta",
66 "version": "1.0",
67 "contents": {
68 "canExit": {
69 "value": true,
70 "serial": 0,
71 "flags": ["global"],
72 "name": "I am name",
73 "name[zh_CN]": "我是名字",
74 "description": "I am description",
75 "permissions": "readwrite",
76 "visibility": "private"
77 },
78 "key1": {
79 "value": "125",
80 "serial": 0,
81 "flags": ["nooverride"],
82 "name": "I am name",
83 "name[zh_CN]": "我是名字",
84 "description": "I am description",
85 "permissions": "readwrite",
86 "visibility": "public"
87 },
88 "number": {
89 "value": 1,
90 "serial": 0,
91 "flags": ["global"],
92 "name": "array value type",
93 "permissions": "readwrite",
94 "visibility": "public"
95 },
96 "array": {
97 "value": ["value1", "value2"],
98 "serial": 0,
99 "flags": ["global"],
100 "name": "array",
101 "permissions": "readwrite",
102 "visibility": "public"
103 },
104 "map": {
105 "value": {"key1": "value1", "key2": "value2"},
106 "serial": 0,
107 "flags": ["nooverride"],
108 "name": "map",
109 "permissions": "readwrite",
110 "visibility": "public"
111 },
112 "publicConfig": {
113 "value": true,
114 "serial": 0,
115 "flags": ["user-public"],
116 "name": "public configure",
117 "name[zh_CN]": "我是公开的配置",
118 "description": "I am public configure",
119 "permissions": "readwrite",
120 "visibility": "private"
121 }
122 }
123 }
124 ```
125
126 ## main.cpp
127 ```cpp
128 #include <DConfigFile>
129 #include <QDebug>
130 #include <QCoreApplication>
131 #include <unistd.h>
132
133 DCORE_USE_NAMESPACE
134
135 int main(int argc, char *argv[])
136 {
137 QCoreApplication a(argc, argv);
138
139 // 构造DConfigFile,元数据文件名example,与元数据安装目录的/usr/share/dsg/configs/APPID名(可执行文件名)对应目录/example.json,
140 DConfigFile configFile("dconfigfile-example","example");
141 // 解析配置文件
142 configFile.load();
143
144 // 创建用户缓存
145 QScopedPointer<DConfigCache> userCache(configFile.createUserCache(getuid()));
146 // 解析配置文件
147 userCache->load();
148
149 // 判断是否有效
150 if (!configFile.isValid()) {
151 qWarning() << QString("DConfig无效.");
152 return 0;
153 }
154
155 // meta 返回原型对象, keyList获取所有配置项的key
156 qDebug() << "所有的所有配置项的key:" << configFile.meta()->keyList();
157
158 // 获取指定配置项的值,配置项可以是字符串,数组,map容器,布尔值,整型,详见example.json
159 qDebug() << "canExit对应的值:" << configFile.value("canExit").toBool();
160
161 // 配置项的可见性,其余配置项标记、配置项的权限可查看文档
162 qDebug() << "配置项的可见性" << configFile.meta()->visibility("canExit");
163
164 QVariantMap map;
165 map.insert("k1","v1");
166 map.insert("k2","v2");
167 // 设置map的值
168 configFile.setValue("map", map, "dconfigfile-example", userCache.get());
169
170 configFile.save();
171
172 // root用户运行,save的数据会保存到/root/.config/dsg/configs-fake-global/dconfigfile-example/example.json
173 // map数据对应的flags标记为NoOverride,配置项允许被覆盖,如果flags为global泽忽略用户身份,详见文档。
174 userCache->save();
175
176 return a.exec();
177 }
178 ```
179
180 ## 从源码构建
181 ```bash
182 mkdir build && cd build
183 # 修改路径前缀为/usr,GNU标准的默认值为/usr/local
184 cmake .. -DCMAKE_INSTALL_PREFIX=/usr
185 sudo make install
186 sudo ./dconfigfile-example
187 ```
188
189 结果如下图
190
191 ![一些简单的输出](/docs/src/dconfigfile_example1.png)
192
193 ![用户保存的数据](/docs/src/dconfigfile_example2.png)
194
195 @enum Dtk::Core::DConfigFile::Flag
196 @brief 配置项名称
197 @var Dtk::Core::DConfigFile::Flag Dtk::Core::DConfigFile::NoOverride
198 @brief 存在此标记时,将表明则此配置项不可被覆盖(详见下述 override 机制)。反之,不存在此标记时表明此配置项允许被覆盖,对于此类配置项,如若其有界面设置入口,则当此项不可写时,应当隐藏或禁用界面的设置入口.
199 @var Dtk::Core::DConfigFile::Flag Dtk::Core::DConfigFile::Global
200 @brief 当读写此类配置时,将忽略用户身份,无论程序使用哪个用户身份执行,读操作都将获取到同样的数据,写操作将对所有用户都生效。但是,如果对应的配置存储目录不存在或无权限写入,则忽略此标志
201 @var Dtk::Core::DConfigFile::Flag Dtk::Core::DConfigFile::UserPublic
202 @brief 该类配置项允许被其他用户访问
203
204
205 @enum Dtk::Core::DConfigFile::Permissions
206 @brief 配置项的权限
207 @var Dtk::Core::DConfigFile::Permissions Dtk::Core::DConfigFile::ReadOnly
208 @brief 将配置项覆盖为只读
209 @var Dtk::Core::DConfigFile::Permissions Dtk::Core::DConfigFile::ReadWrite
210 @brief 将配置项覆盖为可读可写
211
212
213 @enum Dtk::Core::DConfigFile::Visibility
214 @brief 配置项的可见性
215 @var Dtk::Core::DConfigFile::Visibility Dtk::Core::DConfigFile::Private
216 @brief 仅限程序内部使用,对外不可见。此类配置项完全由程序自己读写,可随意增删改写其含义,无需做兼容性考虑
217 @var Dtk::Core::DConfigFile::Visibility Dtk::Core::DConfigFile::Public
218 @brief 外部程序可使用。 此类配置项一旦发布,在兼容性版本的升级中,要保障此配置项向下兼容,简而言之,只允许在程序/库的大版本升级时才允许删除或修改此类配置项,当配置项的 permissions、visibility、flags 任意一个属性被修改则认为此配置项被修改,除此之外修改 value、name、description 属性时则不需要考虑兼容性。
219
220 @struct Dtk::Core::DConfigFile::Version
221 @brief 版本信息
222 @details
223 此文件的内容格式的版本。版本号使用两位数字描述,
224 首位数字不同的描述文件相互之间不兼容,第二位数字不同的描述文件需满足向下兼容。
225 读取此描述文件的程序要根据版本进行内容分析,当遇到不兼容的版本时,需要立即终止解析,忽略此文件,
226 并在程序日志中写入警告信息,如 “1.0” 和 “2.0” 版本之间不兼容,
227 如果解析程序最高只支持 1.0 版本,则遇到 2.0 版本的描述文件时应该终止解析,
228 但是如果遇到 1.1 版本,则可以继续执行。
229 写入此描述文件时,遇到不兼容的版本时,需要先清空当前内容再写入,每次写入皆需更新此字段。
230
231 @fn static constexpr DConfigFile::Version Dtk::Core::DConfigFile::supportedVersion()
232 @brief 支持的版本
233 @return
234
235 @fn Dtk::Core::DConfigFile::DConfigFile(const QString &appId, const QString &name, const QString &subpath = QString())
236 @brief DConfigFile构造函数,构造配置文件管理对象。
237 @param[in] appId 应用程序唯一标识
238 @param[in] name 配置文件名
239 @param[in] subpath 子目录
240
241 @fn Dtk::Core::DConfigFile::DConfigFile(const DConfigFile &other);
242 @brief DConfigFile构造函数,构造配置文件管理对象。
243 @param[in] appId 应用程序唯一标识
244 @param[in] name 配置文件名
245 @param[in] subpath 子目录
246
247 @fn bool Dtk::Core::DConfigFile::load(const QString &localPrefix = QString())
248 @brief 解析配置文件
249 @param[in] localPrefix 为目录前缀
250 @return
251
252 @fn bool Dtk::Core::DConfigFile::load(QIODevice *meta, const QList<QIODevice*> &overrides)
253 @brief 解析配置文件流
254 @param[in] meta 为原型流
255 @param[in] overrides 为覆盖机制查找的文件流
256 @return
257
258 @fn bool Dtk::Core::DConfigFile::save(const QString &localPrefix = QString(), QJsonDocument::JsonFormat format = QJsonDocument::Indented, bool sync = false) const
259 @brief 保存缓存的值到磁盘中
260 @param[in] format 保存格式
261 @param[in] sync 是否立即刷新
262 @return
263
264 @fn bool Dtk::Core::DConfigFile::isValid() const
265 @brief 检测配置文件是否有效
266 @return
267
268 @fn QVariant Dtk::Core::DConfigFile::value(const QString &key, DConfigCache *userCache = nullptr) const
269 @brief DConfigFile::value
270 @param[in] key 配置项名称
271 @param[in] userCache 用户缓存,当key为全局项时, \a userCache 不会被使用
272 @return
273
274 @fn QVariant Dtk::Core::DConfigFile::cacheValue(DConfigCache *userCache, const QString &key) const
275 @brief DConfigFile::cacheValue 获取指定用户缓存的配置项值,若无此配置项的用户缓存值,返回无效值
276 @param[in] key 配置项名称
277 @param[in] userCache 用户缓存,当key为全局配置项时, \a userCache 不会被使用
278 @return
279
280 @fn bool Dtk::Core::DConfigFile::setValue(const QString &key, const QVariant &value, const QString &callerAppid, DConfigCache *userCache = nullptr)
281 @brief 设置缓存中的值
282 @param[in] key 配置项名称
283 @param[in] value 需要设置的值
284 @param[in] uid 设置时的用户id
285 @param[in] appid 设置时的应用id
286 @return 为true时表示重新设置了新值,false表示没有设置
287
288 @fn DConfigCache* Dtk::Core::DConfigFile::createUserCache(const uint uid)
289 @brief 创建用户缓存
290
291 @fn DConfigCache* Dtk::Core::DConfigFile::globalCache() const
292 @brief 返回全局缓存
293 @return
294
295 @fn DConfigMeta* Dtk::Core::DConfigFile::meta()
296 @brief 返回原型对象
297 @return
298
299 */
300
301 /*!
302 @class Dtk::Core::DConfigMeta dconfigfile.h
303 @brief 提供配置文件的原型和覆盖机制的访问接口
304
305 @fn virtual DConfigFile::Version Dtk::Core::DConfigMeta::version() const = 0
306 @brief 返回配置版本信息
307 @return
308
309 @fn virtual void Dtk::Core::DConfigMeta::setVersion(quint16 major, quint16 minor) = 0
310 @brief 设置配置版本信息
311 @param[in] major 主板本号
312 @param[in] minor 次版本号
313
314 @fn virtual bool Dtk::Core::DConfigMeta::load(const QString &localPrefix = QString()) = 0
315 @brief 解析配置文件
316 @param[in] localPrefix 为目录前缀
317 @return
318
319 @fn virtual bool Dtk::Core::DConfigMeta::load(QIODevice *meta, const QList<QIODevice*> &overrides) = 0
320 @brief 解析配置文件流
321 @param[in] meta 为原型流
322 @param[in] overrides 为覆盖机制查找的文件流
323 @return
324
325 @fn virtual QStringList Dtk::Core::DConfigMeta::keyList() const = 0
326 @brief 返回配置内容的所有配置项
327 @return
328
329 @fn virtual DConfigFile::Flags Dtk::Core::DConfigMeta::flags(const QString &key) const = 0
330 @brief 返回指定配置项的特性
331 @param[in] key 配置项名称, NoOverride为此配置项不可被覆盖, Global为忽略用户身份
332 @return
333
334 @fn virtual DConfigFile::Permissions Dtk::Core::DConfigMeta::permissions(const QString &key) const = 0
335 @brief 返回指定配置项的权限
336 @param[in] key 配置项名称
337 @return
338
339 @fn virtual DConfigFile::Visibility Dtk::Core::DConfigMeta::visibility(const QString &key) const = 0
340 @brief 返回指定配置项的可见性
341 @param[in] key 配置项名称
342 @return
343
344 @fn virtual int Dtk::Core::DConfigMeta::serial(const QString &key) const = 0
345 @brief 返回配置项的单调递增值
346 @param[in] key 配置项名称
347 @return -1为无效值,表明没有配置此项
348
349 @fn virtual QString Dtk::Core::DConfigMeta::displayName(const QString &key, const QLocale &locale) = 0
350 @brief 返回指定配置项的显示名
351 @param[in] key 配置项名称
352 @param[in] locale 为语言版本
353 @return
354
355 @fn virtual QString Dtk::Core::DConfigMeta::description(const QString &key, const QLocale &locale) = 0
356 @brief 返回指定配置项的描述信息
357 @param[in] key 配置项名称
358 @param[in] locale 为语言版本
359 @return
360
361 @fn virtual QString Dtk::Core::DConfigMeta::metaPath(const QString &localPrefix = QString(), bool *useAppId = nullptr) const = 0
362 @brief 返回描述文件的路径
363 @param[in] localPrefix 目录的所有需要查找的覆盖机制目录
364 @param[in] useAppId 是否不使用通用目录
365 @return
366
367 @fn virtual QStringList Dtk::Core::DConfigMeta::allOverrideDirs(const bool useAppId, const QString &prefix = QString()) const = 0
368 @brief 获得前缀为 `prefix` 目录的所有需要查找的覆盖机制目录
369 @param[in] useAppId 是否不使用通用目录
370 @param[in] prefix 目录的应用或公共库的所有覆盖机制目录
371 @return
372
373 @fn virtual QVariant DConfigMeta::value(const QString &key) const = 0
374 @brief meta初始值经过覆盖机制覆盖后的原始值
375 @param[in] key 配置项名称
376 @return
377
378 @fn static QStringList genericMetaDirs(const QString &localPrefix = QString())
379 @brief 获取应用无关配置存储的目录
380 @param[in] localPrefix 配置的目录前缀
381 @return 返回应用无关配置存储的目录列表
382
383 @fn static QStringList applicationMetaDirs(const QString &localPrefix, const QString &appId)
384 @brief 获取应用配置存储的目录
385 @param[in] localPrefix 配置的目录前缀
386 @param[in] appId 应用唯一标识
387 @return 返回存储应用配置的目录列表
388 */
389
390 /*!
391 @class Dtk::Core::DConfigCache dconfigfile.h
392 @brief 提供配置文件的用户和全局运行缓存访问接口
393
394 @fn virtual bool Dtk::Core::DConfigCache::load(const QString &localPrefix = QString()) = 0
395 @brief 解析缓存配置文件
396 @return
397
398 @fn virtual bool Dtk::Core::DConfigCache::load(const QString &localPrefix = QString()) = 0
399 @brief 解析缓存配置文件
400 @return
401
402 @fn virtual bool Dtk::Core::DConfigCache::save(const QString &localPrefix = QString(), QJsonDocument::JsonFormat format = QJsonDocument::Indented, bool sync = false) = 0
403 @brief 保存缓存的值到磁盘中
404 @param[in] localPrefix 为目录前缀
405 @param[in] format 保存格式
406 @param[in] sync 是否立即刷新
407 @return
408
409 @fn virtual bool Dtk::Core::DConfigCache::isGlobal() const = 0
410 @brief 是否是全局缓存
411 @return
412
413 @fn virtual void Dtk::Core::DConfigCache::remove(const QString &key) = 0
414 @brief 删除缓存中的配置项
415 @param[in] key 配置项名称
416 @return
417
418 @fn virtual QStringList Dtk::Core::DConfigCache::keyList() const = 0
419 @brief 返回配置内容的所有配置项
420 @return
421
422 @fn virtual bool Dtk::Core::DConfigCache::setValue(const QString &key, const QVariant &value, const int serial, const uint uid, const QString &callerAppid) = 0
423 @brief 设置缓存中的值
424 @param[in] key 配置项名称
425 @param[in] value 需要设置的值
426 @param[in] uid 设置时的用户id
427 @param[in] callerAppid 设置时的应用id
428 @return 为true时表示重新设置了新值,false表示没有设置。
429
430 @fn virtual QVariant Dtk::Core::DConfigCache::value(const QString &key) const = 0
431 @brief 获取缓存中的值
432 @param[in] key 配置项名称
433 @return
434
435 @fn virtual int Dtk::Core::DConfigCache::serial(const QString &key) const = 0
436 @brief 返回配置项的单调递增值
437 @param[in] key 配置项名称
438 @return -1为无效值,表明没有配置此项
439
440 @fn virtual uint Dtk::Core::DConfigCache::uid() const = 0
441 @brief 用户标识,为全局缓存时,uid为非用户标识的特定值
442 @return
443
444 @fn virtual void setCachePathPrefix(const QString &prefix) = 0
445 @brief 指定缓存位置前缀,缓存访问所需的权限及区分不同缓存的位置由调用者考虑,其默认值参考配置策略规范
446 @param[in] prefix 缓存位置的前缀
447
448 */