From e6c2273668f1267da3b8363001f3cb8904af8642 Mon Sep 17 00:00:00 2001 From: Michael Zanetti Date: Sun, 26 Jan 2014 14:34:08 +0100 Subject: [PATCH] much moar docs --- doc/allmodules.qdoc | 10 ++++ doc/hive.qdoc | 4 +- doc/hivecore.qdoc | 7 +++ doc/hiveserver.qdoc | 17 ++++++ doc/jsonrpc.qdoc | 4 ++ doc/libhive.qdoc | 12 ++++ doc/server.qdoc | 9 --- libhive/action.cpp | 7 ++- libhive/actiontype.cpp | 14 +++++ libhive/device.cpp | 11 ++++ libhive/deviceclass.cpp | 44 ++++++++++---- libhive/deviceclass.h | 7 +-- libhive/devicemanager.cpp | 60 ++++++++++++++++++- libhive/deviceplugin.cpp | 53 +++++++++------- libhive/deviceplugin.h | 2 +- libhive/state.cpp | 6 +- libhive/statetype.cpp | 10 ++++ libhive/trigger.cpp | 11 +++- libhive/triggertype.cpp | 6 +- .../meisteranker/devicepluginmeisteranker.cpp | 3 +- server/hivecore.cpp | 7 +++ server/rule.cpp | 22 ++++++- server/ruleengine.cpp | 34 +++++++++++ 23 files changed, 304 insertions(+), 56 deletions(-) create mode 100644 doc/allmodules.qdoc create mode 100644 doc/hivecore.qdoc create mode 100644 doc/hiveserver.qdoc create mode 100644 doc/libhive.qdoc delete mode 100644 doc/server.qdoc diff --git a/doc/allmodules.qdoc b/doc/allmodules.qdoc new file mode 100644 index 00000000..86c5937e --- /dev/null +++ b/doc/allmodules.qdoc @@ -0,0 +1,10 @@ +/*! + \page allmodules.html + \title All Modules + + \table 80% + \row \li \l{libhive} \li Common data types and plugin interfaces + \row \li \l{Hive server} \li The Hive server daemon implementation + \endtable +*/ + diff --git a/doc/hive.qdoc b/doc/hive.qdoc index b7b0168f..8134ec94 100644 --- a/doc/hive.qdoc +++ b/doc/hive.qdoc @@ -6,12 +6,12 @@ The Hive backend service consists of three main modules: \list - \li libhive + \li \l{libhive} \list \li \l{Types}{Types used in the hive system} \li \l{Device Plugins}{The Device Plugin API} \endlist - \li Hive server + \li \l{Hive server} \list \li \l{Hive Core} \li \l{JSONRPC Interface} diff --git a/doc/hivecore.qdoc b/doc/hivecore.qdoc new file mode 100644 index 00000000..554aa762 --- /dev/null +++ b/doc/hivecore.qdoc @@ -0,0 +1,7 @@ +/*! + \page hivecore-index.html + \title Hive Core + + \annotatedlist core +*/ + diff --git a/doc/hiveserver.qdoc b/doc/hiveserver.qdoc new file mode 100644 index 00000000..a3de57b2 --- /dev/null +++ b/doc/hiveserver.qdoc @@ -0,0 +1,17 @@ +/*! + \module server + \title Hive server + The Hive server is the instance that communicates with the hardware and provides a JSONRPC interface + for communicating with the UI. It consists of those parts: + + \section3 Hive core + \annotatedlist core + + \section3 JSRONRPC Interface + \annotatedlist jsonrpc + + \section3 Rules Engine + \annotatedlist rules +*/ + + diff --git a/doc/jsonrpc.qdoc b/doc/jsonrpc.qdoc index e7e8e4bf..76174718 100644 --- a/doc/jsonrpc.qdoc +++ b/doc/jsonrpc.qdoc @@ -1,6 +1,10 @@ /*! \page jsonrpc.html \title JSONRPC Interface + \ingroup jsonrpc + + \brief The JSON RPC interface represents a TCP socket connection using plaintext string communication. + \section1 Description The JSON RPC interface represents a TCP socket connection using plaintext string communication. diff --git a/doc/libhive.qdoc b/doc/libhive.qdoc new file mode 100644 index 00000000..3d814b57 --- /dev/null +++ b/doc/libhive.qdoc @@ -0,0 +1,12 @@ +/*! + \module libhive + \title libhive + + \section1 Types + \annotatedlist types + + \section1 Device Plugins + \annotatedlist devices +*/ + + diff --git a/doc/server.qdoc b/doc/server.qdoc deleted file mode 100644 index 68e8dd22..00000000 --- a/doc/server.qdoc +++ /dev/null @@ -1,9 +0,0 @@ -/*! - \page server.html - \title Hive Server - \nextpage - The Hive server is the instance that communicates with the hardware and provides a JSONRPC interface - for communicating with the UI. - - -*/ diff --git a/libhive/action.cpp b/libhive/action.cpp index dc08bd87..23263d15 100644 --- a/libhive/action.cpp +++ b/libhive/action.cpp @@ -14,33 +14,38 @@ */ #include "action.h" +/*! Construct an Action with the given \a deviceId and \a actionTypeId */ Action::Action(const QUuid &deviceId, const QUuid &actionTypeId) : m_actionTypeId(actionTypeId), m_deviceId(deviceId) { } -/*! An Action is valid if \l{actionTypeId} and \l{deviceId} are valid uuids. */ +/*! An Action is valid if actionTypeId and deviceId are valid uuids. Returns true if valid, false if not. */ bool Action::isValid() const { return !m_actionTypeId.isNull() && !m_deviceId.isNull(); } +/*! Returns the actionTypeId for this Action */ QUuid Action::actionTypeId() const { return m_actionTypeId; } +/*! Returns the deviceId this Action is associated with.*/ QUuid Action::deviceId() const { return m_deviceId; } +/*! Returns the parameters for this Action.*/ QVariantMap Action::params() const { return m_params; } +/*! Set the the parameters for this Action. \a params must match the template in the \l{ActionType} referred by \l{Action::actionTypeId()}*/ void Action::setParams(const QVariantMap ¶ms) { m_params = params; diff --git a/libhive/actiontype.cpp b/libhive/actiontype.cpp index 2ec05fbf..965bb883 100644 --- a/libhive/actiontype.cpp +++ b/libhive/actiontype.cpp @@ -3,37 +3,51 @@ \brief Describes an \l{Action} for a \l{Device}. \ingroup types + \inmodule libhive + ActionTypes are contained in \l{DeviceClass} templates returned + by \l{DevicePlugin}{DevicePlugins} in order to describe the hardware supported + by the plugin. + + All Actions must have valid a ActionType in order to be usful. \sa Action */ #include "actiontype.h" +/*! Constructs an ActionType with the given \a id.*/ ActionType::ActionType(const QUuid &id): m_id(id) { } +/*! Returns the id of this ActionType.*/ QUuid ActionType::id() const { return m_id; } +/*! Returns the name of this ActionType */ QString ActionType::name() const { return m_name; } +/*! Set the \a name for this Action. This will be visible to to the user.*/ void ActionType::setName(const QString &name) { m_name = name; } +/*! Returns the parameter description of this ActionType. \l{Action}{Actions} created + from this ActionType must have their parameters matching to this template. */ QVariantList ActionType::parameters() const { return m_parameters; } +/*! Set the parameter description of this ActionType. \l{Action}{Actions} created + from this ActionType must have their \a parameters matching to this template. */ void ActionType::setParameters(const QVariantList ¶meters) { m_parameters = parameters; diff --git a/libhive/device.cpp b/libhive/device.cpp index 44563a24..33887429 100644 --- a/libhive/device.cpp +++ b/libhive/device.cpp @@ -33,51 +33,61 @@ Device::Device(const QUuid &pluginId, const QUuid &deviceClassId, QObject *paren } +/*! Returns the id of this Device. */ QUuid Device::id() const { return m_id; } +/*! Returns the deviceClassId of the associated \l{DeviceClass}. */ QUuid Device::deviceClassId() const { return m_deviceClassId; } +/*! Returns the id of the \l{DevicePlugin} this Device is managed by. */ QUuid Device::pluginId() const { return m_pluginId; } +/*! Returns the name of this Device. This is visible to the user. */ QString Device::name() const { return m_name; } +/*! Set the \a name for this Device. This is visible to the user.*/ void Device::setName(const QString &name) { m_name = name; } +/*! Returns the parameter of this Device. It must match the parameter description in the associated \l{DeviceClass}. */ QVariantMap Device::params() const { return m_params; } +/*! Sets the \a params of this Device. It must match the parameter description in the associated \l{DeviceClass}. */ void Device::setParams(const QVariantMap ¶ms) { m_params = params; } +/*! Returns the states of this Device. It must match the \l{StateType} description in the associated \l{DeviceClass}. */ QList Device::states() const { return m_states; } +/*! Sets the \a states of this Device. It must match the \l{StateType} description in the associated \l{DeviceClass}. */ void Device::setStates(const QList &states) { m_states = states; } +/*! For convenience, this finds the \l{State} matching the given \a stateTypeId and returns the current valie in this Device. */ QVariant Device::stateValue(const QUuid &stateTypeId) const { foreach (const State &state, m_states) { @@ -88,6 +98,7 @@ QVariant Device::stateValue(const QUuid &stateTypeId) const return QVariant(); } +/*! For convenience, this finds the \l{State} matching the given \a stateTypeId in this Device and sets the current value to \a value. */ void Device::setStateValue(const QUuid &stateTypeId, const QVariant &value) { for (int i = 0; i < m_states.count(); ++i) { diff --git a/libhive/deviceclass.cpp b/libhive/deviceclass.cpp index 122d1a32..b997829b 100644 --- a/libhive/deviceclass.cpp +++ b/libhive/deviceclass.cpp @@ -16,6 +16,11 @@ #include "deviceclass.h" +/*! Constructs a DeviceClass with the give \a pluginId and \a id. + When implementing a plugin, create a DeviceClass for each device you support. + Generate a new uuid (e.g. uuidgen) and hardode it into the plugin. The id + should never change or it will appear as a new DeviceClass in the system. + */ DeviceClass::DeviceClass(const QUuid &pluginId, const QUuid &id): m_id(id), m_pluginId(pluginId) @@ -23,76 +28,93 @@ DeviceClass::DeviceClass(const QUuid &pluginId, const QUuid &id): } -DeviceClass::~DeviceClass() -{ - -} - +/*! Returns the id of this DeviceClass. */ QUuid DeviceClass::id() const { return m_id; } +/*! Returns the pluginId this DeviceClass is managed by. */ QUuid DeviceClass::pluginId() const { return m_pluginId; } +/*! Returns true if this DeviceClass's id and pluginId are valid uuids. */ bool DeviceClass::isValid() const { return !m_id.isNull() && !m_pluginId.isNull(); } +/*! Returns the name of this DeviceClass's. This is visible to the user. */ QString DeviceClass::name() const { return m_name; } +/*! Set the \a name of this DeviceClass's. This is visible to the user. */ void DeviceClass::setName(const QString &name) { m_name = name; } +/*! Returns the statesTypes of this DeviceClass. \{Device}{Devices} created + from this DeviceClass must have their states matching to this template. */ QList DeviceClass::states() const { return m_states; } -void DeviceClass::setStates(const QList &states) +/*! Set the \a stateTypes of this DeviceClass. \{Device}{Devices} created + from this DeviceClass must have their states matching to this template. */ +void DeviceClass::setStates(const QList &stateTypes) { - m_states = states; + m_states = stateTypes; } +/*! Returns the triggerTypes of this DeviceClass. \{Device}{Devices} created + from this DeviceClass must have their triggers matching to this template. */ QList DeviceClass::triggers() const { return m_triggers; } -void DeviceClass::setTriggers(const QList &triggers) +/*! Set the \a triggerTypes of this DeviceClass. \{Device}{Devices} created + from this DeviceClass must have their triggers matching to this template. */ +void DeviceClass::setTriggers(const QList &triggerTypes) { - m_triggers = triggers; + m_triggers = triggerTypes; } +/*! Returns the actionTypes of this DeviceClass. \{Device}{Devices} created + from this DeviceClass must have their actions matching to this template. */ QList DeviceClass::actions() const { return m_actions; } -void DeviceClass::setActions(const QList &actions) +/*! Set the \a actionTypes of this DeviceClass. \{Device}{Devices} created + from this DeviceClass must have their actions matching to this template. */ +void DeviceClass::setActions(const QList &actionTypes) { - m_actions = actions; + m_actions = actionTypes; } +/*! Returns the params description of this DeviceClass. \{Device}{Devices} created + from this DeviceClass must have their params matching to this template. */ QVariantList DeviceClass::params() const { return m_params; } +/*! Set the \a params of this DeviceClass. \{Device}{Devices} created + from this DeviceClass must have their actions matching to this template. */ void DeviceClass::setParams(const QVariantList ¶ms) { m_params = params; } +/*! Compare this \a deviceClass to another. This is effectively the same as calling a.id() == b.id(). Returns true if the ids match.*/ bool DeviceClass::operator==(const DeviceClass &deviceClass) const { return m_id == deviceClass.id(); diff --git a/libhive/deviceclass.h b/libhive/deviceclass.h index f55313f1..6d0b20d7 100644 --- a/libhive/deviceclass.h +++ b/libhive/deviceclass.h @@ -12,7 +12,6 @@ class DeviceClass { public: DeviceClass(const QUuid &pluginId = QUuid(), const QUuid &id = QUuid()); - virtual ~DeviceClass(); QUuid id() const; QUuid pluginId() const; @@ -22,13 +21,13 @@ public: void setName(const QString &name); QList states() const; - void setStates(const QList &states); + void setStates(const QList &stateTypes); QList triggers() const; - void setTriggers(const QList &triggers); + void setTriggers(const QList &triggerTypes); QList actions() const; - void setActions(const QList &actions); + void setActions(const QList &actionTypes); QVariantList params() const; void setParams(const QVariantList ¶ms); diff --git a/libhive/devicemanager.cpp b/libhive/devicemanager.cpp index fe9899ed..e770fa9d 100644 --- a/libhive/devicemanager.cpp +++ b/libhive/devicemanager.cpp @@ -12,6 +12,49 @@ */ +/*! + \enum DeviceManager::HardwareResource + + This enum type specifies hardware resources which can be requested by \l{DevicePlugin}{DevicePlugins}. + + \value HardwareResourceNone + No Resource required. + \value HardwareResourceRadio433 + Refers to the 433 MHz radio. + \value HardwareResourceRadio868 + Refers to the 868 MHz radio. + \value HardwareResourceTimer + Refers to the global timer managed by the \l{DeviceManager}. Plugins should not create their own timers, but rather request the global timer using the hardware resources. +*/ + +/*! + \enum DeviceManager::DeviceError + + This enum type specifies the errors that can happen when working with \l{Device}{Devices}. + + \value DeviceErrorNoError + No Error. Everything went fine. + \value DeviceErrorDeviceNotFound + Couldn't find a \l{Device} for the given id. + \value DeviceErrorDeviceClassNotFound + Couldn't find a \l{DeviceClass} for the given id. + \value DeviceErrorActionTypeNotFound + Couldn't find the \l{ActionType} for the given id. + \value DeviceErrorMissingParameter + Parameters do not comply to the template. + \value DeviceErrorPluginNotFound + Couldn't find the Plugin for the given id. + \value DeviceErrorSetupFailed + Error setting up the \{Device}. It will not be functional. +*/ + +/*! \fn void DeviceManager::emitTrigger(const Trigger &trigger) + The DeviceManager will emit a \l{Trigger} described in \a trigger whenever a Device + creates one. Normally only \l{HiveCore} should connect to this and execute actions + after checking back with the \{RulesEngine}. Exceptions might be monitoring interfaces + or similar, but you should never directly react to this in a \l{DevicePlugin}. +*/ + #include "devicemanager.h" #include "radio433.h" @@ -31,7 +74,9 @@ Q_IMPORT_PLUGIN(DevicePluginIntertechno) Q_IMPORT_PLUGIN(DevicePluginMeisterAnker) Q_IMPORT_PLUGIN(DevicePluginWifiDetector) - +/*! Constructs the DeviceManager with the given \a parent. There should only be one DeviceManager in the system created by \l{HiveCore}. + Use \c HiveCore::instance()->deviceManager() instead to access the DeviceManager. +*/ DeviceManager::DeviceManager(QObject *parent) : QObject(parent), m_radio433(0) @@ -43,21 +88,26 @@ DeviceManager::DeviceManager(QObject *parent) : QMetaObject::invokeMethod(this, "loadConfiguredDevices", Qt::QueuedConnection); } +/*! Returns all the \l{DevicePlugin}{DevicePlugins} loaded in the system. */ QList DeviceManager::plugins() const { return m_devicePlugins.values(); } +/*! Returns the \{DevicePlugin} with the given \a id. Null if the id couldn't be found. */ DevicePlugin *DeviceManager::plugin(const QUuid &id) const { return m_devicePlugins.value(id); } +/*! Returns all the supported \l{DeviceClass}{DeviceClasses} by all \l{DevicePlugin}{DevicePlugins} loaded in the system. */ QList DeviceManager::supportedDevices() const { return m_supportedDevices.values(); } +/*! Add a new configured device for the given \l{DeviceClass} and the given parameters. + \a deviceClassId must refer to an existing \{DeviceClass} and \a params must match the parameter description in the \l{DeviceClass}. */ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const QUuid &deviceClassId, const QVariantMap ¶ms) { DeviceClass deviceClass = findDeviceClass(deviceClassId); @@ -94,6 +144,7 @@ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const QUuid &devic return DeviceErrorNoError; } +/*! Returns the \l{Device} with the given \a id. Null if the id couldn't be found. */ Device *DeviceManager::findConfiguredDevice(const QUuid &id) const { foreach (Device *device, m_configuredDevices) { @@ -104,11 +155,13 @@ Device *DeviceManager::findConfiguredDevice(const QUuid &id) const return 0; } +/*! Returns all configured \{Device}{Devices} in the system. */ QList DeviceManager::configuredDevices() const { return m_configuredDevices; } +/*! Returns all \l{Device}{Devices} matching the \l{DeviceClass} referred by \a deviceClassId. */ QList DeviceManager::findConfiguredDevices(const QUuid &deviceClassId) const { QList ret; @@ -120,6 +173,7 @@ QList DeviceManager::findConfiguredDevices(const QUuid &deviceClassId) return ret; } +/*! For conveninece, this returns the \{DeviceClass} that describes the \l{TriggerType} referred by \a triggerTypeId. */ DeviceClass DeviceManager::findDeviceClassforTrigger(const QUuid &triggerTypeId) const { foreach (const DeviceClass &deviceClass, m_supportedDevices) { @@ -132,6 +186,7 @@ DeviceClass DeviceManager::findDeviceClassforTrigger(const QUuid &triggerTypeId) return DeviceClass(QUuid(), QUuid()); } +/*! For conveninece, this returns the \{DeviceClass} with the id given by \a deviceClassId. */ DeviceClass DeviceManager::findDeviceClass(const QUuid &deviceClassId) const { foreach (const DeviceClass &deviceClass, m_supportedDevices) { @@ -142,6 +197,9 @@ DeviceClass DeviceManager::findDeviceClass(const QUuid &deviceClassId) const return DeviceClass(QUuid(), QUuid()); } +/*! Execute the given \{Action}. + This will find the \l{Device} \a action refers to in \l{Action::deviceId()} and + its \l{DevicePlugin}. Then will dispatch the execution to the \l{DevicePlugin}.*/ DeviceManager::DeviceError DeviceManager::executeAction(const Action &action) { foreach (Device *device, m_configuredDevices) { diff --git a/libhive/deviceplugin.cpp b/libhive/deviceplugin.cpp index 6e86da44..6f92cdcf 100644 --- a/libhive/deviceplugin.cpp +++ b/libhive/deviceplugin.cpp @@ -1,22 +1,15 @@ /*! - \class DevicePlugin - \brief This is the base class interface for device plugins. +\class DevicePlugin +\brief This is the base class interface for device plugins. - \ingroup devices - \inmodule libhive +\ingroup devices +\inmodule libhive - When implementing a new plugin, start by subclassing this and implementing the following - pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId()}, - \l{DevicePlugin::supportedDevices()} and \l{DevicePlugin::requiredHardware()} +When implementing a new plugin, start by subclassing this and implementing the following +pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId()}, +\l{DevicePlugin::supportedDevices()} and \l{DevicePlugin::requiredHardware()} */ -#include "deviceplugin.h" - -#include "devicemanager.h" -#include "radio433.h" - -#include - /*! \fn QString DevicePlugin::pluginName() const Return the name of the plugin. A String presented to the user. @@ -59,23 +52,42 @@ /*! \fn void DevicePlugin::emitTrigger(const Trigger &trigger) - Emit this to produce a \l{Trigger} in the system. Usually in response to incoming data, - such as \l{DevicePlugin::radioData()} or \l{DevicePlugin::hiveTimer()}. Find a - configured \l{Device} from the \l{DeviceManager} and get its \l{TriggerTypes}, then + To produce a new event in the system, create a new \l{Trigger} and emit it with \a trigger. + Usually triggers are emitted in response to incoming data or other other events happening, + such as \l{DevicePlugin::radioData()} or \l{DevicePlugin::hiveTimer()}. Find a configured + \l{Device} from the \l{DeviceManager} and get its \l{TriggerType}{TriggerTypes}, then create a \l{Trigger} complying to that \l{TriggerType} and emit it here. */ -DevicePlugin::DevicePlugin(): +/*! + \fn void DevicePlugin::init() + This will be called after constructing the DevicePlugin. Override this to do any + initialisation work you need to do. + */ + +#include "deviceplugin.h" + +#include "devicemanager.h" +#include "radio433.h" + +#include + +/*! DevicePlugin constructor. DevicePlugins will be instantiated by the DeviceManager, its \a parent. */ +DevicePlugin::DevicePlugin(QObject *parent): + QObject(parent), m_deviceManager(0) { } +/*! Virtual destructor... */ DevicePlugin::~DevicePlugin() { } +/*! This will be called when the DeviceManager initializes the plugin and set up the things behind the scenes. + When implementing a new plugin, use \l{DevicePlugin::init()} instead in order to do initialisation work. */ void DevicePlugin::initPlugin(DeviceManager *deviceManager) { m_deviceManager = deviceManager; @@ -93,7 +105,7 @@ QVariantMap DevicePlugin::configuration() const } /*! - Will be called by the DeviceManager to set a plugin's config. + Will be called by the DeviceManager to set a plugin's \a configuration. When implementing a new plugin, override this and react to configuration changes. @@ -117,7 +129,8 @@ DeviceManager *DevicePlugin::deviceManager() const } /*! - Transmits data on the Radio433 or Radio868 devices, depending on the hardware requested by this plugin. + Transmits data contained in \a rawData on the Radio433 or Radio868 + devices, depending on the hardware requested by this plugin. \sa DevicePlugin::requiredHardware() */ void DevicePlugin::transmitData(QList rawData) diff --git a/libhive/deviceplugin.h b/libhive/deviceplugin.h index 5f25cfc7..f4f7e7e8 100644 --- a/libhive/deviceplugin.h +++ b/libhive/deviceplugin.h @@ -15,7 +15,7 @@ class DevicePlugin: public QObject { Q_OBJECT public: - DevicePlugin(); + DevicePlugin(QObject *parent = 0); virtual ~DevicePlugin(); virtual void init() {} diff --git a/libhive/state.cpp b/libhive/state.cpp index d3a5cade..9f60e074 100644 --- a/libhive/state.cpp +++ b/libhive/state.cpp @@ -6,13 +6,15 @@ \inmodule libhive States hold the state values for devices. A State is associated to a \l{Device} by - the \l{Device::deviceId} {deviceId} and represents the value of a state described in a \l{StateType} + the \l{State::deviceId()} and represents the value of a state described in a \l{StateType} \sa StateType */ #include "state.h" +/*! Constructs a State reflecting the \l{StateType} given by \a stateTypeId + and associated with the \l{Device} given by \a deviceId */ State::State(const QUuid &stateTypeId, const QUuid &deviceId): m_stateTypeId(stateTypeId), m_deviceId(deviceId) @@ -31,11 +33,13 @@ QUuid State::deviceId() const return m_deviceId; } +/*! Returns the state's value.*/ QVariant State::value() const { return m_value; } +/*! Set the state's value to \a value.*/ void State::setValue(const QVariant &value) { m_value = value; diff --git a/libhive/statetype.cpp b/libhive/statetype.cpp index 004fa4d4..e4b6c353 100644 --- a/libhive/statetype.cpp +++ b/libhive/statetype.cpp @@ -10,41 +10,51 @@ #include "statetype.h" +/*! Constructs a State with the given \a id. + When creating a \l{DevicePlugin} generate a new uuid for each StateType you define and + hardcode it into the plugin. */ StateType::StateType(const QUuid &id): m_id(id) { } +/*! Returns the id of the StateType.*/ QUuid StateType::id() const { return m_id; } +/*! Returns the name of the StateType. This is visible to the user (e.g. "Temperature").*/ QString StateType::name() const { return m_name; } +/*! Set the name of the StateType to \a name. This is visible to the user (e.g. "Temperature").*/ void StateType::setName(const QString &name) { m_name = name; } +/*! Returns the Type of the StateType (e.g. QVariant::Real). */ QVariant::Type StateType::type() const { return m_type; } +/*! Set the type fo the StateType to \a type (e.g. QVariant::Real).*/ void StateType::setType(const QVariant::Type &type) { m_type = type; } +/*! Returns the default value of this StateType (e.g. 21.5) */ QVariant StateType::defaultValue() const { return m_defaultValue; } +/*! Set the default value of this StateType to \a defaultValue (e.g. 21.5). */ void StateType::setDefaultValue(const QVariant &defaultValue) { m_defaultValue = defaultValue; diff --git a/libhive/trigger.cpp b/libhive/trigger.cpp index 403ae640..dfadc272 100644 --- a/libhive/trigger.cpp +++ b/libhive/trigger.cpp @@ -10,11 +10,14 @@ The params must match the template as described in \l{TriggerType}. - \sa Device TriggerType + \sa Device, TriggerType */ #include "trigger.h" +/*! Constructs a Trigger reflecting the \l{Trigger} given by \a triggerTypeId, associated with + the \l{Device} given by \a deviceId and the parameters given by \a params. The parameters must + match the description in the reflecting \l{Trigger}.*/ Trigger::Trigger(const QUuid &triggerTypeId, const QUuid &deviceId, const QVariantMap ¶ms): m_triggerTypeId(triggerTypeId), m_deviceId(deviceId), @@ -22,26 +25,32 @@ Trigger::Trigger(const QUuid &triggerTypeId, const QUuid &deviceId, const QVaria { } +/*! Returns the id of the \l{TriggerType} which describes this Trigger.*/ QUuid Trigger::triggerTypeId() const { return m_triggerTypeId; } +/*! Returns the id of the \l{Device} associated with this Trigger.*/ QUuid Trigger::deviceId() const { return m_deviceId; } +/*! Returns the parameters of this Trigger.*/ QVariantMap Trigger::params() const { return m_params; } +/*! Set the parameters of this Trigger to \a params.*/ void Trigger::setParams(const QVariantMap ¶ms) { m_params = params; } +/*! Compare this Trigger to the Trigger given by \a other. + Triggers are equal (returns true) if triggerTypeId, deviceId and params match. */ bool Trigger::operator ==(const Trigger &other) const { return m_triggerTypeId == other.triggerTypeId() diff --git a/libhive/triggertype.cpp b/libhive/triggertype.cpp index 5f2b8cdb..c67396f1 100644 --- a/libhive/triggertype.cpp +++ b/libhive/triggertype.cpp @@ -10,7 +10,7 @@ #include "triggertype.h" -/*! Constructs a TriggerType object with the given id. */ +/*! Constructs a TriggerType object with the given \a id. */ TriggerType::TriggerType(const QUuid &id): m_id(id) { @@ -28,7 +28,7 @@ QString TriggerType::name() const return m_name; } -/*! Set a name for this TriggerType, e.g. "Temperature changed" */ +/*! Set the name for this TriggerType to \a name, e.g. "Temperature changed" */ void TriggerType::setName(const QString &name) { m_name = name; @@ -44,7 +44,7 @@ QVariantList TriggerType::parameters() const } /*! - Set the parameter description for this TriggerType, + Set the parameter description for this TriggerType to \a parameters, e.g. QVariantList(QVariantMap(("name", "temperature"), ("type": QVariant::Real))) */ void TriggerType::setParameters(const QVariantList ¶meters) diff --git a/plugins/deviceplugins/meisteranker/devicepluginmeisteranker.cpp b/plugins/deviceplugins/meisteranker/devicepluginmeisteranker.cpp index bfc9bc60..84c2f9ac 100644 --- a/plugins/deviceplugins/meisteranker/devicepluginmeisteranker.cpp +++ b/plugins/deviceplugins/meisteranker/devicepluginmeisteranker.cpp @@ -100,7 +100,8 @@ QUuid DevicePluginMeisterAnker::pluginId() const void DevicePluginMeisterAnker::executeAction(Device *device, const Action &action) { - + Q_UNUSED(device) + Q_UNUSED(action) } void DevicePluginMeisterAnker::radioData(QList rawData) diff --git a/server/hivecore.cpp b/server/hivecore.cpp index 01917556..3c0cf10d 100644 --- a/server/hivecore.cpp +++ b/server/hivecore.cpp @@ -18,6 +18,7 @@ HiveCore* HiveCore::s_instance = 0; +/*! Returns a pointer to the single \l{HiveCore} instance.*/ HiveCore *HiveCore::instance() { if (!s_instance) { @@ -26,16 +27,20 @@ HiveCore *HiveCore::instance() return s_instance; } +/*! Returns a pointer to the \l{DeviceManager} instance owned by HiveCore.*/ DeviceManager *HiveCore::deviceManager() const { return m_deviceManager; } +/*! Returns a pointer to the \l{RuleEngine} instance owned by HiveCore.*/ RuleEngine *HiveCore::ruleEngine() const { return m_ruleEngine; } +/*! Constructs HiveCore with the given \a parent. This is private. + Use \l{HiveCore::instance()} to access the single instance.*/ HiveCore::HiveCore(QObject *parent) : QObject(parent) { @@ -59,6 +64,8 @@ HiveCore::HiveCore(QObject *parent) : } +/*! Connected to the DeviceManager's emitTrigger signal. Triggers received in + here will be evaluated by the \l{RuleEngine} and the according \l{Action}{Actions} are executed.*/ void HiveCore::gotSignal(const Trigger &trigger) { foreach (const Action &action, m_ruleEngine->evaluateTrigger(trigger)) { diff --git a/server/rule.cpp b/server/rule.cpp index 7bba6b33..7e0bfad0 100644 --- a/server/rule.cpp +++ b/server/rule.cpp @@ -5,7 +5,7 @@ \ingroup rules \inmodule server - A \l{Rule} is always triggered by a \l{Trigger}, has \l{State}{States} + A Rule is always triggered by a \l{Trigger}, has \l{State}{States} to be compared and \l{Action}{Actions} to be executed. Additionally a Rule is either of type \l{Rule::RuleTypeAll} or \l{Rule::RuleTypeAny} which determines if all or any of the \l{State}{States} must be matching @@ -14,10 +14,24 @@ \sa Trigger, State, Action */ +/*! \enum Rule::RuleType + + Note: There is no RuleTypeNone. If you don't want to compare any + states, construct a rule without states in which case it doesn't + matter what the Rule's type is. + + \value RuleTypeAll + All States must match in order for the Rule to apply. + \value RuleTypeAny + Any State must match in order for the Rule to apply. +*/ + #include "rule.h" #include +/*! Constructs a Rule with the given \a id, \a trigger, \a states and \a actions. The ruleType will default to + \l{Rule::RuleTypeAll}.*/ Rule::Rule(const QUuid &id, const Trigger &trigger, const QList &states, const QList &actions): m_id(id), m_trigger(trigger), @@ -27,31 +41,37 @@ Rule::Rule(const QUuid &id, const Trigger &trigger, const QList &states, { } +/*! Returns the id or the Rule. */ QUuid Rule::id() const { return m_id; } +/*! Returns the \l{Trigger} that triggers this Rule.*/ Trigger Rule::trigger() const { return m_trigger; } +/*! Returns the \l{State}{States} that need to be matching in order for this to Rule apply. */ QList Rule::states() const { return m_states; } +/*! Returns the \l{Action}{Actions} to be executed when this Rule is triggerd and states match. */ QList Rule::actions() const { return m_actions; } +/*! Returns the type of the rule. This defines how states are compared. The default is \l{Rule::RuleTypeAll}.*/ Rule::RuleType Rule::ruleType() const { return m_ruleType; } +/*! Set the type of the rule to \a ruleType. This defines how states are compared. The default is \l{Rule::RuleTypeAll}.*/ void Rule::setRuleType(Rule::RuleType ruleType) { m_ruleType = ruleType; diff --git a/server/ruleengine.cpp b/server/ruleengine.cpp index b798b0f9..ea4e6255 100644 --- a/server/ruleengine.cpp +++ b/server/ruleengine.cpp @@ -12,6 +12,26 @@ \sa Trigger, Rule, Action */ +/*! \fn void RuleEngine::ruleAdded(const QUuid &ruleId) + Will be emitted whenever a new \l{Rule} is added to this Engine. + \a ruleId holds the id of the new rule.*/ + +/*! \fn void RuleEngine::ruleRemoved(const QUuid &ruleId) + Will be emitted whenever a \l{Rule} is removed from this Engine. + \a ruleId holds the id of the removed rule. You should remove any references + or copies you hold for this rule.*/ + +/*! \enum RuleEngine::RuleError + \value RuleErrorNoError + No error happened. Everything is fine. + \value RuleErrorRuleNotFound + Couldn't find a \l{Rule} with the given id. + \value RuleErrorDeviceNotFound + Couldn't find a \l{Device} with the given id. + \value RuleErrorTriggerTypeNotFound + Couldn't find a \l{TriggerType} with the given id. + */ + #include "ruleengine.h" #include "hivecore.h" @@ -25,6 +45,9 @@ QString rulesFileName = "hiveyourhome/rules"; +/*! Constructs the RuleEngine with the given \a parent. Although it wouldn't harm to have multiple RuleEngines, there is one + instance available from \l{HiveCore}. This one should be used instead of creating multiple ones. + */ RuleEngine::RuleEngine(QObject *parent) : QObject(parent) { @@ -68,6 +91,10 @@ RuleEngine::RuleEngine(QObject *parent) : } +/*! Ask the Engine to evaluate all the rules for the given \a trigger. + This will search all the \l{Rule}{Rules} triggered by this \l{Trigger} + and evaluate it's states according to its type. It will return a + list of all \l{Action}{Actions} that should be executed. */ QList RuleEngine::evaluateTrigger(const Trigger &trigger) { QList actions; @@ -97,11 +124,14 @@ QList RuleEngine::evaluateTrigger(const Trigger &trigger) return actions; } +/*! Add a new \l{Rule} with the given \a trigger and \a actions to the engine. + For convenience, this creates a Rule without any \l{State} comparison. */ RuleEngine::RuleError RuleEngine::addRule(const Trigger &trigger, const QList &actions) { return addRule(trigger, QList(), actions); } +/*! Add a new \l{Rule} with the given \a trigger, \a states and \a actions to the engine. */ RuleEngine::RuleError RuleEngine::addRule(const Trigger &trigger, const QList &states, const QList &actions) { qDebug() << "adding rule: Trigger:" << trigger.triggerTypeId() << "with" << actions.count() << "actions"; @@ -162,11 +192,15 @@ RuleEngine::RuleError RuleEngine::addRule(const Trigger &trigger, const QList RuleEngine::rules() const { return m_rules; } +/*! Removes the \l{Rule} with the given \a ruleId from the Engine. + Returns \l{RuleEngine::RuleError} which describes whether the operation + was successful or not. */ RuleEngine::RuleError RuleEngine::removeRule(const QUuid &ruleId) { for (int i = 0; i < m_rules.count(); ++i) {