vaikene.ee Git - evaf/blob - src/libs/Common/iregistry.h

   1 /**
   2  * @file Common/iregistry.h
   3  * @brief Common registry for interfaces
   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_IREGISTRY_H
  21 #define __COMMON_IREGISTRY_H
  22
  23 #include "libcommon.h"
  24
  25 #include <QObject>
  26 #include <QString>
  27
  28 namespace eVaf {
  29 namespace Common {
  30
  31 /**
  32  * Common registry for interfaces.
  33  * @code#include <Common/iRegistry>@endcode
  34  *
  35  * Registry is a central collection of all the eVaf interfaces and iRegistry the interface for it.
  36  * Modules use the iRegistry interface to register new interfaces and query existing ones.
  37  *
  38  * Existing interfaces are queried with the queryInterface() function. The returned pointer to QObject
  39  * shall be type casted to the requested interface class using qobject_cast<>():
  40  * @code
  41  * iEnv * env = qobject_cast<iEnv *>(iRegistry::instance()->queryInterface("iEnv"));
  42  * @endcode
  43  *
  44  * Or use the evafQueryInterface<>() function:
  45  * @code
  46  * iEnv * env = evafQueryInterface<iEnv>("iEnv");
  47  * @endcode
  48  *
  49  * Registering new interfaces is done with the registerInterface() function as shown in the following example:
  50  * @code
  51  * iRegistry::instance()->registerInterface("iSample", this);
  52  * @endcode
  53  *
  54  * In general, every interface should have a unique name. If an interface is registered with a name that already
  55  * exists, then the new interface overwrites the old interface with the same name. To reimplement an interface,
  56  * query for the old implementation, store it and then register a new interface with the same name.
  57  *
  58  * Any class implementing an interface shall have QObject as their top-most parent.
  59  *
  60  * <b>iRegistry and instance() functions</b>
  61  *
  62  * Most of the interfaces have the instance() function that returns the current instance of the interface.
  63  * The main difference is that by using the instance() function, modules shall link against the module
  64  * that implements the interface's instance() function. The iRegistry interface can be used to get the same
  65  * interface without knowing the module that implements it.
  66  */
  67 class COMMON_EXPORT iRegistry : public QObject
  68 {
  69     Q_OBJECT
  70
  71 public:
  72
  73     /// Interface constructor
  74     iRegistry() : QObject() {}
  75
  76     /// Empty virtual destructor
  77     virtual ~iRegistry() {}
  78
  79     /**
  80      * Returns the iRegistry interface instance
  81      * @return The iRegistry interface
  82      *
  83      * This function returns the global iRegistry interface instance. All eVaf modules and applications
  84      * are expected to be linked against the common library and this is the only method of obtaining
  85      * the iRegistry interface.
  86      */
  87     static iRegistry * instance();
  88
  89     /**
  90      * Registers an interface
  91      * @param name Name of the interface
  92      * @param obj Object implementing the interface
  93      * @return True if ok; false if registering failed
  94      *
  95      * This function registers a new interface in the global registry of interfaces.
  96      *
  97      * If an interface with this name already exists, then the new interface implementation overwrites the old
  98      * implementation.
  99      */
 100     virtual bool registerInterface(QString const & name, QObject * obj) = 0;
 101
 102     /**
 103      * Returns the interface by its name
 104      * @param name Name of the interface
 105      * @return Interface implementation or NULL if not found.
 106      *
 107      * This function queries the global registry for the interface by its name. It returns a pointer
 108      * to the implementation of the interface or NULL if no such interface is found.
 109      *
 110      * Use the qobject_cast<>() function to type cast the returned pointer to the required interface class.
 111      * Always check for NULL in case there is a mismatch in interface versions or no such interface is found.
 112      */
 113     virtual QObject * queryInterface(QString const & name) const = 0;
 114
 115 };
 116
 117 } // namespace eVaf::Common
 118 } // namespace eVaf
 119
 120 /**
 121  * Helper function for querying interfaces
 122  * @param name Name of the requested interface
 123  * @return The requested interface or NULL if not found
 124  *
 125  * This function can be used to query interfaces from the global registry. It returns a properly
 126  * type-casted interface or NULL if the interface cannot be found or is of an invalid type.
 127  *
 128  * Example:
 129  * @code
 130  * iEnv * env = evafQueryInterface<iEnv>("iEnv");
 131  * if (env) {
 132  *     // Use the interface
 133  * }
 134  * @endcode
 135  */
 136 template<typename T>
 137 inline T * evafQueryInterface(QString const & name)
 138 {
 139     return qobject_cast<T *>(eVaf::Common::iRegistry::instance()->queryInterface(name));
 140 }
 141
 142 #endif // iregistry.h