X-Git-Url: https://vaikene.ee/gitweb/gitweb.cgi?a=blobdiff_plain;f=src%2Flibs%2FCommon%2Firegistry.h;fp=src%2Flibs%2FCommon%2Firegistry.h;h=5966746cc34c8947908d51a34b5c008cab8bd102;hb=688e916955a6b848dbbae1f65ae85a73593ed680;hp=0000000000000000000000000000000000000000;hpb=f049c1cab2a27a68b381d33da01af859e83a42cb;p=evaf

diff --git a/src/libs/Common/iregistry.h b/src/libs/Common/iregistry.h
new file mode 100644
index 0000000..5966746
--- /dev/null
+++ b/src/libs/Common/iregistry.h
@@ -0,0 +1,142 @@
+/**
+ * @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