]> vaikene.ee Git - evaf/blob - src/libs/Common/iconfig.h
Documentation fixes and updates.
[evaf] / src / libs / Common / iconfig.h
1 /**
2 * @file Common/iconfig.h
3 * @brief eVaf configuration interface
4 * @author Enar Vaikene
5 *
6 * Copyright (c) 2011 Enar Vaikene
7 *
8 * This file is part of the eVaf C++ cross-platform application development framework.
9 *
10 * This file can be used under the terms of the GNU General Public License
11 * version 3.0 as published by the Free Software Foundation and appearing in
12 * the file LICENSE included in the packaging of this file. Please review the
13 * the following information to ensure the GNU General Public License version
14 * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
15 *
16 * Alternatively, this file may be used in accordance with the Commercial License
17 * Agreement provided with the Software.
18 */
19
20 #ifndef __COMMON_ICONFIG_H
21 # define __COMMON_ICONFIG_H
22
23 #include "libcommon.h"
24
25 #include <QObject>
26 #include <QString>
27 #include <QVariant>
28
29 namespace eVaf {
30 namespace Common {
31
32 /**
33 * eVaf configuration interface.
34 * @code#include <iConfig>@endcode
35 *
36 * The iConfig interface provides access to configuration parameters. Methods in this interface can be
37 * used to read and write configuration parameters.
38 *
39 * The default implementation of the iConfig interface uses INI files in the eVaf::Common::iApp::etcDir()
40 * directory. Additional configuration backends can be provided by re-implementing the interface.
41 *
42 * Configuration parameters are identified by a name in the following format:
43 * @verbatim [<backend:>][<file>]/<section>/<key> @endverbatim
44 *
45 * Where:
46 * @li \<backend:\> is an optional identifier for the configuration backend. This part is ignored by the default
47 * iConfig interface implementation and is reserved for custom modules. For example, a custom module could look
48 * for the 'db:' backend identifier and store parameters in a database. Any other requests would be forwarded to
49 * the default implementation.
50 * @li \<file\> is an optional configuration file name. The default iConfig interface implementation uses the file
51 * name part to locate the INI file in the eVaf::Common::iApp::etcDir() directory. If the file name part
52 * is '*' or empty, uses eVaf::Common::iApp::name() for the file name.
53 * @li \<section\> is the name of the section. Section names can contain extra '/' characters to build a structured
54 * tree of configuration sections.
55 * @li \<key\> is the name of the parameter.
56 *
57 * For example:
58 * @li 'db:local/extensions/help/module' - backend 'db:', file or database name 'local', section name 'extensions/help' and
59 * the key 'module';
60 * @li '/extensions/help/module' - default backend, default file name, section name 'extensions/help' and the key 'module'.
61 */
62 class COMMON_EXPORT iConfig : public QObject
63 {
64 Q_OBJECT
65
66 public:
67
68 /// Interface constructor
69 iConfig() : QObject() {}
70
71 /// Empty virtual destructor
72 virtual ~iConfig() {}
73
74 /**
75 * Returns the current iConfig interface instance
76 * @return The iConfig interface
77 *
78 * This method returns the current iConfig interface instance as shown in the following example:
79 * @code
80 * QString moduleName =
81 * eVaf::Common::iConfig::instance()->getValue("/extensions/help/module", "libHelp.so").toString();
82 * @endcode
83 */
84 static iConfig * instance();
85
86 /**
87 * Reads a configuration parameter value
88 * @param paramName Name of the parameter
89 * @param defaultValue Default value
90 * @return The parameter value or the default value if the parameter cannot be found
91 *
92 * The getValue() method returns a configuration parameter value identified by the parameter name. If the parameter
93 * cannot be read or is not found, returns the default value.
94 *
95 * The default value is used to determine the type of the value. For example, if the default value is an integer, then
96 * the returned value is also an integer. The default iConfig interface implementation validates parameter values and
97 * makes sure that the parameter value is of the proper type. If the value cannot be converted to the proper type,
98 * returns the default value. Other implementations of the iConfig interface are encouraged to do the same.
99 */
100 virtual QVariant getValue(QString const & paramName, QVariant const & defaultValue) const = 0;
101
102 /**
103 * Writes a configuration parameter value
104 * @param paramName Name of the parameter
105 * @param value The parameter value
106 * @param commit If true, then commits new parameter values
107 * @return True if succeeded; false if not
108 *
109 * The setValue() method writes new configuration parameter values identified by the parameter name.
110 *
111 * The commit argument can be used to improve the performance of writing several parameter values at once. Use
112 * commit = false for all except the last parameter's write operation.
113 * @code
114 * iConfig * conf = eVaf::Common::iConfig::instance();
115 * conf->setValue("/main/param1", 1, false);
116 * conf->setValue("/main/param2", 2, false);
117 * conf->setValue("/main/param3", 3); // Last parameter in the block
118 * @endcode
119 */
120 virtual bool setValue(QString const & paramName, QVariant const & value, bool commit = true) = 0;
121
122 };
123
124
125 } // namespace eVaf::Common
126 } // namespace eVaf
127
128 #endif // iconfig.h