ETM-Schurig/powersync-core
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

added documentation and fixed some doc errors

Browse Source
This commit is contained in:
Simon Stürz 2014-10-25 15:21:06 +02:00 committed by Michael Zanetti
parent 5cd3154b64
commit 1f697b2b1a
15 changed files with 198 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/config.qdocconf
View File

@ -12,5 +12,5 @@ headers.fileextensions = "*.h"
imagedirs = images
sourcedirs = ..
sources.fileextensions = "*.cpp *.qdoc"
sources.fileextensions = "*.cpp *.qdoc *.json"

2
doc/jsonrpc.qdoc
View File

@ -161,5 +161,5 @@
"status": "success"
}
\endcode
*/

81
libguh/devicemanager.cpp
View File

@ -42,7 +42,8 @@
\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.
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.
*/
/*!
@ -52,21 +53,58 @@
\value DeviceErrorNoError
No Error. Everything went fine.
\value DeviceErrorPluginNotFound
Couldn't find the Plugin for the given id.
\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 DeviceErrorStateTypeNotFound
Couldn't find the \l{StateType} for the given id.
\value DeviceErrorEventTypeNotFound
Couldn't find the \l{EventType} for the given id.
\value DeviceErrorDeviceDescriptorNotFound
Couldn't find the \l{DeviceDescriptor} 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 DeviceErrorInvalidParameter
One of the given parameter is not valid.
\value DeviceErrorSetupFailed
Error setting up the \{Device}. It will not be functional.
Error setting up the \l{Device}. It will not be functional.
\value DeviceErrorDuplicateUuid
Error setting up the \l{Device}. The given DeviceId allready exists.
\value DeviceErrorCreationMethodNotSupported
Error setting up the \l{Device}. This \l{DeviceClass}{CreateMethod} is not supported for this \l{Device}.
\value DeviceErrorSetupMethodNotSupported
Error setting up the \l{Device}. This \l{DeviceClass}{SetupMethod} is not supported for this \l{Device}.
\value DeviceErrorHardwareNotAvailable
The Hardware of the \l{Device} is not available.
\value DeviceErrorHardwareFailure
The Hardware of the \l{Device} has an error.
\value DeviceErrorAsync
The response of the \l{Device} will be asynchronous.
\value DeviceErrorDeviceInUse
The \l{Device} is currently bussy.
\value DeviceErrorPairingTransactionIdNotFound
Couldn't find the PairingTransactionId for the given id.
*/
/*! \fn void DeviceManager::emitEvent(const Event &event)
/*!
\enum DeviceManager::DeviceSetupStatus
This enum type specifies the setup status of a \l{Device}.
\value DeviceSetupStatusSuccess
No Error. Everything went fine.
\value DeviceSetupStatusFailure
Something went wrong during the setup.
\value DeviceSetupStatusAsync
The status of the \l{Device} setup will be emitted asynchronous.
*/
/*! \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
after checking back with the \{RulesEngine}. Exceptions might be monitoring interfaces
@ -119,6 +157,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.*/
DeviceManager::~DeviceManager()
{
qDebug() << "Shutting down DeviceManager";
@ -139,6 +178,8 @@ 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 */
DeviceManager::DeviceError DeviceManager::setPluginConfig(const PluginId &pluginId, const ParamList &pluginConfig)
{
DevicePlugin *plugin = m_devicePlugins.value(pluginId);
@ -160,6 +201,7 @@ DeviceManager::DeviceError DeviceManager::setPluginConfig(const PluginId &plugin
return result;
}
/*! Returns all the \l{Vendor}s loaded in the system. */
QList<Vendor> DeviceManager::supportedVendors() const
{
return m_supportedVendors.values();
@ -179,7 +221,8 @@ QList<DeviceClass> 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.*/
DeviceManager::DeviceError DeviceManager::discoverDevices(const DeviceClassId &deviceClassId, const ParamList &params)
{
qDebug() << "DeviceManager discoverdevices" << params;
@ -209,23 +252,10 @@ DeviceManager::DeviceError DeviceManager::discoverDevices(const DeviceClassId &d
}
/*! 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}.
\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{DeviceManager::DeviceError} to inform about the result.
\list
\li DeviceManager::DeviceErrorNoError: The device has been created, set up and added to the list of configured devices correctly.
\li DeviceManager::DeviceErrorAsync: The device has been created, but the setup requires async operations. For instance a network query.
In this case, you should wait for the \l{deviceSetupFinished()} signal to get the final results.
\li DeviceManager::DeviceErrorCreateMethodNotSupported: The deviceId you've chosen refers to a DeviceClass which can't be created manually.
\li DeviceManager::DeviceErrorDeviceClassNotFound: The given deviceClassId can't be found in the list of supported devices.
\li DeviceManager::DeviceErrorMissingParameter: The given params do not suffice for the given deviceClassId.
\li DeviceManager::DeviceErrorDeviceParameterError: The given params can't be matched to the ParamTypes for the given deviceClassId.
\li DeviceManager::DeviceErrorDuplicateUuid: The given uuid already exists.
\li DeviceManager::DeviceErrorPluginNotFound: Couldn't find a plugin that handles this deviceClassId.
\li DeviceManager::DeviceErrorSetupFailed: The device couldn't be set up. Even though you supplied all the parameters correctly, something
went wrong during setup. Reasons may be a hardware/network failure, wrong username/password or similar, depending on what the device plugin
needs to do in order to set up the device.
Returns \l{DeviceError} to inform about the result.
*/
DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassId &deviceClassId, const ParamList &params, const DeviceId id)
{
@ -239,6 +269,11 @@ 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.
*/
DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassId &deviceClassId, const DeviceDescriptorId &deviceDescriptorId, const DeviceId &deviceId)
{
DeviceClass deviceClass = findDeviceClass(deviceClassId);
@ -257,6 +292,10 @@ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassI
return addConfiguredDeviceInternal(deviceClassId, descriptor.params(), deviceId);
}
/*!
Returns \l{DeviceManager}{DeviceError} to inform about the result.
*/
DeviceManager::DeviceError DeviceManager::pairDevice(const PairingTransactionId &pairingTransactionId, const DeviceClassId &deviceClassId, const ParamList &params)
{
DeviceClass deviceClass = findDeviceClass(deviceClassId);

74
libguh/plugin/deviceclass.cpp
View File

@ -16,8 +16,7 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class DeviceClass
/*! \class DeviceClass
\brief Describes \l{Device}{Devices}.
\ingroup devices
@ -32,13 +31,38 @@
\sa Device
*/
/*! \enum DeviceClass::CreateMethod
This enum type specifies the CreateMethod of this \l{DeviceClass}
\value CreateMethodUser
The user will specify the \l{Param}s.
\value CreateMethodAuto
The device will be created automaticaly.
\value CreateMethodDiscovery
The device will be discovered and added by the user by specifying the DeviceDescriptorId.
*/
/*! \enum DeviceClass::SetupMethod
This enum type specifies the SetupMethod of this \l{DeviceClass}
\value SetupMethodJustAdd
The \l{Device} will be just added. This is the default value.
\value SetupMethodDisplayPin
During the setup, a pin will be displayed on the \l{Device}. The pin will be needed in order to pair the device.
\value SetupMethodEnterPin
During the setup, a pin will be needed in order to pair the \l{Device}.
\value SetupMethodPushButton
During the setup, a button has to be pushed in order to pair the \l{Device}.
*/
#include "deviceclass.h"
/*! Constructs a DeviceClass with the give \a pluginId and \a id.
/*! Constructs a DeviceClass with the give \a pluginId ,\a vendorId 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.
*/
should never change or it will appear as a new DeviceClass in the system.*/
DeviceClass::DeviceClass(const PluginId &pluginId, const VendorId &vendorId, const DeviceClassId &id):
m_id(id),
m_vendorId(vendorId),
@ -46,34 +70,33 @@ DeviceClass::DeviceClass(const PluginId &pluginId, const VendorId &vendorId, con
m_createMethods(CreateMethodUser),
m_setupMethod(SetupMethodJustAdd)
{
}
/*! Returns the id of this DeviceClass. */
/*! Returns the id of this \l{DeviceClass}. */
DeviceClassId DeviceClass::id() const
{
return m_id;
}
/*! Returns the VendorId for this DeviceClass */
/*! Returns the VendorId for this \l{DeviceClass} */
VendorId DeviceClass::vendorId() const
{
return m_vendorId;
}
/*! Returns the pluginId this DeviceClass is managed by. */
/*! Returns the pluginId this \l{DeviceClass} is managed by. */
PluginId DeviceClass::pluginId() const
{
return m_pluginId;
}
/*! Returns true if this DeviceClass's id, vendorId and pluginId are valid uuids. */
/*! Returns true if this \l{DeviceClass}'s id, vendorId and pluginId are valid uuids. */
bool DeviceClass::isValid() const
{
return !m_id.isNull() && !m_vendorId.isNull() && !m_pluginId.isNull();
}
/*! Returns the name of this DeviceClass's. This is visible to the user. */
/*! Returns the name of this \l{DeviceClass}'s. This is visible to the user. */
QString DeviceClass::name() const
{
return m_name;
@ -86,14 +109,14 @@ void DeviceClass::setName(const QString &name)
}
/*! Returns the statesTypes of this DeviceClass. \{Device}{Devices} created
from this DeviceClass must have their states matching to this template. */
from this \l{DeviceClass} must have their states matching to this template. */
QList<StateType> DeviceClass::stateTypes() const
{
return m_stateTypes;
}
/*! Set the \a stateTypes of this DeviceClass. \{Device}{Devices} created
from this DeviceClass must have their states matching to this template. */
from this \l{DeviceClass} must have their states matching to this template. */
void DeviceClass::setStateTypes(const QList<StateType> &stateTypes)
{
m_stateTypes = stateTypes;
@ -109,14 +132,14 @@ void DeviceClass::setStateTypes(const QList<StateType> &stateTypes)
}
/*! Returns the eventTypes of this DeviceClass. \{Device}{Devices} created
from this DeviceClass must have their events matching to this template. */
from this \l{DeviceClass} must have their events matching to this template. */
QList<EventType> DeviceClass::eventTypes() const
{
return m_allEventTypes;
}
/*! Set the \a eventTypes of this DeviceClass. \{Device}{Devices} created
from this DeviceClass must have their events matching to this template. */
from this \l{DeviceClass} must have their events matching to this template. */
void DeviceClass::setEventTypes(const QList<EventType> &eventTypes)
{
m_eventTypes = eventTypes;
@ -132,68 +155,79 @@ void DeviceClass::setEventTypes(const QList<EventType> &eventTypes)
}
/*! Returns the actionTypes of this DeviceClass. \{Device}{Devices} created
from this DeviceClass must have their actions matching to this template. */
from this \l{DeviceClass} must have their actions matching to this template. */
QList<ActionType> DeviceClass::actionTypes() const
{
return m_actionTypes;
}
/*! Set the \a actionTypes of this DeviceClass. \{Device}{Devices} created
from this DeviceClass must have their actions matching to this template. */
from this \l{DeviceClass} must have their actions matching to this template. */
void DeviceClass::setActionTypes(const QList<ActionType> &actionTypes)
{
m_actionTypes = actionTypes;
}
/*! Returns the params description of this DeviceClass. \{Device}{Devices} created
from this DeviceClass must have their params matching to this template. */
from this \l{DeviceClass} must have their params matching to this template. */
QList<ParamType> DeviceClass::paramTypes() const
{
return m_paramTypes;
}
/*! Set the \a params of this DeviceClass. \{Device}{Devices} created
from this DeviceClass must have their actions matching to this template. */
from this \l{DeviceClass} must have their actions matching to this template. */
void DeviceClass::setParamTypes(const QList<ParamType> &params)
{
m_paramTypes = params;
}
/*! Returns the discovery params description of this DeviceClass. \{Device}{Devices} created
from this \l{DeviceClass} must have their params matching to this template. */
QList<ParamType> DeviceClass::discoveryParamTypes() const
{
return m_discoveryParamTypes;
}
/*! Set the \a params of this DeviceClass for the discovery. \{Device}{Devices} created
from this \l{DeviceClass} must have their actions matching to this template. */
void DeviceClass::setDiscoveryParamTypes(const QList<ParamType> &params)
{
m_discoveryParamTypes = params;
}
/*! Returns the \l{DeviceClass::CreateMethod}s of this \l{DeviceClass}.*/
DeviceClass::CreateMethods DeviceClass::createMethods() const
{
return m_createMethods;
}
/*! Set the \a createMethods of this \l{DeviceClass}.
\sa CreateMethod, */
void DeviceClass::setCreateMethods(DeviceClass::CreateMethods createMethods)
{
m_createMethods = createMethods;
}
/*! Returns the \l{DeviceClass::SetupMethod} of this \l{DeviceClass}.*/
DeviceClass::SetupMethod DeviceClass::setupMethod() const
{
return m_setupMethod;
}
/*! Set the \a setupMethod of this \l{DeviceClass}.
\sa SetupMethod, */
void DeviceClass::setSetupMethod(DeviceClass::SetupMethod setupMethod)
{
m_setupMethod = setupMethod;
}
/*! Returns the pairing information of this \l{DeviceClass}.*/
QString DeviceClass::pairingInfo() const
{
return m_pairingInfo;
}
/*! Set the \a pairingInfo of this \l{DeviceClass}. */
void DeviceClass::setPairingInfo(const QString &pairingInfo)
{
m_pairingInfo = pairingInfo;

11
libguh/plugin/devicedescriptor.cpp
View File

@ -16,6 +16,17 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class DeviceDescriptor
\brief Describes \l{Device}{Devices}.
\ingroup devices
\inmodule libguh
\sa Device
*/
#include "devicedescriptor.h"
DeviceDescriptor::DeviceDescriptor():

4
libguh/plugin/deviceplugin.cpp
View File

@ -46,7 +46,7 @@ pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId(
*/
/*!
\fn void DevicePlugin::radioData(QList<int> rawData)
\fn void DevicePlugin::radioData(const QList<int> &rawData)
If the plugin has requested any radio device using \l{DevicePlugin::requiredHardware()}, this slot will
be called when there is \a rawData available from that device.
*/
@ -74,7 +74,7 @@ pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId(
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 DevicePlugin::report(), DevicePlugin::actionExecutionFinished()
*/
/*!

10
libguh/types/param.cpp
View File

@ -16,6 +16,16 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class Param
\brief Holds the parameters of a Param.
\ingroup types
\inmodule libguh
\sa Device, ParamType, ParamDescriptor
*/
#include "param.h"
#include <QDebug>

12
libguh/types/paramdescriptor.cpp
View File

@ -16,6 +16,18 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class ParamDescriptor
\brief Describes a certain \l{Param}.
\ingroup types
\inmodule libguh
An ParamDescriptor describes a \l{Param} in order to match it with a \l{Rule}.
\sa State, Rule
*/
#include "paramdescriptor.h"
ParamDescriptor::ParamDescriptor(const QString &name, const QVariant &value):

10
libguh/types/paramtype.cpp
View File

@ -15,6 +15,16 @@
* along with guh. If not, see <http://www.gnu.org/licenses/>. *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class ParamType
\brief Describes a certain ParamType.
\ingroup types
\inmodule libguh
\sa Device, Param
*/
#include "paramtype.h"

13
libguh/types/statedescriptor.cpp
View File

@ -16,6 +16,19 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class StateDescriptor
\brief Describes a certain \l{State}.
\ingroup types
\inmodule libguh
An StateDescriptor describes a \l{State} in order to match it with a \l{Rule}.
\sa State, Rule
*/
#include "statedescriptor.h"
StateDescriptor::StateDescriptor():

10
libguh/types/vendor.cpp
View File

@ -16,6 +16,16 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class Vendor
\brief Holds information about a the vendor of a \l{Device}.
\ingroup types
\inmodule libguh
\sa Device
*/
#include "vendor.h"
Vendor::Vendor(const VendorId &id, const QString &name):

2
plugins/deviceplugins/eq-3/deviceplugineq-3.cpp
View File

@ -17,7 +17,7 @@
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\page wemo.html
\page eq3.html
\title eQ-3 Max!
\ingroup plugins

1
plugins/deviceplugins/openweathermap/devicepluginopenweathermap.cpp
View File

@ -265,6 +265,7 @@
\li 413b3fc6-bd1c-46fb-8c86-03096254f94f
\li unsigned int
\endtable
*/

18
server/rule.cpp
View File

@ -32,17 +32,17 @@
\sa EventDescriptor, State, Action
*/
/*! \enum Rule::RuleType
//! \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.
// 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.
\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"

6
server/ruleengine.cpp
View File

@ -30,11 +30,11 @@
\sa Event, EventDescriptor, Rule, Action
*/
/*! \fn void RuleEngine::ruleAdded(const QUuid &ruleId)
/*! \fn void RuleEngine::ruleAdded(const RuleId &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)
/*! \fn void RuleEngine::ruleRemoved(const RuleId &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.*/
@ -48,7 +48,7 @@
Couldn't find a \l{Device} with the given id.
\value RuleErrorEventTypeNotFound
Couldn't find a \l{EventType} with the given id.
*/
*/
#include "ruleengine.h"
#include "types/paramdescriptor.h"