vaikene.ee Git - evaf/blob - 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