From 6bca9c08dcbe95416ab59c3c42bfe6fa95fe4c8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Tue, 28 Oct 2014 18:47:32 +0100 Subject: [PATCH] added more documentation --- doc/guh.qdoc | 1 + doc/libguh.qdoc | 3 + libguh/devicemanager.cpp | 96 ++++++++++++------ libguh/devicemanager.h | 2 +- libguh/hardware/gpio.cpp | 10 +- libguh/hardware/radio433/radio433.cpp | 27 ++++- libguh/hardware/radio433/radio433.h | 1 - libguh/plugin/device.cpp | 14 +++ libguh/plugin/devicedescriptor.cpp | 18 +++- libguh/plugin/deviceplugin.cpp | 139 +++++++++++++++----------- libguh/types/action.cpp | 14 ++- libguh/types/actiontype.cpp | 14 +-- libguh/types/event.cpp | 29 +++--- libguh/types/eventdescriptor.cpp | 18 ++-- libguh/types/eventtype.cpp | 16 ++- libguh/types/param.cpp | 13 ++- libguh/types/paramdescriptor.cpp | 4 + libguh/types/paramtype.cpp | 17 ++++ libguh/types/state.cpp | 8 +- libguh/types/statedescriptor.cpp | 30 +++--- libguh/types/statetype.cpp | 18 ++-- libguh/types/vendor.cpp | 11 +- 22 files changed, 321 insertions(+), 182 deletions(-) diff --git a/doc/guh.qdoc b/doc/guh.qdoc index b324bfda..8eea0b12 100644 --- a/doc/guh.qdoc +++ b/doc/guh.qdoc @@ -10,6 +10,7 @@ \list \li \l{Types}{Types used in the guh system} \li \l{Device Plugins}{The Device Plugin API} + \li \l{Hardware Resources}{Hardware Resources} \endlist \li \l{guh server} \list diff --git a/doc/libguh.qdoc b/doc/libguh.qdoc index bcfcab9c..154958a3 100644 --- a/doc/libguh.qdoc +++ b/doc/libguh.qdoc @@ -7,6 +7,9 @@ \section1 Device Plugins \annotatedlist devices + + \section1 Hardware Resources + \annotatedlist hardware */ diff --git a/libguh/devicemanager.cpp b/libguh/devicemanager.cpp index b1979848..e4102921 100644 --- a/libguh/devicemanager.cpp +++ b/libguh/devicemanager.cpp @@ -30,8 +30,7 @@ */ -/*! - \enum DeviceManager::HardwareResource +/*! \enum DeviceManager::HardwareResource This enum type specifies hardware resources which can be requested by \l{DevicePlugin}{DevicePlugins}. @@ -46,8 +45,7 @@ but rather request the global timer using the hardware resources. */ -/*! - \enum DeviceManager::DeviceError +/*! \enum DeviceManager::DeviceError This enum type specifies the errors that can happen when working with \l{Device}{Devices}. @@ -91,8 +89,7 @@ Couldn't find the PairingTransactionId for the given id. */ -/*! - \enum DeviceManager::DeviceSetupStatus +/*! \enum DeviceManager::DeviceSetupStatus This enum type specifies the setup status of a \l{Device}. @@ -104,6 +101,36 @@ The status of the \l{Device} setup will be emitted asynchronous. */ +/*! \fn void DeviceManager::loaded(); + The DeviceManager will emit this Signal when all \l{Device}{Devices} are loaded. +*/ + +/*! \fn void DeviceManager::deviceSetupFinished(Device *device, DeviceError status); + This signal is emitted when the setup of a \a device is finished. The \a status parameter describes the + \l{DeviceManager}{DeviceError} that occurred. +*/ + +/*! \fn void DeviceManager::deviceStateChanged(Device *device, const QUuid &stateTypeId, const QVariant &value); + This signal is emitted when the \l{State} of a \a device changed. The \a stateTypeId parameter describes the + \l{StateType} and the \a value parameter holds the new value. +*/ + +/*! \fn void DeviceManager::devicesDiscovered(const DeviceClassId &deviceClassId, const QList &devices); + This signal is emitted when the discovery of a \a deviceClassId is finished. The \a devices parameter describes the + list of \l{DeviceDescriptor}{DeviceDescriptors} of all discovered \l{Device}{Devices}. + \sa discoverDevices() +*/ + +/*! \fn void DeviceManager::actionExecutionFinished(const ActionId &actionId, DeviceError status); + The DeviceManager will emit a this Signal when the \l{Action} with the given \a actionId is finished. + The \a status of the \l{Action} execution will be described as \l{DeviceManager}{DeviceError}. +*/ + +/*! \fn void DeviceManager::pairingFinished(const PairingTransactionId &pairingTransactionId, DeviceError status, const DeviceId &deviceId = DeviceId()); + The DeviceManager will emit a this Signal when the pairing of a \l{Device} with the \a deviceId and \a pairingTransactionId is finished. + The \a status of the pairing will be described as \l{DeviceManager}{DeviceError}. +*/ + /*! \fn void DeviceManager::eventTriggered(const Event &event) The DeviceManager will emit a \l{Event} described in \a event whenever a Device creates one. Normally only \l{GuhCore} should connect to this and execute actions @@ -130,8 +157,7 @@ #include /*! Constructs the DeviceManager with the given \a parent. There should only be one DeviceManager in the system created by \l{GuhCore}. - Use \c GuhCore::instance()->deviceManager() instead to access the DeviceManager. -*/ + * Use \c GuhCore::instance()->deviceManager() instead to access the DeviceManager. */ DeviceManager::DeviceManager(QObject *parent) : QObject(parent), m_radio433(0) @@ -157,7 +183,7 @@ DeviceManager::DeviceManager(QObject *parent) : // TODO: error handling if no Radio433 detected (GPIO or network), disable radio433 plugins or something... } -/*! Destructor of the DeviceManager. Each loaded \l{DevicePlugin} will be deleted.*/ +/*! Destructor of the DeviceManager. Each loaded \l{DevicePlugin} will be deleted. */ DeviceManager::~DeviceManager() { qDebug() << "Shutting down DeviceManager"; @@ -172,14 +198,14 @@ QList DeviceManager::plugins() const return m_devicePlugins.values(); } -/*! Returns the \{DevicePlugin} with the given \a id. Null if the id couldn't be found. */ +/*! Returns the \l{DevicePlugin} with the given \a id. Null if the id couldn't be found. */ DevicePlugin *DeviceManager::plugin(const PluginId &id) const { return m_devicePlugins.value(id); } /*! Returns a certain \l{DeviceError} and sets the configurations of the plugin with the given \a pluginId - and the given \a pluginConfig */ + * and the given \a pluginConfig. */ DeviceManager::DeviceError DeviceManager::setPluginConfig(const PluginId &pluginId, const ParamList &pluginConfig) { DevicePlugin *plugin = m_devicePlugins.value(pluginId); @@ -208,7 +234,7 @@ QList DeviceManager::supportedVendors() const } /*! Returns all the supported \l{DeviceClass}{DeviceClasses} by all \l{DevicePlugin}{DevicePlugins} loaded in the system. - Optionally filtered by vendorId. */ + * Optionally filtered by \a vendorId. */ QList DeviceManager::supportedDevices(const VendorId &vendorId) const { QList ret; @@ -222,7 +248,7 @@ QList DeviceManager::supportedDevices(const VendorId &vendorId) con return ret; } /*! Returns a certain \l{DeviceError} and starts the discovering process of the \l{Device} with the given \a deviceClassId - and the given \a params.*/ + * and the given \a params.*/ DeviceManager::DeviceError DeviceManager::discoverDevices(const DeviceClassId &deviceClassId, const ParamList ¶ms) { qDebug() << "DeviceManager discoverdevices" << params; @@ -251,12 +277,11 @@ DeviceManager::DeviceError DeviceManager::discoverDevices(const DeviceClassId &d return ret; } -/*! 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}. - Optionally you can supply an id yourself if you must keep track of the added device. If you don't supply it, a new one will - be generated. Only devices with \l{DeviceClass::CreateMethodUser} can be created using this method. - Returns \l{DeviceError} to inform about the result. -*/ +/*! Add a new configured device for the given \l{DeviceClass}, the given parameters and \a id. + * \a deviceClassId must refer to an existing \{DeviceClass} and \a params must match the parameter description in the \l{DeviceClass}. + * Optionally you can supply an id yourself if you must keep track of the added device. If you don't supply it, a new one will + * be generated. Only devices with \l{DeviceClass}{CreateMethodUser} can be created using this method. + * Returns \l{DeviceError} to inform about the result. */ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassId &deviceClassId, const ParamList ¶ms, const DeviceId id) { DeviceClass deviceClass = findDeviceClass(deviceClassId); @@ -269,11 +294,10 @@ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassI return DeviceErrorCreationMethodNotSupported; } -/*! Add a new configured device for the given \l{DeviceClass} the given DeviceDescriptorId. Only devices with \l{DeviceClass::CreateMethodDiscovery} - can be created using this method. The \a deviceClassId must refer to an existing \l{DeviceClass} and the \a deviceDescriptorId must refer to an existing DeviceDescriptorId - from the discovery. - Returns \l{DeviceError} to inform about the result. -*/ +/*! Add a new configured device for the given \l{DeviceClass} the given DeviceDescriptorId and \a deviceId. Only devices with \l{DeviceClass}{CreateMethodDiscovery} + * can be created using this method. The \a deviceClassId must refer to an existing \l{DeviceClass} and the \a deviceDescriptorId must refer to an existing DeviceDescriptorId + * from the discovery. + * Returns \l{DeviceError} to inform about the result. */ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassId &deviceClassId, const DeviceDescriptorId &deviceDescriptorId, const DeviceId &deviceId) { DeviceClass deviceClass = findDeviceClass(deviceClassId); @@ -292,10 +316,8 @@ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassI return addConfiguredDeviceInternal(deviceClassId, descriptor.params(), deviceId); } -/*! - Returns \l{DeviceManager}{DeviceError} to inform about the result. -*/ - +/*! Trys to pair a Device with the given \a pairingTransactionId, \a deviceClassId and \a params. + * Returns \l{DeviceManager}{DeviceError} to inform about the result. */ DeviceManager::DeviceError DeviceManager::pairDevice(const PairingTransactionId &pairingTransactionId, const DeviceClassId &deviceClassId, const ParamList ¶ms) { DeviceClass deviceClass = findDeviceClass(deviceClassId); @@ -324,6 +346,8 @@ DeviceManager::DeviceError DeviceManager::pairDevice(const PairingTransactionId return DeviceErrorNoError; } +/*! Trys to pair a Device with the given \a pairingTransactionId, \a deviceClassId and \a deviceDescriptorId. + * Returns \l{DeviceManager}{DeviceError} to inform about the result. */ DeviceManager::DeviceError DeviceManager::pairDevice(const PairingTransactionId &pairingTransactionId, const DeviceClassId &deviceClassId, const DeviceDescriptorId &deviceDescriptorId) { DeviceClass deviceClass = findDeviceClass(deviceClassId); @@ -353,6 +377,8 @@ DeviceManager::DeviceError DeviceManager::pairDevice(const PairingTransactionId return DeviceErrorNoError; } +/*! Confirms the pairing of a \l{Device} with the given \a pairingTransactionId and \a secret. + * Returns \l{DeviceManager}{DeviceError} to inform about the result. */ DeviceManager::DeviceError DeviceManager::confirmPairing(const PairingTransactionId &pairingTransactionId, const QString &secret) { Q_UNUSED(secret) @@ -391,6 +417,8 @@ DeviceManager::DeviceError DeviceManager::confirmPairing(const PairingTransactio return DeviceErrorPairingTransactionIdNotFound; } +/*! This Method will only be used from the DeviceManager in order to add a \l{Device} with the given \a deviceClassId, \a params and \ id. + * Returns \l{DeviceError} to inform about the result. */ DeviceManager::DeviceError DeviceManager::addConfiguredDeviceInternal(const DeviceClassId &deviceClassId, const ParamList ¶ms, const DeviceId id) { ParamList effectiveParams = params; @@ -442,6 +470,9 @@ DeviceManager::DeviceError DeviceManager::addConfiguredDeviceInternal(const Devi return DeviceErrorNoError; } +/*! Removes a \l{Device} with the given \a deviceId from the list of configured Devices. + * This Method also deletes all saved Settings of the Device. + * Returns \l{DeviceError} to inform about the result. */ DeviceManager::DeviceError DeviceManager::removeConfiguredDevice(const DeviceId &deviceId) { Device *device = findConfiguredDevice(deviceId); @@ -498,7 +529,7 @@ QList DeviceManager::findConfiguredDevices(const DeviceClassId &device } /*! For conveninece, this returns the \{DeviceClass} with the id given by \a deviceClassId. - Note: The returned DeviceClass may be invalid.*/ + * Note: The returned DeviceClass may be invalid. */ DeviceClass DeviceManager::findDeviceClass(const DeviceClassId &deviceClassId) const { foreach (const DeviceClass &deviceClass, m_supportedDevices) { @@ -509,9 +540,9 @@ DeviceClass DeviceManager::findDeviceClass(const DeviceClassId &deviceClassId) c return DeviceClass(); } -/*! 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}.*/ +/*! Execute the given \l{Action}. + * This will find the \l{Device} \a action refers to the \l{Action}{deviceId()} and + * its \l{DevicePlugin}. Then will dispatch the execution to the \l{DevicePlugin}.*/ DeviceManager::DeviceError DeviceManager::executeAction(const Action &action) { Action finalAction = action; @@ -547,7 +578,6 @@ DeviceManager::DeviceError DeviceManager::executeAction(const Action &action) void DeviceManager::loadPlugins() { - QStringList searchDirs; searchDirs << QCoreApplication::applicationDirPath() + "/../lib/guh/plugins"; searchDirs << QCoreApplication::applicationDirPath() + "/../plugins/"; diff --git a/libguh/devicemanager.h b/libguh/devicemanager.h index 2385cbf8..cfeac9a9 100644 --- a/libguh/devicemanager.h +++ b/libguh/devicemanager.h @@ -107,7 +107,7 @@ signals: void devicesDiscovered(const DeviceClassId &deviceClassId, const QList &devices); void deviceSetupFinished(Device *device, DeviceError status); void pairingFinished(const PairingTransactionId &pairingTransactionId, DeviceError status, const DeviceId &deviceId = DeviceId()); - void actionExecutionFinished(const ActionId, DeviceError status); + void actionExecutionFinished(const ActionId &actionId, DeviceError status); public slots: DeviceError executeAction(const Action &action); diff --git a/libguh/hardware/gpio.cpp b/libguh/hardware/gpio.cpp index eabeb89a..fd44ac33 100644 --- a/libguh/hardware/gpio.cpp +++ b/libguh/hardware/gpio.cpp @@ -50,7 +50,7 @@ Gpio::~Gpio() unexportGpio(); } -/*! Returns true if the GPIO could be exported in the system file "/sys/class/gpio/export".*/ +/*! Returns true if this GPIO could be exported in the system file "/sys/class/gpio/export". */ bool Gpio::exportGpio() { unexportGpio(); @@ -73,7 +73,7 @@ bool Gpio::exportGpio() return true; } -/*! Returns true if the GPIO could be unexported in the system file "/sys/class/gpio/unexport".*/ +/*! Returns true if this GPIO could be unexported in the system file "/sys/class/gpio/unexport". */ bool Gpio::unexportGpio() { char buf[64]; @@ -94,7 +94,7 @@ bool Gpio::unexportGpio() return true; } -/*! Returns true if the GPIO file could be opend.*/ +/*! Returns true, if the file of this GPIO could be opend.*/ int Gpio::openGpio() { char buf[64]; @@ -109,7 +109,7 @@ int Gpio::openGpio() return fd; } -/*! Returns true, if the direction \a dir of the GPIO could be set correctly. +/*! Returns true, if the direction \a dir of this GPIO could be set correctly. * * Possible directions are: * @@ -255,7 +255,7 @@ int Gpio::getValue() return value; } -/*! Returns true, if the \a edge of the GPIO could be set correctly. The \a edge parameter specifies, +/*! Returns true, if the \a edge of this GPIO could be set correctly. The \a edge parameter specifies, * when an interrupt occurs. * * Possible values are: diff --git a/libguh/hardware/radio433/radio433.cpp b/libguh/hardware/radio433/radio433.cpp index 9de0e1bb..6d5d3d32 100644 --- a/libguh/hardware/radio433/radio433.cpp +++ b/libguh/hardware/radio433/radio433.cpp @@ -18,14 +18,34 @@ /*! \class Radio433 - \brief The Radio433 class helps to interact with the 433 MHz Receiver and Transmitter. + \brief The Radio433 class helps to interact with the 433 MHz receiver and transmitter. + \ingroup hardware \inmodule libguh + This class handles all supported radio 433 MHz receiver and transmitter. Receiving data on the 433.92 MHz frequency + is only supported, if there are \l{Gpio}{GPIO's} available and a suitable receiver is connected to GPIO 27. Examples for receiver + can be found \l{https://www.futurlec.com/Radio-433MHZ.shtml}{here}. The antenna has a very large impact on the quality + of the signal and how well it is recognized. In many forums and blogs it is described that a 17, 3 mm piece of wire is enough. + Experiments have shown, it's not. A 50 Ohm coaxial cabel (thickness = 1mm), mounted on the antenna pin of the receiver + with a minimum distance of 5 cm away from the circuit and unisolated 17.3 mm at the end has shown the best results. + + In order to send data to a 433 MHz device, there currently are two possibilitis. If there are \l{Gpio}{GPIO's} + available, the data will be sent over the transmitter connected to GPIO 22. Also in this case the antenna is a verry + important part. + + The second possibility to sent data to a 433 MHz device is the \l{http://www.brennenstuhl.de/de-DE/steckdosenleisten-schaltgeraete-und-adapter/brematic-hausautomation/brematic-home-automation-gateway-gwy-433-1.html} + {Brennenstuhl 433 MHz LAN Gateway}. If there is a Gateway in the local network, this class will automaticaly detect + it and will be used. If both transmitter are available (Gateway + GPIO), each signal will be transmitted over both sender. +*/ + +/*! \fn void Radio433::dataReceived(QList rawData) + This signal is emitted when the receiver recognized a signal. The \a rawData parameter describes the signal. */ #include "radio433.h" +/*! Construct the hardware resource Radio433 with the given \a parent. Each possible 433 MHz hardware will be initialized here. */ Radio433::Radio433(QObject *parent) : QObject(parent) { @@ -38,12 +58,15 @@ Radio433::Radio433(QObject *parent) : connect(m_brennenstuhlTransmitter, &Radio433BrennenstuhlGateway::availableChanged, this, &Radio433::brennenstuhlAvailableChanged); } +/*! Destroys the hardware resource Radio433 object. */ Radio433::~Radio433() { m_receiver->quit(); m_transmitter->quit(); } +/*! Enables GPIO transmitter and receiver and the Brennenstuhl Lan Gateway. + * Returns true, if the GPIO's are available and set up correctly. The status of the gateway will be emited asynchronous. */ bool Radio433::enable() { m_brennenstuhlTransmitter->enable(); @@ -66,6 +89,7 @@ bool Radio433::enable() return true; } +/*! Returns true, if the Radio433 hardware resources disabled correctly. */ bool Radio433::disabel() { m_brennenstuhlTransmitter->disable(); @@ -93,6 +117,7 @@ void Radio433::brennenstuhlAvailableChanged(const bool &available) } } +/*! Returns true, if the \a rawData with a certain \a delay (pulse length) can be sent. */ bool Radio433::sendData(int delay, QList rawData) { bool sendGpio = false; diff --git a/libguh/hardware/radio433/radio433.h b/libguh/hardware/radio433/radio433.h index fdd502a9..9c254c34 100644 --- a/libguh/hardware/radio433/radio433.h +++ b/libguh/hardware/radio433/radio433.h @@ -32,7 +32,6 @@ public: explicit Radio433(QObject *parent = 0); ~Radio433(); - bool available(); bool enable(); bool disabel(); diff --git a/libguh/plugin/device.cpp b/libguh/plugin/device.cpp index 1694fa56..2e4f2188 100644 --- a/libguh/plugin/device.cpp +++ b/libguh/plugin/device.cpp @@ -29,11 +29,18 @@ \sa DeviceClass */ +/*! \fn void Device::stateValueChanged(const QUuid &stateTypeId, const QVariant &value) + This signal is emitted when the \l{State} with the given \a stateTypeId changed. + The \a value parameter describes the new value of the State. +*/ + + #include "device.h" #include "types/event.h" #include +/*! Construct an Device with the given \a pluginId, \a id, \a deviceClassId and \a parent. */ Device::Device(const PluginId &pluginId, const DeviceId &id, const DeviceClassId &deviceClassId, QObject *parent): QObject(parent), m_id(id), @@ -44,6 +51,7 @@ Device::Device(const PluginId &pluginId, const DeviceId &id, const DeviceClassId } +/*! Construct an Device with the given \a pluginId, \a deviceClassId and \a parent. A new DeviceId will be created for this Device. */ Device::Device(const PluginId &pluginId, const DeviceClassId &deviceClassId, QObject *parent): QObject(parent), m_id(DeviceId::createDeviceId()), @@ -101,6 +109,7 @@ void Device::setParams(const ParamList ¶ms) m_params = params; } +/*! Returns the value of the \l{Param} of this Device with the given \a paramName. */ QVariant Device::paramValue(const QString ¶mName) const { foreach (const Param ¶m, m_params) { @@ -111,6 +120,7 @@ QVariant Device::paramValue(const QString ¶mName) const return QVariant(); } +/*! Sets the \a value of the \l{Param} with the given \a paramName. */ void Device::setParamValue(const QString ¶mName, const QVariant &value) { ParamList params; @@ -129,6 +139,7 @@ QList Device::states() const return m_states; } +/*! Returns true, a \l{Param} with the given \a paramName exists for this Device. */ bool Device::hasParam(const QString ¶mName) const { foreach (const Param ¶m, m_params) { @@ -145,6 +156,7 @@ void Device::setStates(const QList &states) m_states = states; } +/*! Returns true, a \l{State} with the given \a stateTypeId exists for this Device. */ bool Device::hasState(const StateTypeId &stateTypeId) const { foreach (const State &state, m_states) { @@ -184,6 +196,7 @@ void Device::setStateValue(const StateTypeId &stateTypeId, const QVariant &value qWarning() << "failed setting state for" << m_name; } +/*! Returns the \l{State} with the given \a stateTypeId of this Device. */ State Device::state(const StateTypeId &stateTypeId) const { for (int i = 0; i < m_states.count(); ++i) { @@ -194,6 +207,7 @@ State Device::state(const StateTypeId &stateTypeId) const return State(StateTypeId(), DeviceId()); } +/*! Returns true, if setup of this Device is allready completed. */ bool Device::setupComplete() const { return m_setupComplete; diff --git a/libguh/plugin/devicedescriptor.cpp b/libguh/plugin/devicedescriptor.cpp index f4647e7d..b7be6d9d 100644 --- a/libguh/plugin/devicedescriptor.cpp +++ b/libguh/plugin/devicedescriptor.cpp @@ -18,23 +18,28 @@ /*! \class DeviceDescriptor - \brief Describes \l{Device}{Devices}. + \brief Holds the description of a \l{Device}. \ingroup devices \inmodule libguh + An DeviceDescriptor describes an \l{Device} in order to match it with a \l{Rule}. + \sa Device */ #include "devicedescriptor.h" + +/*! Construct a DeviceDescriptor. */ DeviceDescriptor::DeviceDescriptor(): m_id(DeviceDescriptorId::createDeviceDescriptorId()) { } +/*! Construct a DeviceDescriptor with the given \a deviceClassId, \a title and \a description.*/ DeviceDescriptor::DeviceDescriptor(const DeviceClassId &deviceClassId, const QString &title, const QString &description): m_id(DeviceDescriptorId::createDeviceDescriptorId()), m_deviceClassId(deviceClassId), @@ -44,6 +49,7 @@ DeviceDescriptor::DeviceDescriptor(const DeviceClassId &deviceClassId, const QSt } +/*! Construct a DeviceDescriptor with the given \a id, \a deviceClassId, \a title and \a description.*/ DeviceDescriptor::DeviceDescriptor(const DeviceDescriptorId &id, const DeviceClassId &deviceClassId, const QString &title, const QString &description) : m_id(id), m_deviceClassId(deviceClassId), @@ -52,46 +58,56 @@ DeviceDescriptor::DeviceDescriptor(const DeviceDescriptorId &id, const DeviceCla { } +/*! Returns true, if this DeviceDescriptor is valid. A DeviceDescriptor is valid, if the id and the deviceClassId are set. + * \sa id(), deviceClassId(), */ bool DeviceDescriptor::isValid() const { return !m_id.isNull() && !m_deviceClassId.isNull(); } +/*! Returns the id of this DeviceDescriptor. */ DeviceDescriptorId DeviceDescriptor::id() const { return m_id; } +/*! Returns the deviceClassId of this DeviceDescriptor. */ DeviceClassId DeviceDescriptor::deviceClassId() const { return m_deviceClassId; } +/*! Returns the name of this DeviceDescriptor. */ QString DeviceDescriptor::title() const { return m_title; } +/*! Sets the \a title of this DeviceDescriptor. */ void DeviceDescriptor::setTitle(const QString &title) { m_title = title; } +/*! Returns the description of this DeviceDescriptor. */ QString DeviceDescriptor::description() const { return m_description; } +/*! Sets the \a description of this DeviceDescriptor. */ void DeviceDescriptor::setDescription(const QString &description) { m_description = description; } +/*! Returns the list of \l{Param}{Params} of this DeviceDescriptor. */ ParamList DeviceDescriptor::params() const { return m_params; } +/*! Sets the list of \l{Param}{Params} of this DeviceDescriptor with the given \a params. */ void DeviceDescriptor::setParams(const ParamList ¶ms) { m_params = params; diff --git a/libguh/plugin/deviceplugin.cpp b/libguh/plugin/deviceplugin.cpp index 352fd139..2e9f7565 100644 --- a/libguh/plugin/deviceplugin.cpp +++ b/libguh/plugin/deviceplugin.cpp @@ -17,28 +17,17 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /*! -\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 libguh + \ingroup devices + \inmodule libguh -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()} */ -/*! - \fn QUuid DevicePlugin::pluginId() const - When implementing a plugin, generate a new uuid and return it here. Always return the - same uuid and don't change it or configurations can't be matched any more. - */ - -/*! - \fn QList DevicePlugin::supportedDevices() const - Return a list of \l{DeviceClass}{DeviceClasses} describing all the devices supported by this plugin. - */ - /*! \fn DeviceManager::HardwareResources DevicePlugin::requiredHardware() const Return flags describing the common hardware resources required by this plugin. @@ -58,31 +47,56 @@ pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId( */ /*! - \fn void DevicePlugin::executeAction(Device *device, const Action &action) + \fn DeviceManager::DeviceError DevicePlugin::executeAction(Device *device, const Action &action) This will be called to actually execute actions on the hardware. The \{Device} and the \{Action} are contained in the \a device and \a action parameters. - Use \l{DevicePlugin::report()} to report the result. If everything worked out, - just return report(). Otherwise fill in the error code and a short message - describing the offending part. E.g: - If the action couldn't be executed because the device can't be reached (e.g. it is unplugged) - then report the appropriate error code and give the device id as message: - return report(DeviceManager::DeviceErrorSetupFailed, device->id()); - Keep the message short, the DeviceManager will format it for you. + Return the appropriate \l{DeviceManager}{DeviceError}. It is possible to execute actions asynchronously. You never should do anything blocking for a long time (e.g. wait on a network reply from the internet) but instead return DeviceManager::DeviceErrorAsync and continue processing in an async manner. Once you have the reply ready, emit actionExecutionFinished() with the appropriate parameters. - \sa DevicePlugin::report(), DevicePlugin::actionExecutionFinished() - */ + \sa actionExecutionFinished() +*/ + +/*! + \fn void DevicePlugin::devicesDiscovered(const DeviceClassId &deviceClassId, const QList &devices); + This signal is emitted when the discovery of a \a deviceClassId of this DevicePlugin is finished. The \a devices parameter describes the + list of \l{DeviceDescriptor}{DeviceDescriptors} of all discovered \l{Device}{Devices}. + \sa discoverDevices() +*/ + +/*! + \fn void DevicePlugin::pairingFinished(const PairingTransactionId &pairingTransactionId, DeviceManager::DeviceSetupStatus status); + This signal is emitted when the pairing of a \a pairingTransactionId is finished. + The \a status of the will be described as \l{DeviceManager}{DeviceError}. + \sa confirmPairing() +*/ + +/*! + \fn void DevicePlugin::deviceSetupFinished(Device *device, DeviceManager::DeviceSetupStatus status); + This signal is emitted when the setup of a \a device in this DevicePlugin is finished. The \a status parameter describes the + \l{DeviceManager}{DeviceError} that occurred. +*/ + +/*! + \fn void DevicePlugin::configValueChanged(const QString ¶mName, const QVariant &value); + This signal is emitted when the \l{Param} with a certain \a paramName of a \l{Device} configuration changed the \a value. +*/ /*! \fn void DevicePlugin::actionExecutionFinished(const ActionId &id, DeviceManager::DeviceError status) - This signal is to be emitted when you previously have returned DeviceManager::DeviceErrorAsync - in a call of executeAction(). It is used to deliver the return value that previously has - been omitted by filling in DeviceErrorAsync. - */ + This signal is to be emitted when you previously have returned \l{DeviceManager}{DeviceErrorAsync} + in a call of executeAction(). The \a id refers to the executed \l{Action}. The \a status of the \l{Action} + execution will be described as \l{DeviceManager}{DeviceError}. +*/ + +/*! + \fn void DevicePlugin::autoDevicesAppeared(const DeviceClassId &deviceClassId, const QList &deviceDescriptors) + This signal is emitted when a new \l{Device} of certain \a deviceClassId appeared. The description of the \l{Device}{Devices} + will be in \a deviceDescriptors. This signal can only emitted from devices with the \l{DeviceClass}{CreateMethodAuto}. +*/ /*! \fn void DevicePlugin::emitEvent(const Event &event) @@ -91,13 +105,13 @@ pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId( such as \l{DevicePlugin::radioData()} or \l{DevicePlugin::guhTimer()}. Find a configured \l{Device} from the \l{DeviceManager} and get its \l{EventType}{EventTypes}, then create a \l{Event} complying to that \l{EventType} and emit it here. - */ +*/ /*! \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" @@ -121,16 +135,21 @@ DevicePlugin::~DevicePlugin() } +/*! Returns the name of this DevicePlugin. */ QString DevicePlugin::pluginName() const { return m_metaData.value("name").toString(); } +/*! Returns the id of this DevicePlugin. + * When implementing a plugin, generate a new uuid and return it here. Always return the + * same uuid and don't change it or configurations can't be matched any more. */ PluginId DevicePlugin::pluginId() const { return m_metaData.value("id").toString(); } +/*! Returns the list of \l{Vendor}{Vendors} supported by this DevicePlugin. */ QList DevicePlugin::supportedVendors() const { QList vendors; @@ -141,6 +160,7 @@ QList DevicePlugin::supportedVendors() const return vendors; } +/*! Return a list of \l{DeviceClass}{DeviceClasses} describing all the devices supported by this plugin. */ QList DevicePlugin::supportedDevices() const { QList deviceClasses; @@ -227,11 +247,11 @@ void DevicePlugin::startMonitoringAutoDevices() } -/*! Reimplement this if you support a DeviceClass with createMethod CreateMethodDiscovery. - This will be called to discover Devices for the given DeviceClass. This will always - be an async operation. Return DeviceErrorAsync or DeviceErrorNoError if the discovery - has been started successfully. Return an appropriate error otherwise. - Once devices are discovered, emit devicesDiscovered() once. */ +/*! Reimplement this if you support a DeviceClass with createMethod \l{DeviceManager}{CreateMethodDiscovery}. + This will be called to discover Devices for the given \a deviceClassId with the given \a params. This will always + be an async operation. Return \l{DeviceManager}{DeviceErrorAsync} or \l{DeviceManager}{DeviceErrorNoError} + if the discovery has been started successfully. Return an appropriate error otherwise. + Once devices are discovered, emit devicesDiscovered(). */ DeviceManager::DeviceError DevicePlugin::discoverDevices(const DeviceClassId &deviceClassId, const ParamList ¶ms) { Q_UNUSED(deviceClassId) @@ -240,12 +260,11 @@ DeviceManager::DeviceError DevicePlugin::discoverDevices(const DeviceClassId &de } /*! This will be called when a new device is created. The plugin has the chance to do some setup. - Return DeviceSetupStatusFailure if something bad happened during the setup in which case the device - will be disabled. Return DeviceSetupStatusSuccess if everything went well. If you can't tell yet and - need more time to set up the device (note: you should never block in this method) you can - return DeviceSetupStatusAsync. In that case the devicemanager will wait for you to emit - \l{deviceSetupFinished(Device *device, DeviceManager::DeviceSetupStatus status)} to report - the status. + Return \l{DeviceManager}{DeviceSetupStatusFailure} if something bad happened during the setup in which case the \a device + will be disabled. Return \l{DeviceManager}{DeviceSetupStatusSuccess} if everything went well. If you can't tell yet and + need more time to set up the \a device (note: you should never block in this method) you can + return \l{DeviceManager}{DeviceSetupStatusAsync}. In that case the \l{DeviceManager} will wait for you to emit + \l{DevicePlugin}{deviceSetupFinished} to report the status. */ DeviceManager::DeviceSetupStatus DevicePlugin::setupDevice(Device *device) { @@ -253,15 +272,16 @@ DeviceManager::DeviceSetupStatus DevicePlugin::setupDevice(Device *device) return DeviceManager::DeviceSetupStatusSuccess; } -/*! This will be called when a device removed. The plugin has the chance to do some teardown. - The device is still valid during this call, but already removed from the system. - The device will be deleted as soon as this method returns. -*/ +/*! This will be called when a \a device removed. The plugin has the chance to do some teardown. + * The device is still valid during this call, but already removed from the system. + * The device will be deleted as soon as this method returns.*/ void DevicePlugin::deviceRemoved(Device *device) { Q_UNUSED(device) } +/*! Confirms the pairing of a \a deviceClassId with the given \a pairingTransactionId and \a params. + * Returns \l{DeviceManager}{DeviceError} to inform about the result. */ DeviceManager::DeviceSetupStatus DevicePlugin::confirmPairing(const PairingTransactionId &pairingTransactionId, const DeviceClassId &deviceClassId, const ParamList ¶ms) { Q_UNUSED(pairingTransactionId) @@ -272,6 +292,7 @@ DeviceManager::DeviceSetupStatus DevicePlugin::confirmPairing(const PairingTrans return DeviceManager::DeviceSetupStatusFailure; } +/*! Returns the configuration description of this DevicePlugin as a list of \l{ParamType}{ParamTypes}. */ QList DevicePlugin::configurationDescription() const { return QList(); @@ -324,6 +345,7 @@ ParamList DevicePlugin::configuration() const at the time when your plugin is loaded, but will be set soon after. Listen to configurationValueChanged() to know when something changes. When implementing a new plugin, specify in configurationDescription() what you want to see here. + Returns the config value of a \l{Param} with the given \a paramName of this DevicePlugin. */ QVariant DevicePlugin::configValue(const QString ¶mName) const { @@ -350,9 +372,7 @@ DeviceManager::DeviceError DevicePlugin::setConfiguration(const ParamList &confi return DeviceManager::DeviceErrorNoError; } -/*! - Will be called by the DeviceManager to set a plugin's \a configuration. - */ +/*! Will be called by the DeviceManager to set a plugin's \l{Param} with the given \a paramName and \a value. */ DeviceManager::DeviceError DevicePlugin::setConfigValue(const QString ¶mName, const QVariant &value) { bool found = false; @@ -401,15 +421,12 @@ DeviceManager::DeviceError DevicePlugin::setConfigValue(const QString ¶mName When implementing a plugin, use this to find the \l{Device}{Devices} you need. */ - DeviceManager *DevicePlugin::deviceManager() const { return m_deviceManager; } -/*! - Returns a list of all configured devices belonging to this plugin. - */ +/*! Returns a list of all configured devices belonging to this plugin. */ QList DevicePlugin::myDevices() const { QList myDeviceClassIds; @@ -427,7 +444,7 @@ QList DevicePlugin::myDevices() const } /*! - Find a certain device from myDevices() by its params. All parameters must + Find a certain device from myDevices() by its \a params. All parameters must match or the device will not be found. Be prepared for nullptrs. */ Device *DevicePlugin::findDeviceByParams(const ParamList ¶ms) const @@ -447,11 +464,11 @@ Device *DevicePlugin::findDeviceByParams(const ParamList ¶ms) const } /*! - Transmits data contained in \a rawData on the Radio433 or Radio868 - devices, depending on the hardware requested by this plugin. - \sa DevicePlugin::requiredHardware() - */ + Transmits data contained in \a rawData on the \l{Radio433} devices, depending on the hardware requested by this plugin. + Returns true if, the \a rawData with a certain \a delay (pulse length) can be sent. + \sa Radio433, requiredHardware() + */ bool DevicePlugin::transmitData(int delay, QList rawData) { switch (requiredHardware()) { diff --git a/libguh/types/action.cpp b/libguh/types/action.cpp index f872b3e1..b6494ced 100644 --- a/libguh/types/action.cpp +++ b/libguh/types/action.cpp @@ -30,9 +30,10 @@ \sa Device, ActionType */ + #include "action.h" -/*! Construct an Action with the given \a deviceId and \a actionTypeId */ +/*! Construct an Action with the given \a deviceId and \a actionTypeId. */ Action::Action(const ActionTypeId &actionTypeId, const DeviceId &deviceId) : m_id(ActionId::createActionId()), m_actionTypeId(actionTypeId), @@ -40,6 +41,7 @@ Action::Action(const ActionTypeId &actionTypeId, const DeviceId &deviceId) : { } +/*! Returns the actionId for this Action. */ ActionId Action::id() const { return m_id; @@ -51,30 +53,32 @@ bool Action::isValid() const return !m_actionTypeId.isNull() && !m_deviceId.isNull(); } -/*! Returns the actionTypeId for this Action */ +/*! Returns the actionTypeId for this Action.*/ ActionTypeId Action::actionTypeId() const { return m_actionTypeId; } -/*! Returns the deviceId this Action is associated with.*/ +/*! Returns the deviceId this Action is associated with. */ DeviceId Action::deviceId() const { return m_deviceId; } -/*! Returns the parameters for this Action.*/ +/*! Returns the parameters for this Action. */ ParamList 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()}*/ +/*! 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 ParamList ¶ms) { m_params = params; } +/*! Returns the parameter of this Action with a cetrain \a paramName. */ Param Action::param(const QString ¶mName) const { foreach (const Param ¶m, m_params) { diff --git a/libguh/types/actiontype.cpp b/libguh/types/actiontype.cpp index 64ef0c06..3f468ae3 100644 --- a/libguh/types/actiontype.cpp +++ b/libguh/types/actiontype.cpp @@ -27,45 +27,45 @@ 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. + All Actions must have valid a ActionType in order to be useful. \sa Action */ #include "actiontype.h" -/*! Constructs an ActionType with the given \a id.*/ +/*! Constructs an ActionType with the given \a id. */ ActionType::ActionType(const ActionTypeId &id): m_id(id) { } -/*! Returns the id of this ActionType.*/ +/*! Returns the id of this ActionType. */ ActionTypeId ActionType::id() const { return m_id; } -/*! Returns the name of this ActionType */ +/*! 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.*/ +/*! Set the \a name for this Action. This will be visible 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. */ + * from this ActionType must have their parameters matching to this template. */ QList ActionType::paramTypes() const { return m_paramTypes; } /*! Set the parameter description of this ActionType. \l{Action}{Actions} created - from this ActionType must have their \a parameters matching to this template. */ + * from this ActionType must have their \a paramTypes matching to this template. */ void ActionType::setParamTypes(const QList ¶mTypes) { m_paramTypes = paramTypes; diff --git a/libguh/types/event.cpp b/libguh/types/event.cpp index 62425b16..aa3b852a 100644 --- a/libguh/types/event.cpp +++ b/libguh/types/event.cpp @@ -33,15 +33,15 @@ #include "event.h" +/*! Constructs an Event. */ Event::Event(): m_id(EventId::createEventId()) { - } -/*! Constructs a Event reflecting the \l{Event} given by \a EventTypeId, 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{Event}.*/ +/*! Constructs an Event reflecting the \l{Event} given by \a eventTypeId, 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{Event}. */ Event::Event(const EventTypeId &eventTypeId, const DeviceId &deviceId, const ParamList ¶ms): m_id(EventId::createEventId()), m_eventTypeId(eventTypeId), @@ -50,49 +50,50 @@ Event::Event(const EventTypeId &eventTypeId, const DeviceId &deviceId, const Par { } -/*! Returns this event's id. Each newly created event will have a new UUID generated. The id will be copied - in the copy ctor.*/ +/*! Returns the Id of this Event. Each newly created Event will have a new UUID generated. The id will be copied + * in the copy constructor. */ EventId Event::eventId() const { return m_id; } -/*! Returns the id of the \l{EventType} which describes this Event.*/ +/*! Returns the id of the \l{EventType} which describes this Event. */ EventTypeId Event::eventTypeId() const { return m_eventTypeId; } -/*! Set the EventTypeId for this Event. */ +/*! Set the EventTypeId for this Event to the given \a eventTypeId. */ void Event::setEventTypeId(const EventTypeId &eventTypeId) { m_eventTypeId = eventTypeId; } -/*! Returns the id of the \l{Device} associated with this Event.*/ +/*! Returns the id of the \l{Device} associated with this Event. */ DeviceId Event::deviceId() const { return m_deviceId; } -/*! Set the DeviceId for this Event.*/ +/*! Set the \a deviceId for this Event. */ void Event::setDeviceId(const DeviceId &deviceId) { m_deviceId = deviceId; } -/*! Returns the parameters of this Event.*/ +/*! Returns the parameters of this Event. */ ParamList Event::params() const { return m_params; } -/*! Set the parameters of this Event to \a params.*/ +/*! Set the parameters of this Event to \a params. */ void Event::setParams(const ParamList ¶ms) { m_params = params; } +/*! Returns the parameter of this Event with a cetrain \a paramName. */ Param Event::param(const QString ¶mName) const { foreach (const Param ¶m, m_params) { @@ -104,7 +105,7 @@ Param Event::param(const QString ¶mName) const } /*! Compare this Event to the Event given by \a other. - Events are equal (returns true) if eventTypeId, deviceId and params match. */ + * Events are equal (returns true) if eventTypeId, deviceId and params match. */ bool Event::operator ==(const Event &other) const { bool paramsMatch = true; @@ -121,6 +122,7 @@ bool Event::operator ==(const Event &other) const && paramsMatch; } +/*! Writes the eventTypeId and the deviceId of the given \a event to \a dbg. */ QDebug operator<<(QDebug dbg, const Event &event) { dbg.nospace() << "Event(EventTypeId: " << event.eventTypeId().toString() << ", DeviceId" << event.deviceId().toString() << ")"; @@ -128,6 +130,7 @@ QDebug operator<<(QDebug dbg, const Event &event) return dbg.space(); } +/*! Writes the each \l{Event} of the given \a events to \a dbg. */ QDebug operator<<(QDebug dbg, const QList &events) { dbg.nospace() << "EventList (count:" << events.count() << ")"; diff --git a/libguh/types/eventdescriptor.cpp b/libguh/types/eventdescriptor.cpp index 3adb8811..ffe6698b 100644 --- a/libguh/types/eventdescriptor.cpp +++ b/libguh/types/eventdescriptor.cpp @@ -30,8 +30,7 @@ #include "eventdescriptor.h" -/*! Constructs an EventDescriptor describing an \l{Event}. - */ +/*! Constructs an EventDescriptor describing an \l{Event} with the given \a eventTypeId, \a deviceId and the given \a paramDescriptors. */ EventDescriptor::EventDescriptor(const EventTypeId &eventTypeId, const DeviceId &deviceId, const QList ¶mDescriptors): m_eventTypeId(eventTypeId), m_deviceId(deviceId), @@ -39,30 +38,31 @@ EventDescriptor::EventDescriptor(const EventTypeId &eventTypeId, const DeviceId { } -/*! Returns the id of the \l{EventType} which describes this Event.*/ +/*! Returns the id of the \l{EventType} which describes this Event. */ EventTypeId EventDescriptor::eventTypeId() const { return m_eventTypeId; } -/*! Returns the id of the \l{Device} associated with this Event.*/ +/*! Returns the id of the \l{Device} associated with this Event. */ DeviceId EventDescriptor::deviceId() const { return m_deviceId; } -/*! Returns the parameters of this Event.*/ +/*! Returns the parameters of this Event. */ QList EventDescriptor::paramDescriptors() const { return m_paramDescriptors; } -/*! Set the parameters of this Event to \a params.*/ +/*! Set the parameters of this Event to \a paramDescriptors. */ void EventDescriptor::setParamDescriptors(const QList ¶mDescriptors) { m_paramDescriptors = paramDescriptors; } +/*! Set a parameters of this Event to \a paramDescriptorName. */ ParamDescriptor EventDescriptor::paramDescriptor(const QString ¶mDescriptorName) const { foreach (const ParamDescriptor ¶mDescriptor, m_paramDescriptors) { @@ -74,7 +74,7 @@ ParamDescriptor EventDescriptor::paramDescriptor(const QString ¶mDescriptorN } /*! Compare this Event to the Event given by \a other. - Events are equal (returns true) if eventTypeId, deviceId and params match. */ + * Events are equal (returns true) if eventTypeId, deviceId and params match. */ bool EventDescriptor::operator ==(const EventDescriptor &other) const { bool paramsMatch = true; @@ -91,6 +91,8 @@ bool EventDescriptor::operator ==(const EventDescriptor &other) const && paramsMatch; } +/*! Compare this EventDescriptor to the Event given by \a event. + * Events are equal (returns true) if eventTypeId, deviceId and params match. */ bool EventDescriptor::operator ==(const Event &event) const { if (m_eventTypeId != event.eventTypeId() || m_deviceId != event.deviceId()) { @@ -134,6 +136,7 @@ bool EventDescriptor::operator ==(const Event &event) const return true; } +/*! Writes the eventTypeId and the deviceId of the given \a eventDescriptor to \a dbg. */ QDebug operator<<(QDebug dbg, const EventDescriptor &eventDescriptor) { dbg.nospace() << "EventDescriptor(EventTypeId: " << eventDescriptor.eventTypeId().toString() << ", DeviceId" << eventDescriptor.deviceId() << ")"; @@ -141,6 +144,7 @@ QDebug operator<<(QDebug dbg, const EventDescriptor &eventDescriptor) return dbg.space(); } +/*! Writes each \a eventDescriptors to \a dbg. */ QDebug operator<<(QDebug dbg, const QList &eventDescriptors) { dbg.nospace() << "EventDescriptorList (count:" << eventDescriptors.count() << ")"; diff --git a/libguh/types/eventtype.cpp b/libguh/types/eventtype.cpp index 1ec8564f..6116f1c3 100644 --- a/libguh/types/eventtype.cpp +++ b/libguh/types/eventtype.cpp @@ -40,31 +40,27 @@ EventTypeId EventType::id() const return m_id; } -/*! Returns the name of this EventType, e.g. "Temperature changed" */ +/*! Returns the name of this EventType, e.g. "Temperature changed". */ QString EventType::name() const { return m_name; } -/*! Set the name for this EventType to \a name, e.g. "Temperature changed" */ +/*! Set the name for this EventType to \a name, e.g. "Temperature changed". */ void EventType::setName(const QString &name) { m_name = name; } -/*! - Holds a List describing possible parameters for a \l{Event} of this EventType. - e.g. QList(ParamType("temperature", QVariant::Real)) - */ +/*! Holds a List describing possible parameters for a \l{Event} of this EventType. + * e.g. QList(ParamType("temperature", QVariant::Real)). */ QList EventType::paramTypes() const { return m_paramTypes; } -/*! - Set the parameter description for this EventType to \a parameters, - e.g. QList() << ParamType("temperature", QVariant::Real)) - */ +/*! Set the parameter description for this EventType to \a paramTypes, + * e.g. QList() << ParamType("temperature", QVariant::Real)). */ void EventType::setParamTypes(const QList ¶mTypes) { m_paramTypes = paramTypes; diff --git a/libguh/types/param.cpp b/libguh/types/param.cpp index ab91a6bb..05500fbd 100644 --- a/libguh/types/param.cpp +++ b/libguh/types/param.cpp @@ -30,37 +30,44 @@ #include +/*! Constructs a Param with the given \a name and \a value of the paramter. */ Param::Param(const QString &name, const QVariant &value): m_name (name), m_value(value) { } +/*! Returns the name of this Param. */ QString Param::name() const { return m_name; } +/*! Sets the \a name of this Param. */ void Param::setName(const QString &name) { m_name = name; } +/*! Returns the value of this Param. */ QVariant Param::value() const { return m_value; } +/*! Sets the \a value of this Param. */ void Param::setValue(const QVariant &value) { m_value = value; } +/*! A Param is valid if name and and value are set. Returns true if valid, false if not. */ bool Param::isValid() const { return !m_name.isEmpty() && m_value.isValid(); } +/*! Writes the name and value of the given \a param to \a dbg. */ QDebug operator<<(QDebug dbg, const Param ¶m) { dbg.nospace() << "Param(Name: " << param.name() << ", Value:" << param.value() << ")"; @@ -68,6 +75,7 @@ QDebug operator<<(QDebug dbg, const Param ¶m) return dbg.space(); } +/*! Writes the param of the given \a params to \a dbg. */ QDebug operator<<(QDebug dbg, const ParamList ¶ms) { dbg.nospace() << "ParamList (count:" << params.count() << ")" << endl; @@ -78,7 +86,7 @@ QDebug operator<<(QDebug dbg, const ParamList ¶ms) return dbg.space(); } - +/*! Returns true if this Param contains a Param with the given \a paramName. */ bool ParamList::hasParam(const QString ¶mName) const { foreach (const Param ¶m, *this) { @@ -89,6 +97,7 @@ bool ParamList::hasParam(const QString ¶mName) const return false; } +/*! Returns the value of the Param with the given \a paramName. */ QVariant ParamList::paramValue(const QString ¶mName) const { foreach (const Param ¶m, *this) { @@ -99,6 +108,7 @@ QVariant ParamList::paramValue(const QString ¶mName) const return QVariant(); } +/*! Sets the value of a Param with the given \a paramName to the given \a value. */ void ParamList::setParamValue(const QString ¶mName, const QVariant &value) { for (int i = 0; i < count(); i++) { @@ -109,6 +119,7 @@ void ParamList::setParamValue(const QString ¶mName, const QVariant &value) } } +/*! Appends the given \a param to a ParamList. */ ParamList ParamList::operator<<(const Param ¶m) { this->append(param); diff --git a/libguh/types/paramdescriptor.cpp b/libguh/types/paramdescriptor.cpp index c869d7b8..7e5a599d 100644 --- a/libguh/types/paramdescriptor.cpp +++ b/libguh/types/paramdescriptor.cpp @@ -30,17 +30,21 @@ #include "paramdescriptor.h" +/*! Constructs an ParamDescriptor describing an \l{Param} with the given \a name and \a value. + * The ValueOperator is by default ValueOperatorEquals. */ ParamDescriptor::ParamDescriptor(const QString &name, const QVariant &value): Param(name, value), m_operatorType(Types::ValueOperatorEquals) { } +/*! Returns the ValueOperator of this ParamDescriptor. */ Types::ValueOperator ParamDescriptor::operatorType() const { return m_operatorType; } +/*! Sets the ValueOperator of this ParamDescriptor to the given \a operatorType. */ void ParamDescriptor::setOperatorType(Types::ValueOperator operatorType) { m_operatorType = operatorType; diff --git a/libguh/types/paramtype.cpp b/libguh/types/paramtype.cpp index b16bc6e8..b5f8f33b 100644 --- a/libguh/types/paramtype.cpp +++ b/libguh/types/paramtype.cpp @@ -28,6 +28,7 @@ #include "paramtype.h" +/*! Constructs a ParamType object with the given \a name, \a type and \a defaultValue. */ ParamType::ParamType(const QString &name, const QVariant::Type type, const QVariant &defaultValue): m_name(name), m_type(type), @@ -35,77 +36,92 @@ ParamType::ParamType(const QString &name, const QVariant::Type type, const QVari { } +/*! Returns the name of this ParamType. */ QString ParamType::name() const { return m_name; } +/*! Sets the name of this ParamType to the given \a name. */ void ParamType::setName(const QString &name) { m_name = name; } +/*! Returns the type of this ParamType. */ QVariant::Type ParamType::type() const { return m_type; } +/*! Sets the type of this ParamType to the given \a type. */ void ParamType::setType(QVariant::Type type) { m_type = type; } +/*! Returns the default value of this ParamType. */ QVariant ParamType::defaultValue() const { return m_defaultValue; } +/*! Sets the default value of this ParamType to the given \a defaultValue. */ void ParamType::setDefaultValue(const QVariant &defaultValue) { m_defaultValue = defaultValue; } +/*! Returns the minimum value of this ParamType. */ QVariant ParamType::minValue() const { return m_minValue; } +/*! Sets the minimum value of this ParamType to the given \a minValue. */ void ParamType::setMinValue(const QVariant &minValue) { m_minValue = minValue; } +/*! Returns the maximum value of this ParamType. */ QVariant ParamType::maxValue() const { return m_maxValue; } +/*! Sets the maximum value of this ParamType to the given \a maxValue. */ void ParamType::setMaxValue(const QVariant &maxValue) { m_maxValue = maxValue; } +/*! Returns the limits of this ParamType. limits(minValue, maxValue). */ QPair ParamType::limits() const { return qMakePair(m_minValue, m_maxValue); } +/*! Sets the limits of this ParamType. limits(\a min, \a max). */ void ParamType::setLimits(const QVariant &min, const QVariant &max) { m_minValue = min; m_maxValue = max; } +/*! Returns the list of the allowed values of this ParamType. */ QList ParamType::allowedValues() const { return m_allowedValues; } +/*! Sets the list of the allowed values of this ParamType to the given List of \a allowedValues. */ void ParamType::setAllowedValues(const QList allowedValues) { m_allowedValues = allowedValues; } +/*! Writes the name, type defaultValue, min and max value of the given \a paramType to \a dbg. */ QDebug operator<<(QDebug dbg, const ParamType ¶mType) { dbg.nospace() << "ParamType(Name: " << paramType.name() @@ -118,6 +134,7 @@ QDebug operator<<(QDebug dbg, const ParamType ¶mType) return dbg.space(); } +/*! Writes the name, type defaultValue, min and max value of each \a paramTypes to \a dbg. */ QDebug operator<<(QDebug dbg, const QList ¶mTypes) { dbg.nospace() << "ParamTypeList (count:" << paramTypes.count() << ")" << endl; diff --git a/libguh/types/state.cpp b/libguh/types/state.cpp index 42392584..17f93909 100644 --- a/libguh/types/state.cpp +++ b/libguh/types/state.cpp @@ -32,7 +32,7 @@ #include "state.h" /*! Constructs a State reflecting the \l{StateType} given by \a stateTypeId - and associated with the \l{Device} given by \a deviceId */ + * and associated with the \l{Device} given by \a deviceId */ State::State(const StateTypeId &stateTypeId, const DeviceId &deviceId): m_id(StateId::createStateId()), m_stateTypeId(stateTypeId), @@ -58,24 +58,26 @@ DeviceId State::deviceId() const return m_deviceId; } -/*! Returns the state's value.*/ +/*! Returns the state's value. */ QVariant State::value() const { return m_value; } -/*! Set the state's value to \a value.*/ +/*! Set the state's value to \a value. */ void State::setValue(const QVariant &value) { m_value = value; } +/*! Writes the stateTypeId, the deviceId and the value of the given \a state to \a dbg. */ QDebug operator<<(QDebug dbg, const State &state) { dbg.nospace() << "State(StateTypeId: " << state.stateTypeId().toString() << ", DeviceId:" << state.deviceId() << ", value:" << state.value() << ")"; return dbg.space(); } +/*! Writes each stateTypeId, deviceId and value of the given \a states to \a dbg. */ QDebug operator<<(QDebug dbg, const QList &states) { dbg.nospace() << "StateList (count:" << states.count() << ")"; diff --git a/libguh/types/statedescriptor.cpp b/libguh/types/statedescriptor.cpp index c1a96689..9a1e6b06 100644 --- a/libguh/types/statedescriptor.cpp +++ b/libguh/types/statedescriptor.cpp @@ -31,16 +31,14 @@ #include "statedescriptor.h" -/*! Constructs an StateDescriptor describing an \l{State}. - */ +/*! Constructs an StateDescriptor describing an \l{State}.*/ StateDescriptor::StateDescriptor(): m_operatorType(Types::ValueOperatorEquals) { } -/*! Constructs an StateDescriptor describing an \l{State} with the given \a stateTypeId, \a deviceId, \a stateValue and \a operatorType. - */ +/*! Constructs an StateDescriptor describing an \l{State} with the given \a stateTypeId, \a deviceId, \a stateValue and \a operatorType.*/ StateDescriptor::StateDescriptor(const StateTypeId &stateTypeId, const DeviceId &deviceId, const QVariant &stateValue, Types::ValueOperator operatorType): m_stateTypeId(stateTypeId), m_deviceId(deviceId), @@ -50,36 +48,32 @@ StateDescriptor::StateDescriptor(const StateTypeId &stateTypeId, const DeviceId } -/*! Returns the StateTypeId of this \l{State}. - */ +/*! Returns the StateTypeId of this \l{State}.*/ StateTypeId StateDescriptor::stateTypeId() const { return m_stateTypeId; } -/*! Returns the DeviceId of this \l{State}. - */ +/*! Returns the DeviceId of this \l{State}.*/ DeviceId StateDescriptor::deviceId() const { return m_deviceId; } -/*! Returns the Value of this \l{State}. - */ +/*! Returns the Value of this \l{State}.*/ QVariant StateDescriptor::stateValue() const { return m_stateValue; } -/*! Returns the ValueOperator of this \l{State}. - */ +/*! Returns the ValueOperator of this \l{State}.*/ Types::ValueOperator StateDescriptor::operatorType() const { return m_operatorType; } -/*! Overloads the == operator for this \l{State}.Returns true, if the given \a other \l{StateDescriptor} == this StateDescriptor. - */ +/*! Compare this StateDescriptor to \a other. + * StateDescriptors are equal (returns true) if stateTypeId, stateValue and operatorType match. */ bool StateDescriptor::operator ==(const StateDescriptor &other) const { return m_stateTypeId == other.stateTypeId() && @@ -88,8 +82,8 @@ bool StateDescriptor::operator ==(const StateDescriptor &other) const m_operatorType == other.operatorType(); } -/*! Overloads the == operator for this \l{State}. Returns true, if the given \a state == an other \l{State}. - */ +/*! Compare this StateDescriptor to the \l{State} given by \a state. + * States are equal (returns true) if stateTypeId, deviceId and ValueOperator match. */ bool StateDescriptor::operator ==(const State &state) const { if ((m_stateTypeId != state.stateTypeId()) || (m_deviceId != state.deviceId())) { @@ -112,8 +106,8 @@ bool StateDescriptor::operator ==(const State &state) const return false; } -/*! Overloads the != operator for this \l{State}. Returns true, if the given \a state != an other \l{State}. - */ +/*! Compare this StateDescriptor to the \l{State} given by \a state. + * Returns true, if stateTypeId, deviceId or ValueOreator are different from the given \a state. */ bool StateDescriptor::operator !=(const State &state) const { return !(operator==(state)); diff --git a/libguh/types/statetype.cpp b/libguh/types/statetype.cpp index 45dd5ff5..948da9d7 100644 --- a/libguh/types/statetype.cpp +++ b/libguh/types/statetype.cpp @@ -18,7 +18,7 @@ /*! \class StateType - \brief Describes a \l{State} for a \l{Device}. + \brief Describes the Type of a \l{State} from \l{Device}. \ingroup types \inmodule libguh @@ -28,27 +28,27 @@ #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. */ +/*! Constructs a StateType 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 StateTypeId &id): m_id(id) { } -/*! Returns the id of the StateType.*/ +/*! Returns the id of the StateType. */ StateTypeId StateType::id() const { return m_id; } -/*! Returns the name of the StateType. This is visible to the user (e.g. "Temperature").*/ +/*! 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").*/ +/*! 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; @@ -60,13 +60,13 @@ QVariant::Type StateType::type() const return m_type; } -/*! Set the type fo the StateType to \a type (e.g. QVariant::Real).*/ +/*! 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) */ +/*! Returns the default value of this StateType (e.g. 21.5). */ QVariant StateType::defaultValue() const { return m_defaultValue; diff --git a/libguh/types/vendor.cpp b/libguh/types/vendor.cpp index 5e9fecce..573330eb 100644 --- a/libguh/types/vendor.cpp +++ b/libguh/types/vendor.cpp @@ -28,32 +28,31 @@ #include "vendor.h" -/*! Constructs an Vendor with the given \a id and the given \a name. - */ +/*! Constructs an Vendor with the given \a id and the given \a name. */ Vendor::Vendor(const VendorId &id, const QString &name): m_id(id), m_name(name) { } -/*! Returns the id of this vendor. */ +/*! Returns the id of this Vendor. */ VendorId Vendor::id() const { return m_id; } -/*! Set the id of this vendor with the given \a id. */ +/*! Set the id of this Vendor with the given \a id. */ void Vendor::setId(const VendorId &id) { m_id = id; } -/*! Returns the name of this vendor. */ +/*! Returns the name of this Vendor. */ QString Vendor::name() const { return m_name; } -/*! Set the name of this vendor with the given \a name. */ +/*! Set the name of this Vendor with the given \a name. */ void Vendor::setName(const QString &name) { m_name = name;