Debian Codegraph @

src/dconfigfile.cpp

raw
1 // SPDX-FileCopyrightText: 2021 - 2023 UnionTech Software Technology Co., Ltd.
2 //
3 // SPDX-License-Identifier: LGPL-3.0-or-later
4
5 #include "dconfigfile.h"
6
7 #include "dobject_p.h"
8 #include "filesystem/dstandardpaths.h"
9
10 #include <QFile>
11 #include <QJsonDocument>
12 #include <QLoggingCategory>
13 #include <QJsonObject>
14 #include <QJsonArray>
15 #include <QCoreApplication>
16 #include <QVariant>
17 #include <QDebug>
18 #include <QFileInfo>
19 #include <QDir>
20 #include <QDirIterator>
21 #include <QCollator>
22 #include <QDateTime>
23
24 #include <unistd.h>
25 #include <pwd.h>
26
27 // https://gitlabwh.uniontech.com/wuhan/se/deepin-specifications/-/issues/3
28
29 DCORE_BEGIN_NAMESPACE
30
31 #ifndef QT_DEBUG
32 Q_LOGGING_CATEGORY(cfLog, "dtk.dsg.config" , QtInfoMsg);
33 #else
34 Q_LOGGING_CATEGORY(cfLog, "dtk.dsg.config");
35 #endif
36
37 #define FILE_SUFFIX QLatin1String(".json")
38
39 // subpath must be a subdirectory of the dir.
40 inline static bool subpathIsValid(const QString &subpath, const QDir &dir)
41 {
42 if (subpath.isEmpty())
43 return true;
44
45 const QDir subDir(dir.filePath(subpath.mid(1)));
46 return subDir.absolutePath().startsWith(dir.absolutePath());
47 }
48 // name must be a valid filename.
49 inline static bool isValidFilename(const QString& filename)
50 {
51 static const QRegularExpression regex("^[\\w\\-\\.\\ ]+$");
52 QRegularExpressionMatch match = regex.match(filename);
53 return match.hasMatch();
54 }
55 // AppId don't contain ' ', but it can be empty.
56 inline static bool isValidAppId(const QString& appId)
57 {
58 static const QRegularExpression regex("^[\\w\\-\\.]*$");
59 QRegularExpressionMatch match = regex.match(appId);
60 return match.hasMatch();
61 }
62 /*!
63 @~english
64 \internal
65
66 @brief 按子目录查找机制查找配置文件
67
68 在 \a baseDir目录下,查找名称为 \a name的文件,
69 若存在 \a subpath,则从 \a subpath叶子目录逐级向上查找名称为 \a name的文件,
70 若不存在此文件,则返回无效路径.
71 */
72 inline QString getFile(const QString &baseDir, const QString &subpath, const QString &name,
73 bool canFallbackUp = true) {
74 qCDebug(cfLog, "load json file from base dir:\"%s\", subpath = \"%s\", file name =\"%s\".",
75 qPrintable(baseDir), qPrintable(subpath), qPrintable(name));
76
77 const QDir base_dir(baseDir);
78 if (!subpathIsValid(subpath, base_dir)) {
79 qCDebug(cfLog, "subpath is invalid in the base dir:\"%s\", subpath:\"%s\".", qPrintable(baseDir), qPrintable(subpath));
80 return QString();
81 }
82 QDir target_dir = base_dir;
83
84 if (!subpath.isEmpty())
85 target_dir.cd(subpath.mid(1));
86
87 do {
88 qCDebug(cfLog, "load json file from: \"%s\"", qPrintable(target_dir.path()));
89
90 if (QFile::exists(target_dir.filePath(name))) {
91 return target_dir.filePath(name);
92 }
93
94 if (base_dir == target_dir)
95 break;
96 } while (canFallbackUp && target_dir.cdUp());
97
98 return QString();
99 }
100
101 inline QFile *loadFile(const QString &baseDir, const QString &subpath, const QString &name,
102 bool canFallbackUp = true)
103 {
104 QString path = getFile(baseDir, subpath, name, canFallbackUp);
105 if (!path.isEmpty()) {
106 return new QFile(path);
107 }
108 return nullptr;
109 }
110
111 static QJsonDocument loadJsonFile(QIODevice *data)
112 {
113 if (!data->open(QIODevice::ReadOnly)) {
114 if (auto file = qobject_cast<QFile*>(data)) {
115 qCDebug(cfLog, "Falied on open file: \"%s\", error message: \"%s\"",
116 qPrintable(file->fileName()), qPrintable(file->errorString()));
117 }
118 return QJsonDocument();
119 }
120
121 QJsonParseError error;
122 auto document = QJsonDocument::fromJson(data->readAll(), &error);
123 data->close();
124
125 if (error.error != QJsonParseError::NoError) {
126 qCWarning(cfLog, "%s", qPrintable(error.errorString()));
127 return QJsonDocument();
128 }
129
130 return document;
131 }
132
133 static DConfigFile::Version parseVersion(const QJsonObject &obj) {
134 DConfigFile::Version version {0, 0};
135 const QString &verStr = obj[QLatin1String("version")].toString();
136
137 if (verStr.isEmpty()) {
138 return version;
139 }
140
141 const QStringList &items = verStr.split(QLatin1Char('.'));
142
143 if (items.size() != 2)
144 return version;
145
146 bool ok = false;
147 quint16 major = items.first().toUShort(&ok);
148
149 if (!ok)
150 return version;
151
152 quint16 minor = items.last().toUShort(&ok);
153
154 if (!ok)
155 return version;
156
157 version.major = major;
158 version.minor = minor;
159
160 return version;
161 }
162
163 #define MAGIC_META QLatin1String("dsg.config.meta")
164 #define MAGIC_OVERRIDE QLatin1String("dsg.config.override")
165 #define MAGIC_CACHE QLatin1String("dsg.config.cache")
166
167 static const uint InvalidUID = 0xFFFF;
168
169 inline static bool checkMagic(const QJsonObject &obj, QLatin1String request) {
170 return obj[QLatin1String("magic")].toString() == request;
171 }
172
173 inline static bool versionIsValid(const DConfigFile::Version &v) {
174 return v.major > 0 || v.minor > 0;
175 }
176
177 inline static bool checkVersion(const QJsonObject &obj, const DConfigFile::Version &request) {
178 const DConfigFile::Version &v = parseVersion(obj);
179 return versionIsValid(v) && v.major == request.major;
180 }
181
182 inline void overrideValue(QLatin1String subkey, const QJsonValue &from, QVariantHash &target) {
183 const QJsonValue &v = from[subkey];
184
185 if (!v.isUndefined())
186 target[subkey] = v.toVariant();
187 }
188
189 inline static QString getUserName(const uint uid) {
190 passwd *pw = getpwuid(uid);
191 return pw ? QString::fromLocal8Bit(pw->pw_name) : QString();
192 }
193
194 /*!
195 @~english
196 @class Dtk::Core::DConfigFile
197 \inmodule dtkcore
198
199 @brief Specification configuration file implementation of the interface that the configuration file reads and writes.
200 */
201
202 /*!
203 @~english
204 @enum DConfigFile::Flag
205
206 \value NoOverride When this flag exists , it indicates that this configuration item can't be overwritten (see the override mechanism below for details).
207 Otherwise, the absence of this flag indicates that this configuration item is allowed to be overwritten,
208 If it has a screen setting entry, hide or disable the screen setting entry when this entry is not writable.
209 \value Global When reading or writing such a configuration, the user identity is ignored and the same data is obtained regardless of which user identity the program executes.
210 The write operation will take effect for all users. However, if the corresponding configuration storage directory does not exist or has no write permission, this flag is ignored.
211 */
212
213 /*!
214 @~english
215 @enum DConfigFile::Permissions
216
217 \value ReadOnly Overwrite the configuration item as readonly.
218 \value ReadWrite Overwrite the configuration item as readable and writable.
219 */
220
221 /*!
222 @~english
223 @enum DConfigFile::Visibility
224
225 \value Private For internal program use only,
226 Not visible to the outside world. Such configuration items are completely read and written by the program itself, and can be added, deleted and rewritten at will without compatibility consideration,
227 \value Public External programs are available.
228 Once this type of configuration item is released, ensure that the configuration item is backward compatible during the upgrade of the compatible version.
229 In short, this type of configuration item is only allowed to be deleted or modified when a major version of the program/library is upgraded.
230 The configuration item is changed if any of its permissions, visibility, or flags properties are changed.
231 In addition, you do not need to consider compatibility when modifying the value, name, and description attributes.
232 */
233
234 /*!
235 @~english
236 @struct Dtk::Core::DConfigFile::Version
237 \inmodule dtkcore
238 @brief Version Information
239
240 The content format version of this file. The version number is described by two digits,
241 Profiles with different first digits are incompatible with each other, and profiles with different second digits need to be compatible with each other.
242 A program that reads this profile needs to perform content analysis by version, and when it encounters an incompatible version, it needs to terminate parsing immediately and ignore the file.
243 And write a warning message to the program log, such as "1.0" and "2.0" versions are not compatible,
244 If the parser only supports version 1.0, it should stop parsing when it encounters a 2.0 profile.
245 But if version 1.1 is encountered, execution can continue.
246 When writing to this profile, if an incompatible version is encountered, the current contents need to be cleared before writing, and this field needs to be updated with each write
247 */
248
249 DConfigMeta::~DConfigMeta() {}
250
251 QStringList DConfigMeta::genericMetaDirs(const QString &localPrefix)
252 {
253 QStringList paths;
254 // lower priority is higher.
255 for (auto item: DStandardPaths::paths(DStandardPaths::DSG::DataDir)) {
256 paths.prepend(QDir::cleanPath(QString("%1/%2/configs").arg(localPrefix, item)));
257 }
258 return paths;
259 }
260
261 QStringList DConfigMeta::applicationMetaDirs(const QString &localPrefix, const QString &appId)
262 {
263 QStringList paths;
264 const auto &dataPaths = genericMetaDirs(localPrefix);
265 paths.reserve(dataPaths.size());
266 for (auto item : dataPaths) {
267 paths << QString("%1/%2").arg(item, appId);
268 }
269 return paths;
270 }
271
272 Dtk::Core::DConfigCache::~DConfigCache() {}
273
274 struct DConfigKey {
275 DConfigKey(const QString &aappId, const QString &afileName, const QString &asubpath)
276 : appId(aappId),
277 fileName(afileName),
278 subpath(asubpath)
279 {
280 }
281
282 explicit DConfigKey(const DConfigKey &src)
283 : DConfigKey(src.appId, src.fileName, src.subpath)
284 {
285 }
286
287 DConfigKey &operator = (const DConfigKey &src)
288 {
289 this->appId = src.appId;
290 this->fileName = src.fileName;
291 this->subpath = src.subpath;
292 return *this;
293 }
294
295 QString appId;
296 QString fileName;
297 QString subpath;
298 };
299
300 class Q_DECL_HIDDEN DConfigInfo {
301 public:
302 DConfigInfo()
303 {
304
305 }
306 DConfigInfo(const DConfigInfo &other)
307 {
308 this->values = other.values;
309 }
310 DConfigInfo operator = (const DConfigInfo &other)
311 {
312 this->values = other.values;
313 return *this;
314 }
315 inline static bool checkSerial(const int metaSerial, const int cacheSerial)
316 {
317 if (cacheSerial < 0)
318 return true;
319 if (metaSerial >= 0 && metaSerial == cacheSerial)
320 return true;
321 return false;
322 }
323
324 DConfigFile::Visibility visibility(const QString &key) const
325 {
326 DConfigFile::Visibility p = DConfigFile::Private;
327 const auto &tmp = values[key][QLatin1String("visibility")].toString();
328 if (tmp == QLatin1String("public"))
329 p = DConfigFile::Public;
330
331 return p;
332 }
333
334 DConfigFile::Permissions permissions(const QString &key) const
335 {
336 DConfigFile::Permissions p = DConfigFile::ReadOnly;
337 const auto &tmp = values[key][QLatin1String("permissions")].toString();
338 if (tmp == QLatin1String("readwrite"))
339 p = DConfigFile::ReadWrite;
340
341 return p;
342 }
343
344 DConfigFile::Flags flags(const QString &key) const
345 {
346 DConfigFile::Flags flags = {};
347 const auto &tmp = values[key][QLatin1String("flags")];
348 Q_FOREACH(const QString &flag, tmp.toStringList()) {
349 if (flag == QLatin1String("nooverride")) {
350 flags |= DConfigFile::NoOverride;
351 } else if (flag == QLatin1String("global")) {
352 flags |= DConfigFile::Global;
353 } else if (flag == QLatin1String("user-public")) {
354 flags |= DConfigFile::UserPublic;
355 }
356 }
357
358 return flags;
359 }
360
361 QString displayName(const QString &key, const QLocale &locale) const
362 {
363 if (locale == QLocale::AnyLanguage)
364 return values[key][QLatin1String("name")].toString();
365
366 return values[key].value(QString("name[%1]")
367 .arg(locale.name())).toString();
368 }
369
370 QString description(const QString &key, const QLocale &locale) const
371 {
372 if (locale == QLocale::AnyLanguage)
373 return values[key][QLatin1String("description")].toString();
374
375 return values[key].value(QString("description[%1]")
376 .arg(locale.name())).toString();
377 }
378
379 inline QVariant value(const QString &key) const
380 {
381 return values[key][QLatin1String("value")];
382 }
383
384 inline int serial(const QString &key) const
385 {
386 bool status = false;
387 const int tmp = values[key][QLatin1String("serial")].toInt(&status);
388 if (status) {
389 return tmp;
390 }
391 return -1;
392 }
393
394 inline void setValue(const QString &key, const QVariant &value)
395 {
396 values[key]["value"] = value;
397 }
398
399 inline void setSerial(const QString &key, const int &value)
400 {
401 values[key]["serial"] = value;
402 }
403
404 inline void setTime(const QString &key, const QString &value)
405 {
406 values[key]["time"] = value;
407 }
408
409 inline void setUser(const QString &key, const uint &value)
410 {
411 values[key]["user"] = getUserName(value);
412 }
413
414 inline void setAppId(const QString &key, const QString &value)
415 {
416 values[key]["appid"] = value;
417 }
418
419 inline QStringList keyList() const
420 {
421 return values.keys();
422 }
423
424 inline bool contains(const QString &key) const
425 {
426 return values.contains(key);
427 }
428
429 inline void remove(const QString &key)
430 {
431 values.remove(key);
432 }
433
434 inline bool update(const QString &key, const QVariantHash &value)
435 {
436 if (!value.contains("value")) {
437 return false;
438 }
439 values[key] = value;
440 return true;
441 }
442
443 inline bool updateValue(const QString &key, const QJsonValue &value)
444 {
445 return overrideValue(key, "value", value);
446 }
447
448 inline void updateSerial(const QString &key, const QJsonValue &value)
449 {
450 overrideValue(key, "serial", value);
451 }
452
453 inline void updatePermissions(const QString &key, const QJsonValue &value)
454 {
455 overrideValue(key, "permissions", value);
456 }
457
458 QJsonObject content() const
459 {
460 QJsonObject contents;
461 for (auto i = values.constBegin(); i != values.constEnd(); ++i) {
462 contents[i.key()] = QJsonObject::fromVariantHash(i.value());
463 }
464 return contents;
465 }
466 private:
467 bool overrideValue(const QString &key, const QString &subkey, const QJsonValue &from) {
468 const QJsonValue &v = from[subkey];
469
470 if (v.isUndefined()) {
471 return false;
472 }
473
474 values[key][subkey] = v.toVariant();
475 return true;
476 }
477
478 QHash<QString, QVariantHash> values;
479 };
480
481
482 /*!
483 @~english
484 @class Dtk::Core::DConfigMeta
485 \inmodule dtkcore
486
487 @brief Provides a prototype of the configuration file and an access interface to the override mechanism.
488
489 */
490
491 /*!
492 @~english
493 @fn DConfigFile::Version DConfigMeta::version() const = 0;
494
495 @brief Returns configuration version information.
496 @return
497 */
498
499 /*!
500 @~english
501 @fn void DConfigMeta::setVersion(quint16 major, quint16 minor) = 0;
502
503 @brief Sets configuration version information
504 \a major Major version number
505 \a minor Minor version number
506 */
507
508 /*!
509 @~english
510 @fn bool DConfigMeta::load(const QString &localPrefix = QString()) = 0;
511
512 @brief Parsing configuration files
513 \a localPrefix Directory prefix
514 @return
515 */
516
517 /*!
518 @~english
519 @fn bool DConfigMeta::load(QIODevice *meta, const QList<QIODevice*> &overrides) = 0;
520
521 @brief Parse the configuration file stream
522 \a meta Prototype stream
523 \a overrides The file stream to find for the override mechanism
524 @return
525 */
526
527 /*!
528 @~english
529 @fn QStringList DConfigMeta::keyList() const = 0;
530
531 @brief Returns all configuration items for the configuration content
532 @return
533 */
534
535 /*!
536 @~english
537 @fn DConfigFile::Flags DConfigMeta::flags(const QString &key) const = 0;
538
539 @brief Returns the attribute of the specified configuration item
540 \a key Configure the name of the option, NoOverride This option can't be overridden, and Global ignores the user identity
541 @return
542 */
543
544 /*!
545 @~english
546 @fn DConfigFile::Permissions DConfigMeta::permissions(const QString &key) const = 0;
547
548 @brief Returns the permission for the specified configuration item
549 \a key Configuration name
550 @return
551
552 */
553
554 /*!
555 @~english
556 @fn DConfigFile::Visibility DConfigMeta::visibility(const QString &key) const = 0;
557
558 @brief Returns the visibility of the specified configuration item
559 \a key Configuration name
560 @return
561
562 */
563
564 /*!
565 @~english
566 @fn int DConfigMeta::serial(const QString &key) const = 0;
567
568 @brief Returns a monotonically increasing value of a configuration item
569 \a key Configuration name
570 @return An invalid value of -1 indicates that the entry is not configured
571
572 */
573
574 /*!
575 @~english
576 @fn QString DConfigMeta::displayName(const QString &key, const QLocale &locale) = 0;
577
578 @brief Returns the display name of the specified configuration
579 \a key Configuration name
580 \a locale Language version
581 @return
582 */
583
584 /*!
585 @~english
586 @fn QString DConfigMeta::description(const QString &key, const QLocale &locale) = 0;
587
588 @brief Returns a description of the specified configuration item
589 \a key Configuration name
590 \a locale Language version
591 @return
592
593 */
594
595 /*!
596 @~english
597 @fn QString DConfigMeta::metaPath(const QString &localPrefix = QString(), bool *useAppId = nullptr) const = 0;
598
599 @brief Returns the path to the profile
600 \a localPrefix Directory of all override mechanisms that need to be searched
601 @return
602 */
603
604 /*!
605 @~english
606 @fn QStringList DConfigMeta::allOverrideDirs(const bool useAppId, const QString &prefix = QString()) const = 0;
607
608 @brief Gets all the override mechanism directories to look for for the \a prefix directory
609 \a useAppId Whether not to use the generic directory
610 @return
611 */
612
613 /*!
614 @~english
615 @fn QVariant DConfigMeta::value(const QString &key) const = 0;
616
617 @brief Original value of meta overwritten by the overwriting mechanism
618 \a key Configuration name
619 @return
620 */
621
622 class Q_DECL_HIDDEN DConfigMetaImpl : public DConfigMeta {
623 // DConfigMeta interface
624 public:
625 explicit DConfigMetaImpl(const DConfigKey &configKey);
626 virtual ~DConfigMetaImpl() override;
627
628 inline virtual QStringList keyList() const override
629 {
630 return values.keyList();
631 }
632 inline virtual DConfigFile::Flags flags(const QString &key) const override
633 {
634 return values.flags(key);
635 }
636 inline virtual DConfigFile::Permissions permissions(const QString &key) const override
637 {
638 return values.permissions(key);
639 }
640 inline virtual DConfigFile::Visibility visibility(const QString &key) const override
641 {
642 return values.visibility(key);
643 }
644 inline virtual int serial(const QString &key) const override
645 {
646 return values.serial(key);
647 }
648 inline virtual QString description(const QString &key, const QLocale &locale) override
649 {
650 return values.description(key, locale);
651 }
652 virtual DConfigFile::Version version() const override
653 {
654 return m_version;
655 }
656 inline virtual void setVersion(quint16 major, quint16 minor) override
657 {
658 m_version.major = major;
659 m_version.minor = minor;
660 }
661 inline virtual QString displayName(const QString &key, const QLocale &locale) override
662 {
663 return values.displayName(key, locale);
664 }
665 inline virtual QVariant value(const QString &key) const override
666 {
667 return values.value(key);
668 }
669
670 QString metaPath(const QString &localPrefix, bool *useAppId) const override
671 {
672 bool useAppIdForOverride = true;
673
674 QString path;
675 const QStringList &applicationMetas = applicationMetaDirs(localPrefix, configKey.appId);
676 for (auto iter = applicationMetas.rbegin(); iter != applicationMetas.rend(); iter++) {
677 path = getFile(*iter, configKey.subpath, configKey.fileName + FILE_SUFFIX);
678 if (!path.isEmpty())
679 break;
680 }
681
682 if (path.isEmpty()) {
683 useAppIdForOverride = false;
684 const QStringList &genericnMetas = genericMetaDirs(localPrefix);
685 for (auto iter = genericnMetas.rbegin(); iter != genericnMetas.rend(); iter++) {
686 path = getFile(*iter, configKey.subpath, configKey.fileName + FILE_SUFFIX);
687 if (!path.isEmpty())
688 break;
689 }
690 }
691 if (useAppId) {
692 *useAppId = useAppIdForOverride;
693 }
694 return path;
695 }
696
697 bool load(const QString &localPrefix) override
698 {
699 if (!isValidAppId(configKey.appId)) {
700 qCWarning(cfLog, "AppId is invalid, appId=%s", qPrintable(configKey.appId));
701 return false;
702 }
703 if (!isValidFilename(configKey.fileName)) {
704 qCWarning(cfLog, "Name is invalid, filename=%s", qPrintable(configKey.fileName));
705 return false;
706 }
707 bool useAppIdForOverride = true;
708 QString path = metaPath(localPrefix, &useAppIdForOverride);
709 if (path.isEmpty()) {
710 qCWarning(cfLog, "Can't load meta file from local prefix: \"%s\"", qPrintable(localPrefix));
711 return false;
712 }
713
714 QScopedPointer<QFile> meta(new QFile(path));
715
716 struct _ScopedPointer {
717 explicit _ScopedPointer(const QList<QIODevice*> &list)
718 : m_list(list) {}
719 ~_ScopedPointer() {qDeleteAll(m_list);}
720
721 QList<QIODevice*> m_list;
722 };
723 _ScopedPointer overrides(loadOverrides(localPrefix, useAppIdForOverride));
724
725 return load(meta.data(), overrides.m_list);
726 }
727
728 bool load(QIODevice *meta, const QList<QIODevice*> &overrides) override
729 {
730 {
731 const QJsonDocument &doc = loadJsonFile(meta);
732 if (!doc.isObject())
733 return false;
734
735 // 检查标识
736 const QJsonObject &root = doc.object();
737 if (!checkMagic(root, MAGIC_META)) {
738 qCWarning(cfLog, "The meta magic does not match");
739 return false;
740 }
741
742 // 检查版本兼容性
743 const auto &v = parseVersion(root);
744 if (!versionIsValid(v) || v.major > DConfigFile::supportedVersion().major) {
745 qCWarning(cfLog, "The meta version number does not match, "
746 "the file major version=%i, supported major version<=%i",
747 v.major, DConfigFile::supportedVersion().major);
748 return false;
749 }
750
751 m_version = v;
752
753 const auto &contents = root[QLatin1String("contents")].toObject();
754 auto i = contents.constBegin();
755
756 // 初始化原始值
757 for (; i != contents.constEnd(); ++i) {
758 if (!values.update(i.key(), i.value().toObject().toVariantHash())) {
759 qWarning() << "key:" << i.key() << "has no value";
760 return false;
761 }
762 }
763 }
764 // for override
765 Q_FOREACH(auto override, overrides) {
766 const QJsonDocument &doc = loadJsonFile(override);
767 if (doc.isObject()) {
768 const QJsonObject &root = doc.object();
769 if (!checkMagic(root, MAGIC_OVERRIDE)) {
770 if (auto file = static_cast<QFile*>(override)) {
771 qCWarning(cfLog, "The override magic does not match, file: \"%s\", error message: \"%s\"",
772 qPrintable(file->fileName()), qPrintable(file->errorString()));
773 } else {
774 qCWarning(cfLog, "The override magic does not match");
775 }
776 break; //TODO don't continue parse?
777 }
778 if (!checkVersion(root, m_version)) {
779 qCWarning(cfLog, "The override version number does not match");
780 break;
781 }
782
783 if (auto file = static_cast<QFile*>(override)) {
784 qCDebug(cfLog, "The override will be applied, file: \"%s\"", qPrintable(file->fileName()));
785 }
786
787 const auto &contents = root[QLatin1String("contents")].toObject();
788 auto i = contents.constBegin();
789
790 for (; i != contents.constEnd(); ++i) {
791 if (!values.contains(i.key())) {
792 qCWarning(cfLog, "The meta doesn't contain the override key: \"%s\".", qPrintable(i.key()));
793 continue;
794 }
795 // 检查是否允许 override
796 if (values.flags(i.key()) & DConfigFile::NoOverride)
797 continue;
798
799 if (!values.updateValue(i.key(), i.value())) {
800 qWarning() << "key (override):" << i.key() << "has no value";
801 return false;
802 }
803 values.updateSerial(i.key(), i.value());
804 values.updatePermissions(i.key(), i.value());
805 }
806 }
807 }
808
809 return true;
810 }
811 /*!
812 @~english
813 \internal
814
815 @brief 获得前缀为 \a prefix 目录的应用或公共库的所有覆盖机制目录,越后优先级越高
816 */
817 inline QStringList overrideDirs(const QString & prefix, bool useAppId) const {
818 const QString &path2 = QString("%1/etc/dsg/configs/overrides/%2/%3")
819 .arg(prefix, useAppId ? configKey.appId : QString(), configKey.fileName);
820
821 QStringList paths;
822 const QStringList &dataPaths = DStandardPaths::paths(DStandardPaths::DSG::DataDir);
823 paths.reserve(dataPaths.size() + 1);
824 for (auto path: dataPaths) {
825 // reverse `DataDir`'s paths, previous `DataDir`'s value has high priority
826 paths.prepend(QString("%1%2/configs/overrides/%3/%4")
827 .arg(prefix, path, useAppId ? configKey.appId : QString(), configKey.fileName));
828 }
829 // 在后面的优先级更高
830 paths.append(path2);
831 return paths;
832 }
833
834 inline QStringList allOverrideDirs(const bool useAppId, const QString &prefix) const override
835 {
836 QStringList dirs;
837 // 只有当允许不使用 appid 时才能回退到通用目录
838 if (!useAppId) {
839 dirs << overrideDirs(prefix, false);
840 }
841 // 无论如何都先从带 appid 的目录下加载override文件
842 // 在列表后面的更优先
843 dirs << overrideDirs(prefix, true);
844 return dirs;
845 }
846 /*!
847 @~english
848 \internal
849
850 @brief 获得所有遵守覆盖机制的文件流
851
852 在override文件放置路径下按优先级查找覆盖文件,支持子目录查找机制,
853 使用自然排序(如“a2”在“a11”之前)规则按文件名进行排序
854 */
855 QList<QIODevice *> loadOverrides(const QString &prefix, bool useAppId) const
856 {
857 auto filters = QDir::Files | QDir::NoDotAndDotDot | QDir::Readable;
858 const QStringList nameFilters {"*" + FILE_SUFFIX};
859
860 QStringList dirs = allOverrideDirs(useAppId, prefix);
861
862 QList<QIODevice*> list;
863 list.reserve(50);
864 QCollator collator(QLocale::English);
865 collator.setNumericMode(true);
866 collator.setIgnorePunctuation(true);
867
868 Q_FOREACH(const auto &dir, dirs) {
869 const QDir base_dir(QDir::cleanPath(dir));
870
871 if (!base_dir.exists())
872 continue;
873
874 if (!subpathIsValid(configKey.subpath, base_dir))
875 continue;
876
877 QDir target_dir = base_dir;
878 target_dir.setFilter(filters);
879 target_dir.setNameFilters(nameFilters);
880
881 if (!configKey.subpath.isEmpty())
882 target_dir.cd(configKey.subpath.mid(1));
883
884 do {
885 qCDebug(cfLog, "load override file from: \"%s\"", qPrintable(target_dir.path()));
886
887 QDirIterator iterator(target_dir);
888 QList<QIODevice*> sublist;
889 sublist.reserve(50);
890 while(iterator.hasNext()) {
891 sublist.append(new QFile(iterator.next()));
892 }
893
894 // 从小到大排序
895 std::sort(sublist.begin(), sublist.end(), [&collator](QIODevice *f1, QIODevice *f2){
896 if (collator.compare(static_cast<const QFile*>(f1)->fileName(),
897 static_cast<const QFile*>(f2)->fileName()) < 0)
898 return true;
899 return false;
900 });
901
902 list = sublist + list;
903
904 if (base_dir.path() == target_dir.path())
905 break;
906 } while (target_dir.cdUp());
907 }
908
909 return list;
910 }
911
912 DConfigKey configKey;
913 DConfigInfo values;
914 DConfigFile::Version m_version = {0, 0};
915 char padding [4] = {};
916 };
917
918 DConfigMetaImpl::DConfigMetaImpl(const DConfigKey &configKey)
919 : DConfigMeta (),
920 configKey(configKey)
921 {
922 }
923
924 DConfigMetaImpl::~DConfigMetaImpl()
925 {
926 }
927
928 /*!
929 @~english
930 @class Dtk::Core::DConfigCache
931 \inmodule dtkcore
932
933 @brief Provides user and global runtime cache access interfaces for Configuration file.
934
935 */
936
937 /*!
938 @~english
939 @fn bool DConfigCache::load(const QString &localPrefix = QString()) = 0;
940 @brief Parse the cache configuration file
941 @return
942 */
943
944 /*!
945 @~english
946 @fn bool DConfigCache::save(const QString &localPrefix = QString(), QJsonDocument::JsonFormat format = QJsonDocument::Indented, bool sync = false) = 0;
947 @brief Save the cached value to disk
948 \a localPrefix Directory prefix
949 \a format Save format
950 \a sync Whether to refresh immediately
951 @return
952 */
953
954 /*!
955 @~english
956 @fn bool DConfigCache::isGlobal() const = 0;
957 @brief Whether to cache globally
958 @return
959 */
960
961 /*!
962 @~english
963 @fn void DConfigCache::remove(const QString &key) = 0;
964 @brief Delete a configuration entry from the cache
965 \a key Configuration name
966 @return
967 */
968
969 /*!
970 @~english
971 @fn QStringList DConfigCache::keyList() const = 0;
972 @brief Returns all configuration items for the configuration content
973 @return
974 */
975
976 /*!
977 @~english
978 @fn bool DConfigCache::setValue(const QString &key, const QVariant &value, const int serial, const uint uid, const QString &callerAppid) = 0;
979 @brief Sets the value in the cache
980 \a key Configuration name
981 \a value Configuration name
982 \a uid User Id at setup time
983 \a callerAppid Application id at setup time
984 @return A value of true indicates that the new value has been reset, and false indicates that it has not been set
985 */
986
987 /*!
988 @~english
989 @fn QVariant DConfigCache::value(const QString &key) const = 0;
990 @brief Get the value in the cache
991 \a key Configuration name
992 @return
993 */
994
995 /*!
996 @~english
997 @fn int DConfigCache::serial(const QString &key) const = 0;
998 @brief Returns a monotonically increasing value of a configuration item
999 \a key Configuration name
1000 @return An invalid value of -1 indicates that the entry is not configured
1001 */
1002
1003 /*!
1004 @~english
1005 @fn uint DConfigCache::uid() const = 0;
1006 @brief User identification, when used in the global cache, uid is a specific value for non-user identification
1007 @return
1008 */
1009
1010 /*!
1011 @~english
1012 @fn void setCachePathPrefix(const QString &prefix) = 0;
1013 @brief Set cache's prefix path, it's access permissions is considered by caller,
1014 and it needs to distinguish the paths of different caches by caller.
1015 @param prefix cache's prefix path.
1016 */
1017
1018 class Q_DECL_HIDDEN DConfigCacheImpl : public DConfigCache {
1019 public:
1020 DConfigCacheImpl(const DConfigKey &configKey, const uint uid, bool global);
1021 virtual ~DConfigCacheImpl() override;
1022
1023 // DConfigCache interface
1024 public:
1025 inline virtual int serial(const QString &key) const override
1026 {
1027 return values.serial(key);
1028 }
1029
1030 inline virtual uint uid() const override
1031 {
1032 return userid;
1033 }
1034
1035 inline virtual QStringList keyList() const override
1036 {
1037 return values.keyList();
1038 }
1039
1040 inline QString applicationCacheDir(const QString &localPrefix, const QString &suffix) const
1041 {
1042 QString prefix(cachePrefix);
1043 if (prefix.isEmpty()) {
1044 // If target user is current user or system user, then get the home path by environment variable first.
1045 QString homePath;
1046 if (userid == InvalidUID || (getuid() == userid)) {
1047 homePath = DStandardPaths::homePath();
1048 } else {
1049 homePath = DStandardPaths::homePath(getuid());
1050 }
1051
1052 if (homePath.isEmpty())
1053 return QString();
1054
1055 // fallback to default application cache directory.
1056 prefix = homePath + QStringLiteral("/.config/dsg/configs");
1057 }
1058 return QDir::cleanPath(QString("%1/%2/%3").arg(localPrefix, prefix + suffix, configKey.appId));
1059 }
1060
1061 inline QString applicationCacheDir(const QString &localPrefix) const
1062 {
1063 return applicationCacheDir(localPrefix, QString());
1064 }
1065
1066 inline QString cacheDir(const QString &basePath) {
1067 QDir dir(basePath + configKey.subpath);
1068 return dir.filePath(configKey.fileName + FILE_SUFFIX);
1069 }
1070
1071 inline QString globalCacheDir(const QString &localPrefix) const {
1072 QString prefix(cachePrefix);
1073 if (prefix.isEmpty()) {
1074 // TODO `DSG_APP_DATA` is not set and `appid` is not captured in `DStandardPaths::path`.
1075 QString appDataDir = DStandardPaths::path(DStandardPaths::DSG::AppData);
1076 if (appDataDir.isEmpty()) {
1077 #ifdef D_DSG_APP_DATA_FALLBACK
1078 appDataDir = QStringLiteral(D_DSG_APP_DATA_FALLBACK);
1079 QFileInfo tmp(appDataDir);
1080 if (!tmp.exists() && !tmp.isSymLink() && !QDir::current().mkpath(appDataDir)) {
1081 qCDebug(cfLog, "Not found a valid DSG_APP_DATA directory");
1082 return QString();
1083 }
1084 #else
1085 return QString();
1086 #endif
1087 }
1088 // fallback to default global cache directory.
1089 prefix = QString("%1/configs").arg(appDataDir);
1090 }
1091
1092 return QDir::cleanPath(QString("%1/%2/%3").arg(localPrefix, prefix, configKey.appId));
1093 }
1094
1095 QString getCacheDir(const QString &localPrefix = QString())
1096 {
1097 if (isGlobal()) {
1098 const QString &dir = globalCacheDir(localPrefix);
1099 if (!dir.isEmpty())
1100 return dir;
1101
1102 // Not supported the global config, fallback the config cache data to user directory.
1103 return applicationCacheDir(localPrefix, "-fake-global");
1104 } else {
1105 return applicationCacheDir(localPrefix);
1106 }
1107 }
1108
1109 bool load(const QString &localPrefix = QString()) override;
1110
1111 bool isGlobal() const override
1112 {
1113 return global;
1114 }
1115
1116 inline void remove(const QString &key) override
1117 {
1118 values.remove(key);
1119 cacheChanged = true;
1120 }
1121 bool setValue(const QString &key, const QVariant &value, const int serial, const uint uid, const QString &appid) override
1122 {
1123 if (values.value(key) == value) {
1124 return false;
1125 }
1126 values.setValue(key, value);
1127 values.setSerial(key, serial);
1128 values.setTime(key, QDateTime::currentDateTime().toString(Qt::ISODate));
1129 values.setUser(key, uid);
1130 values.setAppId(key, appid.isEmpty() ? configKey.appId : appid);
1131 cacheChanged = true;
1132 return true;
1133 }
1134
1135 inline QVariant value(const QString &key) const override
1136 {
1137 return values.value(key);
1138 }
1139
1140 bool save(const QString &localPrefix, QJsonDocument::JsonFormat format, bool sync) override;
1141
1142 virtual void setCachePathPrefix(const QString &prefix) override
1143 {
1144 cachePrefix = prefix;
1145 }
1146
1147 DConfigKey configKey;
1148 DConfigInfo values;
1149 QString cachePrefix;
1150 uint userid;
1151 bool global;
1152 bool cacheChanged = false;
1153 };
1154
1155 DConfigCacheImpl::DConfigCacheImpl(const DConfigKey &configKey, const uint uid, bool global)
1156 : DConfigCache(),
1157 configKey(configKey),
1158 userid(uid),
1159 global(global)
1160 {
1161 }
1162
1163 DConfigCacheImpl::~DConfigCacheImpl()
1164 {
1165 }
1166
1167 bool DConfigCacheImpl::load(const QString &localPrefix)
1168 {
1169 // cache 文件要严格匹配 subpath
1170 const QString &dir = getCacheDir(localPrefix);
1171 if (dir.isEmpty()) {
1172 return true;
1173 }
1174 QScopedPointer<QFile> cache(loadFile(dir,
1175 configKey.subpath,
1176 configKey.fileName + FILE_SUFFIX,
1177 false));
1178 if (!cache) {
1179 return true;
1180 }
1181
1182 const QJsonDocument &doc = loadJsonFile(cache.data());
1183
1184 if (doc.isObject()) {
1185 const QJsonObject &root = doc.object();
1186 if (!checkMagic(root, MAGIC_CACHE))
1187 return false;
1188 if (!checkVersion(root, DConfigFile::supportedVersion()))
1189 return false;
1190
1191 auto &&contents = root[QLatin1String("contents")].toObject();
1192 auto i = contents.constBegin();
1193
1194 // 原样保存原始数据
1195 for (; i != contents.constEnd(); ++i) {
1196 values.update(i.key(), i.value().toObject().toVariantHash());
1197 }
1198 }
1199 return true;
1200 }
1201
1202 bool DConfigCacheImpl::save(const QString &localPrefix, QJsonDocument::JsonFormat format, bool sync)
1203 {
1204 if (!cacheChanged)
1205 return true;
1206
1207 cacheChanged = false;
1208 const QString &dir = getCacheDir(localPrefix);
1209 if (dir.isEmpty()) {
1210 qCWarning(cfLog, "Falied on saveing, the config cache directory is empty for the user[%d], "
1211 "the current user[%d].", userid, getuid());
1212 return false;
1213 }
1214 QString path = cacheDir(dir);
1215
1216 QFile cache(path);
1217 if (!QFile::exists(QFileInfo(cache.fileName()).path())) {
1218 QDir().mkpath(QFileInfo(cache.fileName()).path());
1219 }
1220
1221 if (!cache.open(QIODevice::WriteOnly)) {
1222 qCWarning(cfLog, "Falied on saveing data when open file: \"%s\", error message: \"%s\"",
1223 qPrintable(cache.fileName()), qPrintable(cache.errorString()));
1224 return false;
1225 }
1226
1227 qCDebug(cfLog, "Save cache file \"%s\".", qPrintable(cache.fileName()));
1228
1229 QJsonObject root;
1230
1231 root[QLatin1String("magic")] = MAGIC_CACHE;
1232 const DConfigFile::Version version = DConfigFile::supportedVersion();
1233 root[QLatin1String("version")] = QString("%1.%2").arg(version.major)
1234 .arg(version.minor);
1235
1236 root[QLatin1String("contents")] = values.content();
1237 QJsonDocument doc;
1238 doc.setObject(root);
1239 const QByteArray &json = doc.toJson(format);
1240
1241 bool status = cache.write(json) == json.size();
1242 if (status && sync) {
1243 cache.flush();
1244 }
1245 return status;
1246 }
1247
1248 class Q_DECL_HIDDEN DConfigFilePrivate : public DObjectPrivate {
1249 public:
1250 DConfigFilePrivate(DConfigFile *qq, const QString &appId,
1251 const QString &name, const QString &subpath)
1252 : DObjectPrivate(qq),
1253 configKey(appId, name ,subpath),
1254 configMeta(new DConfigMetaImpl(configKey))
1255 {
1256 }
1257 DConfigFilePrivate(DConfigFile *qq, const DConfigKey &configKey)
1258 : DObjectPrivate(qq),
1259 configKey(configKey),
1260 configMeta(new DConfigMetaImpl(configKey))
1261 {
1262 }
1263
1264 ~DConfigFilePrivate() override;
1265
1266 bool load(const QString &localPrefix)
1267 {
1268 bool status = configMeta->load(localPrefix);
1269 if (status) {
1270 // for cache
1271 status &= globalCache->load(localPrefix);
1272 }
1273 return status;
1274 }
1275 bool setValue(const QString &key, const QVariant &value,
1276 DConfigCache *userCache, const QString &appid)
1277 {
1278 // 此处不要检查权限,在获取 value 时会检查
1279 if (auto cache = getCache(key, userCache)) {
1280 if (!value.isValid()) {
1281 cache->remove(key);
1282 return true;
1283 } else {
1284 const auto &metaValue = configMeta->value(key);
1285 // sample judgement to reduce a copy of convert.
1286 #if QT_VERSION >= QT_VERSION_CHECK(6, 0, 0)
1287 if (metaValue.typeId() == value.typeId())
1288 return cache->setValue(key, value, configMeta->serial(key), cache->uid(), appid);
1289
1290 // convert copy to meta's type, it promises `setValue` don't change meta's type.
1291 // canConvert isn't explicit, e.g: QString is also can convert to double.
1292 auto copy = value;
1293 if (!copy.convert(metaValue.metaType())) {
1294 qCWarning(cfLog) << "check type error, meta type is " << metaValue.metaType().name()
1295 << ", and now type is " << value.metaType().name();
1296 return false;
1297 }
1298
1299 // TODO it's a bug of qt, MetaType of 1.0 is qlonglong instead of double in json file.
1300 static const QVector<QMetaType> filterConvertType {
1301 QMetaType{QMetaType::Double}
1302 };
1303 // reset to origin value.
1304 if (filterConvertType.contains(value.metaType())) {
1305 copy = value;
1306 }
1307 #else
1308 if (metaValue.type() == value.type())
1309 return cache->setValue(key, value, configMeta->serial(key), cache->uid(), appid);
1310
1311 auto copy = value;
1312 if (!copy.convert(metaValue.userType())) {
1313 qCWarning(cfLog) << "check type error, meta type is " << metaValue.type()
1314 << ", and now type is " << value.type();
1315 return false;
1316 }
1317
1318 static const QVector<QVariant::Type> filterConvertType {
1319 QVariant::Double
1320 };
1321 if (filterConvertType.contains(value.type())) {
1322 copy = value;
1323 }
1324 #endif
1325
1326 return cache->setValue(key, copy, configMeta->serial(key), cache->uid(), appid);
1327 }
1328 }
1329 return false;
1330 }
1331 DConfigCache* getCache(const QString &key, DConfigCache *userCache) const
1332 {
1333 if(configMeta->flags(key).testFlag(DConfigFile::Global)) {
1334 return globalCache;
1335 }
1336 return userCache;
1337 }
1338 QVariant cacheValue(DConfigCache *userCache, const QString &key) const
1339 {
1340 // 检查权限
1341 if (configMeta->permissions(key) != DConfigFile::ReadOnly) {
1342 if (auto cache = getCache(key, userCache)) {
1343 if (DConfigInfo::checkSerial(configMeta->serial(key), cache->serial(key))) {
1344 const QVariant &tmp = cache->value(key);
1345 if (tmp.isValid())
1346 return tmp;
1347 }
1348 }
1349 }
1350 return QVariant();
1351 }
1352 QVariant value(const QString &key, DConfigCache *userCache) const
1353 {
1354 const QVariant &v = cacheValue(userCache, key);
1355 if (v.isValid())
1356 return v;
1357 return configMeta->value(key);
1358 }
1359
1360 D_DECLARE_PUBLIC(DConfigFile)
1361
1362 private:
1363 DConfigCacheImpl* globalCache;
1364 DConfigKey configKey;
1365 DConfigMeta *configMeta;
1366 };
1367
1368 DConfigFilePrivate::~DConfigFilePrivate()
1369 {
1370 if (globalCache) {
1371 delete globalCache;
1372 globalCache = nullptr;
1373 }
1374 if (configMeta) {
1375 delete configMeta;
1376 configMeta = nullptr;
1377 }
1378 }
1379
1380 /*!
1381 @~english
1382 @brief Supported versions
1383 @return
1384 */
1385 constexpr DConfigFile::Version DConfigFile::supportedVersion()
1386 {
1387 return DConfigFile::Version{1, 0};
1388 }
1389
1390 /*!
1391 @~english
1392 @brief 构造配置文件管理对象
1393 \a appId Application unique identification
1394 \a name Config filename
1395 \a subpath Subdirectories
1396 */
1397 DConfigFile::DConfigFile(const QString &appId, const QString &name, const QString &subpath)
1398 : DObject(*new DConfigFilePrivate(this, appId, name, subpath))
1399 {
1400 D_D(DConfigFile);
1401 d->globalCache = new DConfigCacheImpl(d->configKey, InvalidUID, true);
1402 }
1403
1404 DConfigFile::DConfigFile(const DConfigFile &other)
1405 : DObject(*new DConfigFilePrivate(this, other.d_func()->configKey))
1406 {
1407 D_D(DConfigFile);
1408 auto cache = new DConfigCacheImpl(d->configKey, InvalidUID, true);
1409 cache->values = other.d_func()->globalCache->values;
1410 d->globalCache = cache;
1411 }
1412
1413 /*!
1414 @~english
1415 @brief Parse configuration files
1416 \a localPrefix Directory prefix
1417 @return
1418 */
1419 bool DConfigFile::load(const QString &localPrefix)
1420 {
1421 D_D(DConfigFile);
1422 return d->load(localPrefix);
1423 }
1424
1425 /*!
1426 @~english
1427 @brief Parse the profile stream
1428 \a meta Prototype stream
1429 \a overrides File stream to find for the override mechanism
1430 @return
1431 */
1432 bool DConfigFile::load(QIODevice *meta, const QList<QIODevice *> &overrides)
1433 {
1434 return this->meta()->load(meta, overrides);
1435 }
1436
1437 /*!
1438 @~english
1439 @brief Save the cached value to disk
1440 \a format Save format
1441 \a sync Whether to refresh immediately
1442 @return
1443 */
1444 bool DConfigFile::save(const QString &localPrefix, QJsonDocument::JsonFormat format, bool sync) const
1445 {
1446 D_DC(DConfigFile);
1447
1448 bool ok = d->globalCache->save(localPrefix, format, sync);
1449
1450 return ok;
1451 }
1452
1453 /*!
1454 @~english
1455 * @brief DConfigFile::value
1456 * @param key Configuration name
1457 * @param userCache Specific user cache, \a userCache is unused when the key is global
1458 * @return
1459 */
1460 QVariant DConfigFile::value(const QString &key, DConfigCache *userCache) const
1461 {
1462 D_DC(DConfigFile);
1463 return d->value(key, userCache);
1464 }
1465
1466 /*!
1467 * \brief DConfigFile::cacheValue Get a specific user cache's value
1468 * \param userCache Specific user cache, it is unused if the \a key is global configuration item
1469 * \param key Configuration name
1470 * \return
1471 */
1472 QVariant DConfigFile::cacheValue(DConfigCache *userCache, const QString &key) const
1473 {
1474 D_DC(DConfigFile);
1475 return d->cacheValue(userCache, key);
1476 }
1477
1478 /*!
1479 @~english
1480 @brief Sets the value in the cache
1481 \a key Configuration name
1482 \a value The value to set
1483 \a userCache Specific user cache at setup time
1484 \a appid Application id at setup time
1485 @return A value of true indicates that the new value has been reset, and false indicates that it has not been set
1486 */
1487 bool DConfigFile::setValue(const QString &key, const QVariant &value, const QString &callerAppid, DConfigCache *userCache)
1488 {
1489 D_D(DConfigFile);
1490 return d->setValue(key, value, userCache, callerAppid);
1491 }
1492
1493 DConfigCache *DConfigFile::createUserCache(const uint uid)
1494 {
1495 D_D(DConfigFile);
1496 return new DConfigCacheImpl(d->configKey, uid, false);
1497 }
1498
1499
1500 /*!
1501 @~english
1502 @brief Return to the global cache
1503 @return
1504 */
1505 DConfigCache *DConfigFile::globalCache() const
1506 {
1507 D_DC(DConfigFile);
1508 return d->globalCache;
1509 }
1510
1511 /*!
1512 @~english
1513 @brief Return the prototype object
1514 @return
1515 */
1516 DConfigMeta *DConfigFile::meta()
1517 {
1518 D_D(DConfigFile);
1519 return d->configMeta;
1520 }
1521
1522 /*!
1523 @~english
1524 @brief Checks whether the configuration file is valid
1525 @return
1526 */
1527 bool DConfigFile::isValid() const
1528 {
1529 D_DC(DConfigFile);
1530 return versionIsValid(d->configMeta->version());
1531 }
1532
1533 DCORE_END_NAMESPACE