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

Add API documentation

Browse Source
This commit is contained in:
Simon Stürz 2018-02-27 21:03:31 +01:00 committed by Michael Zanetti
parent 3719d315b5
commit 1f58300352
40 changed files with 4776 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/coap.qdoc
View File

@ -4,7 +4,7 @@
In order to interact with a CoAP (Constrained Application Protocol) server nymea provides following classes:
\annotatedlist coap
\annotatedlist coap-group
*/

245
doc/generate-api-qdoc.py Executable file
View File

@ -0,0 +1,245 @@
#!/usr/bin/env python
# -*- coding: UTF-8 -*-
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# #
# Copyright (C) 2018 Simon Stuerz <simon.stuerz@guh.io> #
# #
# This file is part of guh. #
# #
# guh is free software: you can redistribute it and/or modify #
# it under the terms of the GNU General Public License as published by #
# the Free Software Foundation, version 2 of the License. #
# #
# guh is distributed in the hope that it will be useful, #
# but WITHOUT ANY WARRANTY; without even the implied warranty of #
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the #
# GNU General Public License for more details. #
# #
# You should have received a copy of the GNU General Public License #
# along with guh. If not, see <http://www.gnu.org/licenses/>. #
# #
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
import argparse
import traceback
import json
import os
import subprocess
__version__='1.0.0'
#--------------------------------------------------------------------------
def printInfo(info):
print(info)
#--------------------------------------------------------------------------
def printWarning(warning):
print('Warning: ' + warning)
#--------------------------------------------------------------------------
def printError(error):
print('Error: ' + error)
#--------------------------------------------------------------------------
def writeToFile(line):
outputFile.write('%s\n' % line)
#--------------------------------------------------------------------------
def writeCodeSection(jsonData):
writeToFile('\code')
writeToFile(json.dumps(jsonData, sort_keys=True, indent=4))
writeToFile('\endcode')
#--------------------------------------------------------------------------
def getJsonString(object, key):
for objectKey, value in object.items():
if objectKey is key:
return value
return None
#--------------------------------------------------------------------------
def extractReferences(object):
referenceList = []
for key, value in object.iteritems():
keyString = ('%s' % key)
if keyString.startswith('$ref:'):
referenceList.append(keyString)
valueString = ('%s' % value)
if valueString.startswith('$ref:'):
referenceList.append(valueString)
elif isinstance(value, dict):
referenceList.extend(extractReferences(value))
elif isinstance(value, list):
for item in value:
itemString = ('%s' % item)
if itemString.startswith('$ref:'):
referenceList.append(itemString)
elif isinstance(item, dict):
referenceList.extend(extractReferences(item))
return referenceList
#--------------------------------------------------------------------------
def createReferenceLine(object):
# Get list of all references
referenceList = []
fullReferenceList = extractReferences(object)
for reference in fullReferenceList:
if reference not in referenceList:
referenceList.append(reference.replace('$ref:', ''))
if not referenceList:
return ""
# Write references from content
referencesString = "See also: "
referenceCount = len(referenceList)
for i in range(len(referenceList)):
if i is referenceCount - 1:
referencesString += '\l{%s}' % referenceList[i]
else:
referencesString += '\l{%s}, ' % referenceList[i]
return referencesString
#--------------------------------------------------------------------------
def extractTypes(types):
typesList = []
for type in types:
typesList.append(type)
typesSorted = sorted(typesList)
for type in typesSorted:
writeToFile('\section3 %s' % type)
writeCodeSection(types[type])
if isinstance(types[type], dict):
writeToFile(createReferenceLine(types[type]))
#--------------------------------------------------------------------------
def extractMethods(methods):
methodsList = []
for method in methods:
methodsList.append(method)
methodsSorted = sorted(methodsList)
for method in methodsSorted:
writeToFile('\section3 %s' % method)
writeToFile('%s' % methods[method]['description'])
writeToFile('\section4 Params')
writeCodeSection(methods[method]['params'])
writeToFile('\section4 Returns')
writeCodeSection(methods[method]['returns'])
writeToFile(createReferenceLine(methods[method]))
#--------------------------------------------------------------------------
def extractNotifications(notifications):
notificationsList = []
for notification in notifications:
notificationsList.append(notification)
notificationsSorted = sorted(notificationsList)
for notification in notificationsSorted:
writeToFile('\section3 %s' % notification)
writeToFile('%s' % notifications[notification]['description'])
writeToFile('\section4 Params')
writeCodeSection(notifications[notification]['params'])
writeToFile(createReferenceLine(notifications[notification]))
#--------------------------------------------------------------------------
def writeDocumentationContent(apiVersion, apiJson):
printInfo('--> Write API documentation content')
printInfo('--> API version: \"%s\"' % (version))
writeToFile('In following section you can find a detaild description of the current API version %s.' % apiVersion)
writeToFile('\list')
writeToFile('\li \l{Types}')
writeToFile('\li \l{Methods}')
writeToFile('\li \l{Notifications}')
writeToFile('\endlist')
if 'types' in apiJson:
writeToFile('\section1 Types')
extractTypes(apiJson['types'])
if 'methods' in apiJson:
writeToFile('\section1 Methods')
extractMethods(apiJson['methods'])
if 'notifications' in apiJson:
writeToFile("\section2 Notifications")
extractNotifications(apiJson['notifications'])
writeToFile("\section1 Full introspect")
writeCodeSection(apiJson)
###########################################################################
# Main
###########################################################################
if __name__ == '__main__':
parser = argparse.ArgumentParser(description='This tool generates a qdoc file out of the api.json file for the online documentation.')
parser.add_argument('-v', '--version', action='version', version=__version__)
parser.add_argument('-j', '--jsonfile', help='The API JSON input file name with the JSON RPC api definition', metavar='jsonfile', default='../tests/auto/api.json')
parser.add_argument('-o', '--output', help='The qdoc outputFile with the generated documentation script', metavar='output', default='./jsonrpc-api.qdoc')
args = parser.parse_args()
# Print build information for debugging
printInfo('Json file: %s' % (args.jsonfile))
printInfo('Output: %s' % (args.output))
# Open API file for reading
try:
inputFile = open(args.jsonfile, 'r')
except:
printError('Could not open input file \"%s\"' % (args.jsonfile))
exit -1
# Open qdoc file for writing
try:
outputFile = open(args.output, 'w')
except:
printError('Could not open output file \"%s\"' % (args.output))
exit -1
# Read version line and create json content of the rest
inputFileContent = inputFile.read().splitlines(True)
inputFile.close()
# Parse verion and json data
version = inputFileContent[0].strip()
jsonRawContent = ''
for line in inputFileContent[1:]:
jsonRawContent += line
# Parse json content
try:
apiJson = json.loads(jsonRawContent)
except ValueError as error:
printError(' --> Could not load json content')
printError(' %s' % (error))
exit -1
# Sort alphabetically
apiJsonSortedRaw = json.dumps(apiJson, sort_keys=True, indent=4)
apiJsonSorted = json.loads(apiJsonSortedRaw)
writeDocumentationContent(version, apiJsonSorted)

3766
doc/jsonrpc-api.qdoc Normal file
View File

File diff suppressed because it is too large Load Diff

193
doc/jsonrpc.qdoc
View File

@ -3,15 +3,15 @@
\title JSON-RPC API
\ingroup jsonrpc
\brief The JSON RPC interface represents a TCP socket connection using plaintext string communication.
\brief The JSON RPC interface represents a socket connection using plaintext string communication.
\section1 Description
\chapter Description
The JSON RPC interface represents a TCP socket connection using plaintext string communication.
The JSON RPC interface represents a socket connection using plaintext string communication.
Messages are exchanged using the JSON format. Please note that this is not a REST API as the
transport channel is not based on HTTP. It is an internal RPC mechanism to allow communication
between the nymea Server and the main controller interface. This communication socket is not meant
to be exported to the outside of the of the systen as it allows arbitrary commands to manipulate
between the guh Server and the main controller interface. This communication socket is not meant
to be exported to the outside of the of the system as it allows arbitrary commands to manipulate
the system.
The JSON message protocol communicates by exchanging JSON Objects with the following properties:
@ -29,141 +29,68 @@
the requested method.
\endlist
The JSONRPC API is self documenting and can be introspected by calling \c"JSONRPC.Introspect".
\chapter Handshake
Parameters are optional if the type is the type is prefixed with "o:" for optional.
\section1 Communicating with the server
The server listens by default on TCP port 2222 for incoming TCP connections. It will respond to incoming connections with a some information about the server. Telnet can be used to issue commands for testing.
An example how to communicate with the API using telnet on the same host where the nymea server
is running:
\code
$ telnet localhost 2222
\endcode
\code
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{
"id": 0,
"protocol version": 28,
"server": "nymea JSONRPC interface",
"version": "0.6.0"
}
\endcode
Now the connection is established and waits for commands.
\section1 Classes
\annotatedlist json
\section1 Examples
\section2 Introspect API
\section3 Request
Once connected to the socket, the server will send immediatly a handshake message. The handshake message
is a JSON object and contains all relevant information about the server and the API in order to start
communicationg with the server.
Here is an example of the handshare:
\code
{
"id": 1,
"method":"JSONRPC.Introspect"
}
\endcode
\section3 Response
\code
{
"id": 1,
"params": {
"methods": {
...
"Devices.GetSupportedDevices": {
"description": "Returns a list of supported Device classes.",
"params": {
},
"returns": {
"deviceClasses": [
"$ref:DeviceClass"
]
}
},
...
},
"types": {
...
"DeviceClass": {
"actions": [
"$ref:ActionType"
],
"id": "uuid",
"name": "string",
"params": [
"$ref:ParamType"
],
"states": [
"$ref:StateType"
],
"events": [
"$ref:EventType"
]
},
...
}
},
"status": "success"
"id": 0,
"name": "guh",
"protocol version": "1.2",
"authenticationRequired": false,
"initialSetupRequired": false,
"pushButtonAuthAvailable": false,
"server": "guhIO",
"language": "de_DE",
"uuid": "{42842b0f-a7bb-4a94-b624-a55f31c5603e}",
"version": "0.8.3"
}
\endcode
\section2 Getting a list of supported devices
\section3 Request
\code
{
"id":1,
"method":"Devices.GetSupportedDevices"
}
\endcode
\section3 Response:
\code {
"id": 1,
"params": {
"deviceClasses": [
{
"actions": [
],
"id": "{bd216356-f1ec-4324-9785-6982d2174e17}",
"name": "WiFi Device",
"params": [
{
"name": "mac",
"type": "string"
}
],
"states": [
{
"id": "{cb43e1b5-4f61-4538-bfa2-c33055c542cf}",
"name": "inRange",
"type": "bool"
}
],
"events": [
{
"id": "{7cae711a-a0af-41b4-b3bf-38d3e23b41ba}",
"name": "inRange",
"params": [
{
"name": "inRange",
"type": "bool"
}
]
}
]
}
...
]
}
"status": "success"
}
\endcode
\list
\li \code "id": int \endcode
The id in the handshake has always the value 0. This is the first message during connection.
\li \code "name": string \endcode
This field represents the name of the server you are connected to. This name is user defined an can be changed.
(Example: \c"JSONRPC.Introspect")
\li \code "protocol version": string \endcode
The field represents the API version of the server you are connected to. This should be used for API compatibility checks
\li \code "authenticationRequired": bool \endcode
If this property is true, a client must perform the authentication process before beeing able to interact with the API. See section \l{Authentication} for more information.
\li \code "initialSetupRequired": bool \endcode
This property indicates if the server was set up already. A server is set up if a user has been created. If the \tt authenticationRequired property is \tt{false}, this field can be ignored.
\li \code "pushButtonAuthAvailable": bool \endcode
This property indicates if the server has a running push-button agent and therefore the push-button authentication available. If the \tt authenticationRequired property is \tt{false}, this field can be ignored.
\li \code "server": string \endcode
This property holds the name of the server. This name can not be changed.
\li \code "language": string \endcode
This property holds the language of the server. The language can be changed in the settings.
\li \code "uuid": string \endcode
This property holds the UUID of the server and can be used as a unique identifier.
\li \code "version": string \endcode
This property holds the build version of the server.
\endlist
\chapter Authentication
The API has an authentication mechanism, which makes sure that no unauthorized network participent can perform actions or get information from the server. For using the authentication the \tt authenticationRequired property in the \l{Handshake}{handshake} must be \tt{true}.
\section2 Create a user
\section2 Authenticate
\chapter API
\include jsonrpc-api.qdoc
\section1 Newest JSON-RPC API

2
doc/libnymea.qdoc
View File

@ -12,7 +12,7 @@
\annotatedlist hardware
\chapter CoAP
\annotatedlist coap
\annotatedlist coap-group
*/

8
doc/main.css
View File

@ -290,12 +290,12 @@ strong {
:not(pre) > code,
:not(pre) > kbd,
:not(pre) > samp {
font-size: 0.875rem;
font-size: 1.1rem;
font-family: Consolas, monaco, monospace;
color: #d63843;
color: #3d8077;
white-space: nowrap;
padding: 2px 6px;
background: #efefef;
/* background: #efefef; */
}
em {
@ -969,7 +969,7 @@ h2:after, h3.fn:after {
margin: 0 auto 0 0;
left: 0;
right: 0;
width: 20%;
width: 100%;
background: #d3d5d6;
}

13
doc/nymea.qdoc
View File

@ -1,6 +1,8 @@
/*!
\page index.html
Welcome to the guh developer documentation. Here you can find information related to the development for guh.
\section1 Overview
The nymea daemon consists of three main modules:
@ -21,15 +23,8 @@
\li \l{Type Utils}{Global types of nymea (Type Utils)}
\li \l{CoAP}{The CoAP API}
\endlist
\li \l{Plugins}{The nymea plugins}
\endlist
\section1 API's
The nymea daemon provides two API's:
\list
\li \l{JSON-RPC API}{JSON-RPC}
\li \l{https://github.com/guh/nymea/wiki/REST-API}{REST}
\endlist
\section1 Write your own plugin
Here you can find some tutorials for developing and working with nymea:
@ -43,6 +38,8 @@
\section1 Client developers
\list
\li \l{JSON-RPC API}{The API description}
\li \l{Interfaces for DeviceClasses}
\li \l{Paramtypes and the coresponding UI elements}
\endlist

4
libnymea-core/hardware/network/avahi/qtavahiservice.cpp
View File

@ -24,7 +24,7 @@
\class QtAvahiService
\brief Allows to publish an avahi service to the network.
\inmodule libnymea
\inmodule core
*/
/*! \enum QtAvahiService::QtAvahiServiceState
@ -44,7 +44,7 @@
*/
/*! \fn void QtAvahiService::serviceStateChanged(const QtAvahiServiceState &state);
/*! \fn void QtAvahiService::serviceStateChanged(const QtAvahiServiceState &state)
This signal will be emitted when the \a state of this \l{QtAvahiService} has changed.
*/

6
libnymea/coap/coap.cpp
View File

@ -22,7 +22,7 @@
\class Coap
\brief The client connection class to a CoAP server.
\ingroup coap
\ingroup coap-group
\inmodule libnymea
The Coap class provides a signal solt based communication with a \l{https://tools.ietf.org/html/rfc7252}{CoAP (Constrained Application Protocol)}
@ -67,7 +67,7 @@
/*! \fn void Coap::notificationReceived(const CoapObserveResource &resource, const int &notificationNumber, const QByteArray &payload);
This signal is emitted when a value of an observed \a resource changed. The \a notificationNumber specifies the the count of the notification
to keep the correct order. The value can be parsed from the \a payload.
to keep the correct order. The value can be parsed from the \a payload parameter.
*/
#include "coap.h"
@ -76,7 +76,7 @@
Q_LOGGING_CATEGORY(dcCoap, "Coap")
/*! Constructs a coap access manager with the given \a parent and \a port. */
/*! Constructs a Coap access manager with the given \a parent and \a port. */
Coap::Coap(QObject *parent, const quint16 &port) :
QObject(parent),
m_reply(0)

2
libnymea/coap/coapobserveresource.cpp
View File

@ -27,7 +27,7 @@
The CoapObserveResource class holds information about an observed resource.
\sa Coap::notificationReceived()
\sa Coap
*/

14
libnymea/coap/coapoption.cpp
View File

@ -60,28 +60,18 @@
*/
/*! \fn CoapOption::CoapOption();
Constructs a \l{CoapOption}.
*/
/*! \fn CoapOption::CoapOption(const Option &option, const QByteArray &data);
Constructs a \l{CoapOption} with the given \a option and option \a data.
*/
/*! \fn void CoapOption::setOption(const Option &option);
Sets the \l{CoapOption::Option} of this CoapOption to the given \a option.
*/
#include "coapoption.h"
#include <QMetaEnum>
/*! Constructs a CoapOption. */
CoapOption::CoapOption()
{
}
/*! Sets the \a option of this CoapOption to the given parameter. */
void CoapOption::setOption(const CoapOption::Option &option)
{
m_option = option;

2
libnymea/coap/coapoption.h
View File

@ -57,7 +57,7 @@ public:
CoapOption();
void setOption(const Option &option);
void setOption(const CoapOption::Option &option);
Option option() const;
void setData(const QByteArray &data);

2
libnymea/coap/coappdu.cpp
View File

@ -22,7 +22,7 @@
\class CoapPdu
\brief Represents a CoAP protocol data unit (PDU).
\ingroup coap
\ingroup coap-group
\inmodule libnymea
*/

2
libnymea/coap/coapreply.cpp
View File

@ -22,7 +22,7 @@
\class CoapReply
\brief Represents a reply of a CoAP request.
\ingroup coap
\ingroup coap-group
\inmodule libnymea
The CoapReply class contains the data and headers for a request sent with \l{Coap} client.

2
libnymea/coap/coaprequest.cpp
View File

@ -22,7 +22,7 @@
\class CoapRequest
\brief Represents a request to a CoAP server.
\ingroup coap
\ingroup coap-group
\inmodule libnymea
*/

2
libnymea/coap/corelink.cpp
View File

@ -22,7 +22,7 @@
\class CoreLink
\brief Represents a link of a CoRE link format.
\ingroup coap
\ingroup coap-group
\inmodule libnymea
This class represents a Constrained RESTful Environments (CoRE) Link format according to the

2
libnymea/coap/corelinkparser.cpp
View File

@ -22,7 +22,7 @@
\class CoreLinkParser
\brief Provides an easy way to parse a CoRE link list.
\ingroup coap
\ingroup coap-group
\inmodule libnymea
\section2 Example

29
libnymea/devicemanager.cpp
View File

@ -100,10 +100,19 @@
The status of the \l{Device} setup will be emitted asynchronous.
*/
// Signals
/*! \fn void DeviceManager::loaded();
The DeviceManager will emit this signal when all \l{Device}{Devices} are loaded.
*/
/*! \fn void DeviceManager::languageUpdated();
The DeviceManager will emit this signal when all system language has been updated.
*/
/*! \fn void DeviceManager::pluginConfigChanged(const PluginId &id, const ParamList &config);
The DeviceManager will emit this signal when the \a config \l{ParamList}{Params} of the \l{DevicePlugin}{plugin} with the given \a id has changed.
*/
/*! \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}{DeviceError} that occurred.
@ -114,6 +123,11 @@
\l{StateType} and the \a value parameter holds the new value.
*/
/*! \fn void DeviceManager::deviceDisappeared(const DeviceId &deviceId);
This signal is emitted when the automatically created \l{Device} with the given \a deviceId dissapeard. This signal will
create the Devices.DeviceRemoved notification.
*/
/*! \fn void DeviceManager::deviceRemoved(const DeviceId &deviceId);
This signal is emitted when the \l{Device} with the given \a deviceId was removed from the system. This signal will
create the Devices.DeviceRemoved notification.
@ -259,8 +273,8 @@ QList<QJsonObject> DeviceManager::pluginsMetadata()
return pluginList;
}
/*! Register a DevicePlugin class. This can be used to create devices internally from the nymea system without having to create a full plugin.
The DeviceManager takes ownership of the object and will clean it up when exiting. Do not delete the object yourself. */
/*! Register a DevicePlugin class. This can be used to create devices internally from the guh system without having to create a full plugin.
The \a metaData contains the static plugin configurations. The DeviceManager takes ownership of the object \a plugin and will clean it up when exiting. Do not delete the object yourself. */
void DeviceManager::registerStaticPlugin(DevicePlugin *plugin, const QJsonObject &metaData)
{
if (!verifyPluginMetadata(metaData)) {
@ -310,6 +324,10 @@ void DeviceManager::setLocale(const QLocale &locale)
emit languageUpdated();
}
/*! Returns the pointer to the \l{HardwareManager} of the system.
\sa HardwareManager
*/
HardwareManager *DeviceManager::hardwareManager() const
{
return m_hardwareManager;
@ -364,13 +382,13 @@ QList<Vendor> DeviceManager::supportedVendors() const
return m_supportedVendors.values();
}
/*! Returns the list of all supported interfaces */
/*! Returns the list of all supported \l{Interfaces for DeviceClasses}{interfaces}. */
Interfaces DeviceManager::supportedInterfaces() const
{
return m_supportedInterfaces.values();
}
/*! Returns the interface with the given name. If the interface can't be found it will return an invalid interface. */
/*! Returns the interface with the given \a name. If the interface can't be found it will return an invalid interface. */
Interface DeviceManager::findInterface(const QString &name)
{
return m_supportedInterfaces.value(name);
@ -803,6 +821,7 @@ QList<Device *> DeviceManager::findConfiguredDevices(const DeviceClassId &device
return ret;
}
/*! Returns all \l{Device}{Devices} with the given \a interface. See also \l{Interfaces for DeviceClasses}{interfaces}. */
QList<Device *> DeviceManager::findConfiguredDevices(const QString &interface) const
{
QList<Device*> ret;
@ -815,7 +834,7 @@ QList<Device *> DeviceManager::findConfiguredDevices(const QString &interface) c
return ret;
}
/*! Returns all child \l{Device}{Devices} of the given \a device. */
/*! Returns all child \l{Device}{Devices} of the \l{Device} with the given \a id. */
QList<Device *> DeviceManager::findChildDevices(const DeviceId &id) const
{
QList<Device *> ret;

2
libnymea/devicemanager.h
View File

@ -51,6 +51,7 @@ class LIBNYMEA_EXPORT DeviceManager : public QObject
{
Q_OBJECT
Q_ENUMS(DeviceError)
Q_ENUMS(DeviceSetupStatus)
friend class DevicePlugin;
@ -204,5 +205,6 @@ private:
};
Q_DECLARE_METATYPE(DeviceManager::DeviceError)
Q_DECLARE_METATYPE(DeviceManager::DeviceSetupStatus)
#endif // DEVICEMANAGER_H

8
libnymea/hardware/radio433/radio433.cpp
View File

@ -46,6 +46,14 @@
*/
/*! \fn Radio433::~Radio433();
The virtual destructor of the Radio433.
*/
/*! \fn bool Radio433::sendData(int delay, QList<int> rawData, int repetitions);
Returns true if the given \a rawData can be sent to a RF 433MHz device with the given \a delay. The amount of packages to send can be configured with the paramter \a repetitions.
*/
#include "radio433.h"
#include "loggingcategories.h"

39
libnymea/hardwaremanager.cpp
View File

@ -20,14 +20,53 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class HardwareManager
\brief The main entry point when interacting with \l{HardwareResource}{hardware resources}
\inmodule libguh
\sa HardwareResource
*/
/*! \fn HardwareManager::~HardwareManager();
The virtual destructor of the HardwareManager.
*/
/*! \fn Radio433 * HardwareManager::radio433();
Returns the Radio433 \l{HardwareResource}.
*/
/*! \fn PluginTimerManager * HardwareManager::pluginTimerManager();
Returns the PluginTimerManager \l{HardwareResource}.
*/
/*! \fn NetworkAccessManager * HardwareManager::networkManager();
Returns the NetworkAccessManager \l{HardwareResource}.
*/
/*! \fn UpnpDiscovery * HardwareManager::upnpDiscovery();
Returns the UpnpDiscovery \l{HardwareResource}.
*/
/*! \fn QtAvahiServiceBrowser * HardwareManager::avahiBrowser();
Returns the QtAvahiServiceBrowser \l{HardwareResource}.
*/
/*! \fn BluetoothLowEnergyManager * HardwareManager::bluetoothLowEnergyManager();
Returns the BluetoothLowEnergyManager \l{HardwareResource}.
*/
#include "hardwaremanager.h"
/*! Constructs a new HardwareManager with the given \a parent.*/
HardwareManager::HardwareManager(QObject *parent) :
QObject(parent)
{
}
/*! Sets the given \a resource to \a enabled. This allowes to enable/disable individual \l{HardwareResource}{HardwareResources}. */
void HardwareManager::setResourceEnabled(HardwareResource *resource, bool enabled)
{
resource->setEnabled(enabled);

43
libnymea/hardwareresource.cpp
View File

@ -20,10 +20,52 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class HardwareResource
\brief The base class for hardware resources.
\inmodule libguh
\sa HardwareResource
*/
/*! \fn HardwareResource::~HardwareResource();
The virtual destructor of the HardwareResource.
*/
/*! \fn bool HardwareResource::available() const;
Returns true if the hardware resource is available.
\sa availableChanged()
*/
/*! \fn bool HardwareResource::enabled() const;
Returns true if the hardware resource is enabled.
\sa enabledChanged()
*/
/*! \fn bool HardwareResource::setEnabled(bool enabled);
Sets the hardware resource to \a enabled.
\sa enabledChanged()
*/
// Signals
/*! \fn bool HardwareResource::enabledChanged(bool enabled);
This signal will be emited if the hardware resource was \a enabled or disabled.
*/
/*! \fn bool HardwareResource::availableChanged(bool available);
This signal will be emited if the hardware resource \a available changed.
*/
#include "hardwareresource.h"
#include "hardwaremanager.h"
#include "loggingcategories.h"
/*! Constructs a new HardwareResource with the given \a name and \a parent. */
HardwareResource::HardwareResource(const QString &name, QObject *parent) :
NymeaDBusService("/io/guh/nymead/HardwareManager/" + name, parent),
m_name(name)
@ -31,6 +73,7 @@ HardwareResource::HardwareResource(const QString &name, QObject *parent) :
}
/*! Returns the name of this resource. */
QString HardwareResource::name() const
{
return m_name;

2
libnymea/network/avahi/avahiserviceentry.cpp
View File

@ -27,6 +27,8 @@
\ingroup types
\inmodule libnymea
You can find an example \l{QtAvahiServiceBrowser}{here}.
*/
#include "avahiserviceentry.h"

63
libnymea/network/avahi/qtavahiservicebrowser.cpp
View File

@ -26,8 +26,71 @@
\ingroup hardware
\inmodule libnymea
The QtAvahiServiceBrowser allows to discover the avahi network and get services.
\chapter Example
In order to search for available avahi services in the current network you use this hardware resource like this:
\tt devicepluginexample.h
\code
#include "network/avahi/avahiserviceentry.h"
class DevicePluginExample : public DevicePlugin
{
...
public:
void init() override;
private slots:
void onServiceEntryAdded(const AvahiServiceEntry &serviceEntry);
void onServiceEntryRemoved(const AvahiServiceEntry &serviceEntry);
...
};
\endcode
\tt devicepluginexample.cpp
\code
void DevicePluginExample::init() {
connect(hardwareManager()->avahiBrowser(), &QtAvahiServiceBrowser::serviceEntryAdded, this, &DevicePluginExample::onServiceEntryAdded);
connect(hardwareManager()->avahiBrowser(), &QtAvahiServiceBrowser::serviceEntryRemoved, this, &DevicePluginExample::onServiceEntryRemoved);
}
void DevicePluginExample::onServiceEntryAdded(const AvahiServiceEntry &serviceEntry) {
qCDebug(dcExample()) << "New service added to network:" << serviceEntry;
...
}
void DevicePluginExample::onServiceEntryRemoved(const AvahiServiceEntry &serviceEntry) {
qCDebug(dcExample()) << "Service removed from network:" << serviceEntry;
...
}
\endcode
\sa AvahiServiceEntry
*/
/*! \fn QtAvahiServiceBrowser::~QtAvahiServiceBrowser();
Destroys this QtAvahiServiceBrowser;
*/
/*! \fn QList<AvahiServiceEntry> QtAvahiServiceBrowser::serviceEntries() const;
Returns the list of available service entries in the network of this browser.
*/
// Signals
/*! \fn void QtAvahiServiceBrowser::serviceEntryAdded(const AvahiServiceEntry &entry);
This signal will be emitted when a new \a entry was added to the current entry list.
*/

142
libnymea/network/networkaccessmanager.cpp
View File

@ -21,17 +21,147 @@
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class NetworkAccessManager
\brief Allows to send network requests and receive replies.
\class NetworkAccessManager
\brief Allows to send network requests and receive replies.
\ingroup hardware
\inmodule libnymea
\ingroup hardware
\inmodule libnymea
The network manager class is a reimplementation of the \l{http://doc-snapshot.qt-project.org/qt5-5.4/qnetworkaccessmanager.html}{QNetworkAccessManager}
and allows plugins to send network requests and receive replies.
The network manager class is a reimplementation of the \l{http://doc.qt.io/qt-5/qnetworkaccessmanager.html}{QNetworkAccessManager}
and allows plugins to send network requests and receive replies.
\chapter Example
In order to make a GET request in your plugin, you can take a look at following example:
\tt devicepluginexample.h
\code
#include "network/networkaccessmanager.h"
class DevicePluginExample : public DevicePlugin
{
...
private:
void getServerData();
private slots:
void onGetRequestFinished();
...
};
\endcode
\tt devicepluginexample.cpp
\code
void DevicePluginExample::getServerData() {
QNetworkReply *reply = hardwareManager()->networkManager()->get(QNetworkRequest(QUrl("http://example.com")));
connect(reply, &QNetworkReply::finished, this, &DevicePluginExample::onGetRequestFinished);
}
void DevicePluginExample::onGetRequestFinished() {
QNetworkReply *reply = static_cast<QNetworkReply *>(sender());
int httpStatus = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
if (httpStatus != 200 || reply->error() != QNetworkReply::NoError) {
qCWarning(dcExample()) << "Get data reply error: " << httpStatus << reply->errorString();
reply->deleteLater();
return;
}
QByteArray data = reply->readAll();
reply->deleteLater();
...
}
\endcode
\sa HardwareResource, HardwareManager::networkManager()
*/
/*! \fn NetworkAccessManager::~NetworkAccessManager();
Destroys this NetworkAccessManager.
*/
/*! \fn QNetworkReply *NetworkAccessManager::get(const QNetworkRequest &request);
Posts a \a request to obtain the contents of the target request and returns a new QNetworkReply object opened for reading which emits the readyRead() signal whenever new data arrives.
The contents as well as associated headers will be downloaded.
\sa post(), put(), deleteResource(), sendCustomRequest()
*/
/*! \fn QNetworkReply *NetworkAccessManager::deleteResource(const QNetworkRequest &request);
Sends a \a request to delete the resource identified by the URL of request.
\note This feature is currently available for HTTP only, performing an HTTP DELETE request.
\sa post(), put(), deleteResource(), sendCustomRequest()
*/
/*! \fn QNetworkReply *NetworkAccessManager::head(const QNetworkRequest &request);
Posts a \a request to obtain the network headers for request and returns a new QNetworkReply object which will contain such headers.
The function is named after the HTTP request associated (HEAD).
\sa post(), put(), deleteResource(), sendCustomRequest()
*/
/*! \fn QNetworkReply *NetworkAccessManager::post(const QNetworkRequest &request, QIODevice *data);
Sends an HTTP POST \a request to the destination specified by request and returns a new QNetworkReply object opened for reading that will contain the reply sent by the server. The contents of the \a data device will be uploaded to the server.
Data must be open for reading and must remain valid until the finished() signal is emitted for this reply.
\note Sending a POST request on protocols other than HTTP and HTTPS is undefined and will probably fail.
\sa get(), put(), deleteResource(), sendCustomRequest()
*/
/*! \fn QNetworkReply *NetworkAccessManager::post(const QNetworkRequest &request, const QByteArray &data);
This is an overloaded function.
Sends the contents of the \a data byte array to the destination specified by \a request.
*/
/*! \fn QNetworkReply *NetworkAccessManager::post(const QNetworkRequest &request, QHttpMultiPart *multiPart);
This is an overloaded function.
Sends the contents of the \a multiPart message to the destination specified by \a request.
This can be used for sending MIME multipart messages over HTTP.
*/
/*! \fn QNetworkReply *NetworkAccessManager::put(const QNetworkRequest &request, QIODevice *data);
Uploads the contents of \a data to the destination \a request and returnes a new QNetworkReply object that will be open for reply.
data must be opened for reading when this function is called and must remain valid until the finished() signal is emitted for this reply.
Whether anything will be available for reading from the returned object is protocol dependent. For HTTP, the server may send a small HTML page indicating the upload was successful (or not).
Other protocols will probably have content in their replies.
\note For HTTP, this request will send a PUT request, which most servers do not allow. Form upload mechanisms, including that of uploading files through HTML forms, use the POST mechanism.
\sa get(), post(), deleteResource(), sendCustomRequest()
*/
/*! \fn QNetworkReply *NetworkAccessManager::put(const QNetworkRequest &request, const QByteArray &data);
This is an overloaded function.
Sends the contents of the \a data byte array to the destination specified by \a request.
*/
/*! \fn QNetworkReply *NetworkAccessManager::put(const QNetworkRequest &request, QHttpMultiPart *multiPart);
This is an overloaded function.
Sends the contents of the \a multiPart message to the destination specified by \a request.
This can be used for sending MIME multipart messages over HTTP.
*/
/*! \fn QNetworkReply *NetworkAccessManager::sendCustomRequest(const QNetworkRequest &request, const QByteArray &verb, QIODevice *data = nullptr);
Sends a custom \a request to the server identified by the URL of request.
It is the user's responsibility to send a \a verb to the server that is valid according to the HTTP specification.
This method provides means to send verbs other than the common ones provided via get() or post() etc., for instance sending an HTTP OPTIONS command.
If \a data is not empty, the contents of the data device will be uploaded to the server; in that case, data must be open for reading and must remain valid until the finished() signal is emitted for this reply.
\sa get(), post(), put(), deleteResource()
*/
#include "networkaccessmanager.h"
#include "loggingcategories.h"

8
libnymea/network/upnp/upnpdevicedescriptor.cpp
View File

@ -27,8 +27,14 @@
\ingroup types
\inmodule libnymea
The upnp device descriptor holds the discovered information of a UPnP device. These information are
the result of a \l{UpnpDiscovery::discoverDevices()}{discoverDevices()} request and can accessed in from the
\l{UpnpDiscoveryReply::deviceDescriptors()}{deviceDescriptors()} once the UpnpDiscoveryReply
is \l{UpnpDiscoveryReply::finished()}{finished}.
\sa UpnpDevice
You can find an example \l{UpnpDiscovery}{here}.
\sa UpnpDevice, UpnpDiscovery, UpnpDiscoveryReply
*/
#include "upnpdevicedescriptor.h"

89
libnymea/network/upnp/upnpdiscovery.cpp
View File

@ -21,25 +21,88 @@
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class UpnpDiscovery
\brief Allows to detect UPnP devices in the network.
\class UpnpDiscovery
\brief Allows to discover UPnP devices in the network.
\ingroup hardware
\inmodule libnymea
\ingroup hardware
\inmodule libnymea
This resource allows plugins to discover UPnP devices in the network and receive notification messages. The resource
will bind a UDP socket to the multicast 239.255.255.250 on port 1900.
This resource allows plugins to discover UPnP devices in the network and receive notification messages. The resource
will bind a UDP socket to the multicast 239.255.255.250 on port 1900.
The communication was implementet using following documentation: \l{http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf}
The communication was implementet using following documentation: \l{http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf}
\sa UpnpDevice, UpnpDeviceDescriptor
\chapter Example
In order to perform an UPnP discovery in your plugin, you can take a look at following example:
\tt devicepluginexample.h
\code
class DevicePluginExample : public DevicePlugin
{
...
private:
void discoverUpnpDevices();
private slots:
void onUpnpDiscoveryFinished();
...
};
\endcode
\tt devicepluginexample.cpp
\code
#include "network/upnp/upnpdiscovery.h"
#include "network/upnp/upnpdiscoveryreply.h"
void DevicePluginExample::discoverUpnpDevices() {
UpnpDiscoveryReply *reply = hardwareManager()->upnpDiscovery()->discoverDevices();
connect(reply, &UpnpDiscoveryReply::finished, this, &DevicePluginExample::onUpnpDiscoveryFinished);
}
void DevicePluginExample::onUpnpDiscoveryFinished() {
UpnpDiscoveryReply *reply = static_cast<UpnpDiscoveryReply *>(sender());
if (reply->error() != UpnpDiscoveryReply::UpnpDiscoveryReplyErrorNoError) {
qCWarning(dcExample()) << "UPnP discovery error" << reply->error();
}
// Note: you have to delete the reply using deleteLater()
reply->deleteLater();
foreach (const UpnpDeviceDescriptor &upnpDevice, reply->deviceDescriptors()) {
qCDebug(dcExample()) << upnpDevice.friendlyName() << upnpDevice.hostAddress().toString();
}
...
}
\endcode
\sa UpnpDevice, UpnpDeviceDescriptor
*/
/*!
\fn UpnpDiscovery::upnpNotify(const QByteArray &notifyMessage)
This signal will be emitted when a UPnP NOTIFY message \a notifyMessage will be recognized.
\sa DevicePlugin::upnpNotifyReceived()
*/
/*! \fn UpnpDiscovery::~UpnpDiscovery();
Destroys this UpnpDiscovery.
*/
/*! \fn UpnpDiscoveryReply *UpnpDiscovery::discoverDevices(const QString &searchTarget = "ssdp:all", const QString &userAgent = QString(), const int &timeout = 5000);
Start a UPnP discovery request for devices listening on the given \a searchTarget and \a userAgent. The discovery duration can be specified with \a timeout parameter.
*/
/*! \fn void UpnpDiscovery::sendToMulticast(const QByteArray &data);
Sends \a data to the UpnP multicast group. This method can be used in order to send raw data to the group.
*/
/*! \fn UpnpDiscovery::upnpNotify(const QByteArray &notifyMessage)
This signal will be emitted when a UPnP NOTIFY message \a notifyMessage will be recognized.
*/
#include "upnpdiscovery.h"

67
libnymea/network/upnp/upnpdiscoveryreply.cpp
View File

@ -20,8 +20,75 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class UpnpDiscoveryReply
\brief Allows to handle UPnP discovery request in the network.
\ingroup hardware
\inmodule libguh
\sa UpnpDevice, UpnpDiscovery
*/
/*! \enum UpnpDiscoveryReply::UpnpDiscoveryReplyError
\value UpnpDiscoveryReplyErrorNoError
The reply finished successfully.
\value UpnpDiscoveryReplyErrorNotAvailable
The UpnpDiscovery HardwareResource is not available.
\value UpnpDiscoveryReplyErrorNotEnabled
The UpnpDiscovery HardwareResource is not enabled.
\value UpnpDiscoveryReplyErrorResourceBusy
The UpnpDiscovery HardwareResource is currently busy.
*/
// Public
/*! \fn UpnpDiscoveryReply::~UpnpDiscoveryReply();
The virtual destructor of the UpnpDiscoveryReply.
*/
/*! \fn int UpnpDiscoveryReply::searchTarget() const;
Returns the search target which was used for this UpnpDiscovery request.
\sa UpnpDiscovery::discoverDevices()
*/
/*! \fn int UpnpDiscoveryReply::userAgent() const;
Returns the user agent which was used for this UpnpDiscovery request.
\sa UpnpDiscovery::discoverDevices()
*/
/*! \fn UpnpDiscoveryReplyError UpnpDiscoveryReply::error() const;
Returns the current error of this UpnpDiscoveryReply.
\sa UpnpDiscoveryReplyError
*/
/*! \fn bool UpnpDiscoveryReply::isFinished() const;
Returns true if this UpnpDiscoveryReply is finished.
\sa UpnpDiscoveryReplyError
*/
/*! \fn QList<UpnpDeviceDescriptor> UpnpDiscoveryReply::deviceDescriptors() const;
Returns the list of found \l{UpnpDeviceDescriptor}{UpnpDeviceDescriptors}. This list will be empty if an error occured.
\sa finished()
*/
// Signals
/*! \fn void UpnpDiscoveryReply::finished();
This signal will be emitted once the UpnpDiscoveryReply is finished.
*/
/*! \fn void UpnpDiscoveryReply::errorOccured(const UpnpDiscoveryReplyError &error);
This signal will be emitted once an UpnpDiscoveryReply \a error occured.
*/
#include "upnpdiscoveryreply.h"
/*! Construct a new UpnpDiscoveryReply with the given \a parent. */
UpnpDiscoveryReply::UpnpDiscoveryReply(QObject *parent) :
QObject(parent)
{

3
libnymea/nymeasettings.cpp
View File

@ -48,6 +48,9 @@
\value SettingsRoleGlobal
This role will create the \b{nymead.conf} file and is used to store the global settings of the nymea system. This settings
file is read only.
\value SettingsRoleDeviceStates
This role will create the \b{device-states.conf} file and is used to store the configured \l{Device} \l{State}{States}.
*/
#include "nymeasettings.h"

5
libnymea/plugin/deviceplugin.cpp
View File

@ -28,9 +28,9 @@
\ingroup devices
\inmodule libnymea
*/
/*!
\fn void DevicePlugin::devicesDiscovered(const DeviceClassId &deviceClassId, const QList<DeviceDescriptor> &devices);
This signal is emitted when the discovery of a \a deviceClassId of this DevicePlugin is finished. The \a devices parameter describes the
@ -71,7 +71,7 @@
/*!
\fn void DevicePlugin::autoDeviceDisappeared(const DeviceId &id)
Emit this signal when a device which was created by \l{DevicePlugin::autoDevicesAppeared} has been removed from the system.
Emit this signal when a device with the given \a id and which was created by \l{DevicePlugin::autoDevicesAppeared} has been removed from the system.
Be careful with this, as this will completely remove the device from the system and with it all the associated rules. Only
emit this if you are sure that a device will never come back. This signal should not be emitted for child auto devices
when the parent who created them is removed. The system will automatically remove all child devices in such a case.
@ -462,6 +462,7 @@ QList<Device *> DevicePlugin::myDevices() const
return ret;
}
/*! Returns the pointer to the main \l{HardwareManager} of this server. */
HardwareManager *DevicePlugin::hardwareManager() const
{
return m_deviceManager->hardwareManager();

164
libnymea/plugintimer.cpp
View File

@ -20,15 +20,179 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class PluginTimer
\brief The plugin timer class for plugins.
\ingroup hardware
\inmodule libguh
The plugin timer allowes to trigger repeating actions in a device plugin. This timer does not represent a precise timer
should be used for not time critical things. The PluginTimerManager will schedule the requested timer as needed and
trigger the timeout() method.
\chapter Example
In order to do something repeatedly in a \l{DevicePlugin} you can register a new PluginTimer like this:
\tt devicepluginexample.h
\code
#include "plugintimer.h"
class DevicePluginExample : public DevicePlugin
{
...
public:
void init() override;
private:
PluginTimer *m_pluginTimer = nullptr;
private slots:
void onPluginTimerTimeout();
...
};
\endcode
\tt devicepluginexample.cpp
\code
void DevicePluginExample::init() {
m_pluginTimer = hardwareManager()->pluginTimerManager()->registerTimer(10);
connect(m_pluginTimer, &PluginTimer::timeout, this, &DevicePluginExample::onPluginTimerTimeout);
}
DevicePluginExample::~DevicePluginExample()
{
hardwareManager()->pluginTimerManager()->unregisterTimer(m_pluginTimer);
}
\endcode
\sa PluginTimerManager
*/
// Public
/*! \fn PluginTimer::~PluginTimer();
The virtual destructor of the PluginTimer. You should always use the PluginTimerManager for destroying a PluginTimer object.
*/
/*! \fn int PluginTimer::interval() const;
This property holds the timeout interval in seconds.
*/
/*! \fn int PluginTimer::currentTick() const;
Returns the current timer tick of this PluginTimer in seconds.
*/
/*! \fn bool PluginTimer::running() const;
Returns true, if this PluginTimer is currently running.
\sa start(), stop(), pause(), resume(), reset()
*/
// Signals
/*! \fn void PluginTimer::timeout();
This signal will be emited if the timer timeouted.
*/
/*! \fn void PluginTimer::currentTickChanged(const int &currentTick);
This signal will be emited whenever the \a currentTick of this PluginTimer changed.
\sa currentTick()
*/
/*! \fn void PluginTimer::runningChanged(const bool &running);
This signal will be emited whenever the \a running status of this PluginTimer changed.
\sa running()
*/
/*! \fn void PluginTimer::pausedChanged(const bool &paused);
This signal will be emited whenever the \a paused status of this PluginTimer changed.
\sa running()
*/
// Public slots
/*! \fn void PluginTimer::reset();
This method resets the timer to 0. This method does not change the current running state or the configured interval.
*/
/*! \fn void PluginTimer::start();
Starts the timer.
\sa running(), runningChanged()
*/
/*! \fn void PluginTimer::stop();
Stops the timer.
\sa running(), runningChanged()
*/
/*! \fn void PluginTimer::pause();
Pauses the timer.
\sa running()
*/
/*! \fn void PluginTimer::resume();
Resumes the timer. If the timer was not on paused, this method has no effect.
\sa pause()
*/
/*!
\class PluginTimerManager
\brief The plugin timer manager for guh.
\ingroup hardware
\inmodule libguh
The plugin timer manager allows to register and unregister generic timers for device plugins. In order to save
resources the PluginTimerManager is responsible to schedule the timers appropriate and stop them if the HardwareResource
gets disabled.
You can find an example \l{PluginTimer}{here}.
\sa PluginTimer, HardwareResource
*/
/*! \fn PluginTimerManager::~PluginTimerManager();
The virtual destructor of the PluginTimerManager.
*/
/*! \fn PluginTimer *PluginTimerManager::registerTimer(int seconds = 60);
Registers a new PluginTimer with an interval of the given \a seconds parameter. Returns a new PluginTimer object.
\sa unregisterTimer()
*/
/*! \fn void unregisterTimer(PluginTimer *timer = nullptr);
Unregisters the given \a timer. The PluginTimerManager will delete the object once the unregister process is complete.
\sa registerTimer()
*/
#include "plugintimer.h"
#include "loggingcategories.h"
/*! Constructs a \l{PluginTimerManager} with the given \a parent. */
PluginTimerManager::PluginTimerManager(QObject *parent) :
HardwareResource("PluginTimerManager", parent)
{
}
/*! Constructs a PluginTimer with the given \a parent. */
PluginTimer::PluginTimer(QObject *parent) :
QObject(parent)
{

6
libnymea/types/deviceclass.cpp
View File

@ -449,11 +449,17 @@ void DeviceClass::setPairingInfo(const QString &pairingInfo)
m_pairingInfo = pairingInfo;
}
/*! Returns the \l{Interfaces for DeviceClasses}{interfaces} of this \l{DeviceClass}.*/
QStringList DeviceClass::interfaces() const
{
return m_interfaces;
}
/*! Set the \a interfaces of this \l{DeviceClass}.
\note You can find information about interfaces \l{Interfaces for DeviceClasses}{here}.
*/
void DeviceClass::setInterfaces(const QStringList &interfaces)
{
m_interfaces = interfaces;

10
libnymea/types/eventdescriptor.cpp
View File

@ -39,6 +39,14 @@
\sa Event, EventType, nymeaserver::Rule
*/
/*! \enum EventDescriptor::Type
\value TypeDevice
The EventDescriptor describes a device Event.
\value TypeInterface
The EventDescriptor describes an interface based Event.
*/
#include "eventdescriptor.h"
/*! Constructs an EventDescriptor describing an \l{Event} with the given \a eventTypeId, \a deviceId and the given \a paramDescriptors. */
@ -49,6 +57,7 @@ EventDescriptor::EventDescriptor(const EventTypeId &eventTypeId, const DeviceId
{
}
/*! Constructs an EventDescriptor describing an \l{Event} with the given \a interface, \a interfaceEvent and the given \a paramDescriptors. */
EventDescriptor::EventDescriptor(const QString &interface, const QString &interfaceEvent, const QList<ParamDescriptor> &paramDescriptors):
m_interface(interface),
m_interfaceEvent(interfaceEvent),
@ -57,6 +66,7 @@ EventDescriptor::EventDescriptor(const QString &interface, const QString &interf
}
/*! Returns true \l{EventDescriptor::Type}{Type} of this descriptor. */
EventDescriptor::Type EventDescriptor::type() const
{
return (!m_deviceId.isNull() && !m_eventTypeId.isNull()) ? TypeDevice : TypeInterface;

2
libnymea/types/eventtype.cpp
View File

@ -67,7 +67,7 @@ QString EventType::displayName() const
return m_displayName;
}
/*! Set the displayName for this EventType to \a name, e.g. "Temperature changed". */
/*! Set the displayName for this EventType to \a displayName, e.g. "Temperature changed". */
void EventType::setDisplayName(const QString &displayName)
{
m_displayName = displayName;

9
libnymea/types/paramtype.cpp
View File

@ -31,6 +31,12 @@
\sa Device, Param, ParamDescriptor
*/
/*! \fn ParamType::ParamType();
Constructs a new ParamType which is initially not valid.
\sa isValid()
*/
#include "paramtype.h"
@ -72,7 +78,7 @@ QString ParamType::displayName() const
return m_displayName;
}
/*! Sets the displayName of this ParamType, to be shown to the user, translated. */
/*! Sets the \a displayName of this ParamType, to be shown to the user, translated. */
void ParamType::setDisplayName(const QString &displayName)
{
m_displayName = displayName;
@ -199,6 +205,7 @@ void ParamType::setReadOnly(const bool &readOnly)
m_readOnly = readOnly;
}
/*! Returns true if this ParamType is valid. A ParamType is valid, if the the id, the name and the data type is set. */
bool ParamType::isValid() const
{
return !m_id.isNull() && !m_name.isEmpty() && m_type != QVariant::Invalid;

11
libnymea/types/ruleaction.cpp
View File

@ -35,9 +35,18 @@
\sa nymeaserver::Rule, RuleActionParam,
*/
/*! \enum RuleAction::Type
\value TypeDevice
The RuleAction describes a device Action.
\value TypeInterface
The RuleAction describes an interface based Action.
*/
#include "ruleaction.h"
/*! Constructs a RuleAction with the given by \a actionTypeId and \a deviceId. */
/*! Constructs a RuleAction with the given by \a actionTypeId, \a deviceId and \a params. */
RuleAction::RuleAction(const ActionTypeId &actionTypeId, const DeviceId &deviceId, const RuleActionParamList &params):
m_id(ActionId::createActionId()),
m_actionTypeId(actionTypeId),

1
libnymea/types/ruleactionparam.cpp
View File

@ -74,6 +74,7 @@ ParamTypeId RuleActionParam::paramTypeId() const
return m_paramTypeId;
}
/*! Returns the name of this RuleActionParam. */
QString RuleActionParam::paramName() const
{
return m_paramName;

10
libnymea/types/statetype.cpp
View File

@ -36,7 +36,7 @@
/*! 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. */
* hardcode it into the plugin json file. */
StateType::StateType(const StateTypeId &id):
m_id(id)
{
@ -49,13 +49,13 @@ StateTypeId StateType::id() const
return m_id;
}
/*! Returns the name of the StateType. This is used internally, e.g. to match interfaces. */
/*! Returns the name of the StateType. This is used internally, e.g. to match \l{Interfaces for DeviceClasses}{interfaces}. */
QString StateType::name() const
{
return m_name;
}
/*! Set the name of the StateType to \a name. This is used internally, e.g. to match interfaces. */
/*! Set the name of the StateType to \a name. This is used internally, e.g. to match \l{Interfaces for DeviceClasses}{interfaces}. */
void StateType::setName(const QString &name)
{
m_name = name;
@ -67,7 +67,7 @@ QString StateType::displayName() const
return m_displayName;
}
/*! Set the displayName of the StateType to \a name. This is visible to the user (e.g. "Color temperature"). */
/*! Set the displayName of the StateType to \a displayName. This is visible to the user (e.g. "Color temperature"). */
void StateType::setDisplayName(const QString &displayName)
{
m_displayName = displayName;
@ -190,7 +190,7 @@ bool StateType::cached() const
return m_cached;
}
/*! Sets whether this StateType should be cached or not. */
/*! Sets whether this StateType should be \a cached or not. If a state value gets cached, the state will be initialized with the cached value on start.*/
void StateType::setCached(bool cached)
{
m_cached = cached;

2
libnymea/types/vendor.cpp
View File

@ -69,7 +69,7 @@ QString Vendor::displayName() const
return m_displayName;
}
/*! Sets the name of this Vendor, to be shown to the user, translated. */
/*! Sets the \a displayName of this Vendor, to be shown to the user, translated. */
void Vendor::setDisplayName(const QString &displayName)
{
m_displayName = displayName;

1
nymea.pro
View File

@ -12,6 +12,7 @@ tests.depends = libnymea libnymea-core
doc.depends = FORCE
# Note: some how extraimages in qdocconf did not the trick
doc.commands += cd $$top_srcdir/libnymea/interfaces; ./generatedoc.sh;
doc.commands += cd $$top_srcdir/doc; ./generate-api-qdoc.py;
doc.commands += cd $$top_srcdir/doc; qdoc config.qdocconf; cp -r images/* html/images/; \
cp -r favicons/* html/; cp -r $$top_srcdir/doc/html $$top_builddir/