]>
vaikene.ee Git - evaf/blob - iregistry.h
5966746cc34c8947908d51a34b5c008cab8bd102
2 * @file Common/iregistry.h
3 * @brief Common registry for interfaces
6 * Copyright (c) 2011 Enar Vaikene
8 * This file is part of the eVaf C++ cross-platform application development framework.
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.
16 * Alternatively, this file may be used in accordance with the Commercial License
17 * Agreement provided with the Software.
20 #ifndef __COMMON_IREGISTRY_H
21 #define __COMMON_IREGISTRY_H
23 #include "libcommon.h"
32 * Common registry for interfaces.
33 * @code#include <Common/iRegistry>@endcode
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.
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<>():
41 * iEnv * env = qobject_cast<iEnv *>(iRegistry::instance()->queryInterface("iEnv"));
44 * Or use the evafQueryInterface<>() function:
46 * iEnv * env = evafQueryInterface<iEnv>("iEnv");
49 * Registering new interfaces is done with the registerInterface() function as shown in the following example:
51 * iRegistry::instance()->registerInterface("iSample", this);
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.
58 * Any class implementing an interface shall have QObject as their top-most parent.
60 * <b>iRegistry and instance() functions</b>
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.
67 class COMMON_EXPORT iRegistry
: public QObject
73 /// Interface constructor
74 iRegistry() : QObject() {}
76 /// Empty virtual destructor
77 virtual ~iRegistry() {}
80 * Returns the iRegistry interface instance
81 * @return The iRegistry interface
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.
87 static iRegistry
* instance();
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
95 * This function registers a new interface in the global registry of interfaces.
97 * If an interface with this name already exists, then the new interface implementation overwrites the old
100 virtual bool registerInterface(QString
const & name
, QObject
* obj
) = 0;
103 * Returns the interface by its name
104 * @param name Name of the interface
105 * @return Interface implementation or NULL if not found.
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.
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.
113 virtual QObject
* queryInterface(QString
const & name
) const = 0;
117 } // namespace eVaf::Common
121 * Helper function for querying interfaces
122 * @param name Name of the requested interface
123 * @return The requested interface or NULL if not found
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.
130 * iEnv * env = evafQueryInterface<iEnv>("iEnv");
132 * // Use the interface
137 inline T
* evafQueryInterface(QString
const & name
)
139 return qobject_cast
<T
*>(eVaf::Common::iRegistry::instance()->queryInterface(name
));
142 #endif // iregistry.h