--- /dev/null
+/**
+ * @file Common/iregistry.h
+ * @brief Common registry for interfaces
+ * @author Enar Vaikene
+ *
+ * Copyright (c) 2011 Enar Vaikene
+ *
+ * This file is part of the eVaf C++ cross-platform application development framework.
+ *
+ * This file can be used under the terms of the GNU General Public License
+ * version 3.0 as published by the Free Software Foundation and appearing in
+ * the file LICENSE included in the packaging of this file. Please review the
+ * the following information to ensure the GNU General Public License version
+ * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
+ *
+ * Alternatively, this file may be used in accordance with the Commercial License
+ * Agreement provided with the Software.
+ */
+
+#ifndef __COMMON_IREGISTRY_H
+#define __COMMON_IREGISTRY_H
+
+#include "libcommon.h"
+
+#include <QObject>
+#include <QString>
+
+namespace eVaf {
+namespace Common {
+
+/**
+ * Common registry for interfaces.
+ * @code#include <Common/iRegistry>@endcode
+ *
+ * Registry is a central collection of all the eVaf interfaces and iRegistry the interface for it.
+ * Modules use the iRegistry interface to register new interfaces and query existing ones.
+ *
+ * Existing interfaces are queried with the queryInterface() function. The returned pointer to QObject
+ * shall be type casted to the requested interface class using qobject_cast<>():
+ * @code
+ * iEnv * env = qobject_cast<iEnv *>(iRegistry::instance()->queryInterface("iEnv"));
+ * @endcode
+ *
+ * Or use the evafQueryInterface<>() function:
+ * @code
+ * iEnv * env = evafQueryInterface<iEnv>("iEnv");
+ * @endcode
+ *
+ * Registering new interfaces is done with the registerInterface() function as shown in the following example:
+ * @code
+ * iRegistry::instance()->registerInterface("iSample", this);
+ * @endcode
+ *
+ * In general, every interface should have a unique name. If an interface is registered with a name that already
+ * exists, then the new interface overwrites the old interface with the same name. To reimplement an interface,
+ * query for the old implementation, store it and then register a new interface with the same name.
+ *
+ * Any class implementing an interface shall have QObject as their top-most parent.
+ *
+ * <b>iRegistry and instance() functions</b>
+ *
+ * Most of the interfaces have the instance() function that returns the current instance of the interface.
+ * The main difference is that by using the instance() function, modules shall link against the module
+ * that implements the interface's instance() function. The iRegistry interface can be used to get the same
+ * interface without knowing the module that implements it.
+ */
+class COMMON_EXPORT iRegistry : public QObject
+{
+ Q_OBJECT
+
+public:
+
+ /// Interface constructor
+ iRegistry() : QObject() {}
+
+ /// Empty virtual destructor
+ virtual ~iRegistry() {}
+
+ /**
+ * Returns the iRegistry interface instance
+ * @return The iRegistry interface
+ *
+ * This function returns the global iRegistry interface instance. All eVaf modules and applications
+ * are expected to be linked against the common library and this is the only method of obtaining
+ * the iRegistry interface.
+ */
+ static iRegistry * instance();
+
+ /**
+ * Registers an interface
+ * @param name Name of the interface
+ * @param obj Object implementing the interface
+ * @return True if ok; false if registering failed
+ *
+ * This function registers a new interface in the global registry of interfaces.
+ *
+ * If an interface with this name already exists, then the new interface implementation overwrites the old
+ * implementation.
+ */
+ virtual bool registerInterface(QString const & name, QObject * obj) = 0;
+
+ /**
+ * Returns the interface by its name
+ * @param name Name of the interface
+ * @return Interface implementation or NULL if not found.
+ *
+ * This function queries the global registry for the interface by its name. It returns a pointer
+ * to the implementation of the interface or NULL if no such interface is found.
+ *
+ * Use the qobject_cast<>() function to type cast the returned pointer to the required interface class.
+ * Always check for NULL in case there is a mismatch in interface versions or no such interface is found.
+ */
+ virtual QObject * queryInterface(QString const & name) const = 0;
+
+};
+
+} // namespace eVaf::Common
+} // namespace eVaf
+
+/**
+ * Helper function for querying interfaces
+ * @param name Name of the requested interface
+ * @return The requested interface or NULL if not found
+ *
+ * This function can be used to query interfaces from the global registry. It returns a properly
+ * type-casted interface or NULL if the interface cannot be found or is of an invalid type.
+ *
+ * Example:
+ * @code
+ * iEnv * env = evafQueryInterface<iEnv>("iEnv");
+ * if (env) {
+ * // Use the interface
+ * }
+ * @endcode
+ */
+template<typename T>
+inline T * evafQueryInterface(QString const & name)
+{
+ return qobject_cast<T *>(eVaf::Common::iRegistry::instance()->queryInterface(name));
+}
+
+#endif // iregistry.h
projects / evaf / blobdiff