规范配置文件读写的相关接口的配置文件实现更多...

#include <dconfigfile.h>

类 Dtk::Core::DConfigFile 继承关系图:

类
struct	Version
	版本信息更多...

Public 类型
enum	Flag { NoOverride = 1 << 0 , Global = 1 << 1 , UserPublic = 1 << 2 }
	配置项名称更多...

enum	Permissions { ReadOnly , ReadWrite }
	配置项的权限更多...

enum	Visibility { Private , Public }
	配置项的可见性更多...

Public 成员函数
	DConfigFile (const QString &appId, const QString &name, const QString &subpath=QString())
	DConfigFile构造函数,构造配置文件管理对象。

	DConfigFile (const DConfigFile &other)
	DConfigFile构造函数,构造配置文件管理对象。

bool	load (const QString &localPrefix=QString())
	解析配置文件

bool	load (QIODevice meta, const QList< QIODevice > &overrides)
	解析配置文件流

bool	save (const QString &localPrefix=QString(), QJsonDocument::JsonFormat format=QJsonDocument::Indented, bool sync=false) const
	保存缓存的值到磁盘中

bool	isValid () const
	检测配置文件是否有效

QVariant	value (const QString &key, DConfigCache *userCache=nullptr) const
	DConfigFile::value

QVariant	cacheValue (DConfigCache *userCache, const QString &key) const
	DConfigFile::cacheValue 获取指定用户缓存的配置项值，若无此配置项的用户缓存值，返回无效值

bool	setValue (const QString &key, const QVariant &value, const QString &callerAppid, DConfigCache *userCache=nullptr)
	设置缓存中的值

DConfigCache *	createUserCache (const uint uid)
	创建用户缓存

DConfigCache *	globalCache () const
	返回全局缓存

DConfigMeta *	meta ()
	返回原型对象

静态 Public 成员函数
static constexpr Version	supportedVersion ()
	支持的版本

友元
QDebug	operator<< (QDebug, const DConfigFile &)

额外继承的成员函数
Protected 成员函数继承自 Dtk::Core::DObject
	DObject (DObject *parent=nullptr)

	DObject (DObjectPrivate &dd, DObject *parent=nullptr)

Protected 属性继承自 Dtk::Core::DObject
QScopedPointer< DObjectPrivate >	d_d_ptr

详细描述

规范配置文件读写的相关接口的配置文件实现

概述

规范配置文件读写的相关接口的配置文件实现

项目目录结构如下：

├── CMakeLists.txt
├── config
│   └── example.json
└── main.cpp

CMakeLists.txt

cmake_minimum_required(VERSION 3.1.0)                    # 指定cmake最低版本
 
project(dconfigfile-example VERSION 1.0.0 LANGUAGES CXX) # 指定项目名称, 版本, 语言 cxx就是c++
 
set(CMAKE_CXX_STANDARD 11)                               # 指定c++标准
set(CMAKE_CXX_STANDARD_REQUIRED ON)                      # 指定c++标准要求,至少为11以上
 
set(CMAKE_AUTOMOC ON)                                    # 支持qt moc
set(CMAKE_AUTORCC ON)                                    # 支持qt资源文件
set(CMAKE_AUTOUIC ON)                                    # 支持qt ui文件(非必须)
 
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)                    # 支持 clangd
 
if (CMAKE_VERSION VERSION_LESS "3.7.0")                  # 如果cmake版本小于3.7.0
    set(CMAKE_INCLUDE_CURRENT_DIR ON)                    # 设置包含当前目录
endif()
 
find_package(Qt5 REQUIRED COMPONENTS Core)               # 寻找Qt5组件Core
find_package(Dtk REQUIRED COMPONENTS Core)               # 寻找Dtk组件Core
 
add_executable(${PROJECT_NAME}                           # 生成可执行文件
    main.cpp
)
 
target_link_libraries(${PROJECT_NAME} PRIVATE            # 添加需要链接的共享库
    Qt5::Core
    dtkcore
)
 
# dtk_add_config_meta_files函数，部署一些"meta"的配置。
# 函数定义在dtkcore的cmake目录下
# APPID 应用的ID
# FILES 需要部署的文件。
dtk_add_config_meta_files(
    APPID ${PROJECT_NAME}
    FILES ./config/example.json
)

example.json

{
    "magic": "dsg.config.meta",
    "version": "1.0",
    "contents": {
        "canExit": {
            "value": true,
            "serial": 0,
            "flags": ["global"],
            "name": "I am name",
            "name[zh_CN]": "我是名字",
            "description": "I am description",
            "permissions": "readwrite",
            "visibility": "private"
        },
        "key1": {
            "value": "125",
            "serial": 0,
            "flags": ["nooverride"],
            "name": "I am name",
            "name[zh_CN]": "我是名字",
            "description": "I am description",
            "permissions": "readwrite",
            "visibility": "public"
        },
        "number": {
          "value": 1,
          "serial": 0,
          "flags": ["global"],
          "name": "array value type",
          "permissions": "readwrite",
          "visibility": "public"
        },
        "array": {
          "value": ["value1", "value2"],
          "serial": 0,
          "flags": ["global"],
          "name": "array",
          "permissions": "readwrite",
          "visibility": "public"
        },
        "map": {
          "value": {"key1": "value1", "key2": "value2"},
          "serial": 0,
          "flags": ["nooverride"],
          "name": "map",
          "permissions": "readwrite",
          "visibility": "public"
        },
        "publicConfig": {
          "value": true,
          "serial": 0,
          "flags": ["user-public"],
          "name": "public configure",
          "name[zh_CN]": "我是公开的配置",
          "description": "I am public configure",
          "permissions": "readwrite",
          "visibility": "private"
        }
    }
}

main.cpp

#include <DConfigFile>
#include <QDebug>
#include <QCoreApplication>
#include <unistd.h>
 
DCORE_USE_NAMESPACE
 
int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);
 
    // 构造DConfigFile，元数据文件名example，与元数据安装目录的/usr/share/dsg/configs/APPID名(可执行文件名)对应目录/example.json，
    DConfigFile configFile("dconfigfile-example","example");
    // 解析配置文件
    configFile.load();
 
    // 创建用户缓存
    QScopedPointer<DConfigCache> userCache(configFile.createUserCache(getuid()));
    // 解析配置文件
    userCache->load();
 
    // 判断是否有效
    if (!configFile.isValid()) {
        qWarning() << QString("DConfig无效.");
        return 0;
    }
 
    // meta 返回原型对象, keyList获取所有配置项的key
    qDebug() << "所有的所有配置项的key:" << configFile.meta()->keyList();
 
    // 获取指定配置项的值，配置项可以是字符串，数组，map容器，布尔值，整型，详见example.json
    qDebug() << "canExit对应的值:" <<  configFile.value("canExit").toBool();
 
    // 配置项的可见性，其余配置项标记、配置项的权限可查看文档
    qDebug() << "配置项的可见性" << configFile.meta()->visibility("canExit");
 
    QVariantMap map;
    map.insert("k1","v1");
    map.insert("k2","v2");
    // 设置map的值
    configFile.setValue("map", map, "dconfigfile-example", userCache.get());
 
    configFile.save();
 
    // root用户运行，save的数据会保存到/root/.config/dsg/configs-fake-global/dconfigfile-example/example.json
    // map数据对应的flags标记为NoOverride，配置项允许被覆盖，如果flags为global泽忽略用户身份，详见文档。
    userCache->save();
 
    return a.exec();
}

从源码构建

mkdir build && cd build
# 修改路径前缀为/usr,GNU标准的默认值为/usr/local
cmake .. -DCMAKE_INSTALL_PREFIX=/usr
sudo make install
sudo ./dconfigfile-example

结果如下图

一些简单的输出

用户保存的数据

成员枚举类型说明

◆ Flag

enum Dtk::Core::DConfigFile::Flag

配置项名称

枚举值
NoOverride	存在此标记时，将表明则此配置项不可被覆盖（详见下述 override 机制）。反之，不存在此标记时表明此配置项允许被覆盖，对于此类配置项，如若其有界面设置入口，则当此项不可写时，应当隐藏或禁用界面的设置入口.
Global	当读写此类配置时，将忽略用户身份，无论程序使用哪个用户身份执行，读操作都将获取到同样的数据，写操作将对所有用户都生效。但是，如果对应的配置存储目录不存在或无权限写入，则忽略此标志
UserPublic	该类配置项允许被其他用户访问

◆ Permissions

enum Dtk::Core::DConfigFile::Permissions

配置项的权限

枚举值
ReadOnly	将配置项覆盖为只读
ReadWrite	将配置项覆盖为可读可写

◆ Visibility

enum Dtk::Core::DConfigFile::Visibility

配置项的可见性

枚举值

Private

仅限程序内部使用，对外不可见。此类配置项完全由程序自己读写，可随意增删改写其含义，无需做兼容性考虑

Public

外部程序可使用。此类配置项一旦发布，在兼容性版本的升级中，要保障此配置项向下兼容，简而言之，只允许在程序/库的大版本升级时才允许删除或修改此类配置项，当配置项的 permissions、visibility、flags 任意一个属性被修改则认为此配置项被修改，除此之外修改 value、name、description 属性时则不需要考虑兼容性。

构造及析构函数说明

◆ DConfigFile() [1/2]

Dtk::Core::DConfigFile::DConfigFile	(	const QString &	appId,
		const QString &	name,
		const QString &	subpath = `QString()`
	)

explicit

DConfigFile构造函数,构造配置文件管理对象。

参数

[in]	appId	应用程序唯一标识
[in]	name	配置文件名
[in]	subpath	子目录

◆ DConfigFile() [2/2]

Dtk::Core::DConfigFile::DConfigFile ( const DConfigFile & other )

explicit

DConfigFile构造函数,构造配置文件管理对象。

参数

[in]	appId	应用程序唯一标识
[in]	name	配置文件名
[in]	subpath	子目录

成员函数说明

◆ cacheValue()

QVariant Dtk::Core::DConfigFile::cacheValue	(	DConfigCache *	userCache,
		const QString &	key
	)		const

DConfigFile::cacheValue 获取指定用户缓存的配置项值，若无此配置项的用户缓存值，返回无效值

参数

[in]	key	配置项名称
[in]	userCache	用户缓存,当key为全局配置项时, userCache 不会被使用

返回

◆ globalCache()

DConfigCache * Dtk::Core::DConfigFile::globalCache ( ) const

返回全局缓存

返回

◆ isValid()

bool Dtk::Core::DConfigFile::isValid ( ) const

检测配置文件是否有效

返回

◆ load() [1/2]

bool Dtk::Core::DConfigFile::load ( const QString & localPrefix = QString() )

解析配置文件

参数

[in] localPrefix 为目录前缀

返回

◆ load() [2/2]

bool Dtk::Core::DConfigFile::load	(	QIODevice *	meta,
		const QList< QIODevice * > &	overrides
	)

解析配置文件流

参数

[in]	meta	为原型流
[in]	overrides	为覆盖机制查找的文件流

返回

◆ meta()

DConfigMeta * Dtk::Core::DConfigFile::meta ( )

返回原型对象

返回

◆ save()

bool Dtk::Core::DConfigFile::save	(	const QString &	localPrefix = `QString()`,
		QJsonDocument::JsonFormat	format = `QJsonDocument::Indented`,
		bool	sync = `false`
	)		const

保存缓存的值到磁盘中

参数

[in]	format	保存格式
[in]	sync	是否立即刷新

返回

◆ setValue()

bool Dtk::Core::DConfigFile::setValue	(	const QString &	key,
		const QVariant &	value,
		const QString &	callerAppid,
		DConfigCache *	userCache = `nullptr`
	)

设置缓存中的值

参数

[in]	key	配置项名称
[in]	value	需要设置的值
[in]	uid	设置时的用户id
[in]	appid	设置时的应用id

返回: 为true时表示重新设置了新值,false表示没有设置

◆ supportedVersion()

static constexpr DConfigFile::Version Dtk::Core::DConfigFile::supportedVersion ( )

staticconstexpr

支持的版本

返回

◆ value()

QVariant Dtk::Core::DConfigFile::value	(	const QString &	key,
		DConfigCache *	userCache = `nullptr`
	)		const

DConfigFile::value

参数

[in]	key	配置项名称
[in]	userCache	用户缓存,当key为全局项时, userCache 不会被使用

返回

该类的文档由以下文件生成:

include/global/dconfigfile.h
docs/global/dconfigfile.zh_CN.dox

类

Public 类型

Public 成员函数

静态 Public 成员函数

友元

额外继承的成员函数

详细描述

概述

CMakeLists.txt

example.json

main.cpp

从源码构建

成员枚举类型说明

◆ Flag

◆ Permissions

◆ Visibility

构造及析构函数说明

◆ DConfigFile() [1/2]

◆ DConfigFile() [2/2]

成员函数说明

◆ cacheValue()

◆ globalCache()

◆ isValid()

◆ load() [1/2]

◆ load() [2/2]

◆ meta()

◆ save()

◆ setValue()

◆ supportedVersion()

◆ value()