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

add typeutils documentation

Browse Source
This commit is contained in:
Simon Stürz 2015-08-08 18:10:32 +02:00 committed by Michael Zanetti
parent 3087ba918b
commit 610fc77ded
46 changed files with 613 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/allmodules.qdoc
View File

@ -1,10 +1,10 @@
/*!
\page allmodules.html
\title All Modules
\title All guh Modules
\table 80%
\row \li \l{libguh} \li Common data types and plugin interfaces
\row \li \l{guhserver} \li The guh server daemon implementation
\row \li \l{libguh} \li Common data types and plugin interfaces
\row \li \l{Plugins} \li The device plugins of the guh server
\endtable
*/

19
doc/config.qdocconf
View File

@ -3,9 +3,27 @@ include(html-template.qdocconf)
project = guh
description = Gear up your Home!
dita.metadata.default.author = Simon Stürz
dita.metadata.default.permissions = all
dita.metadata.default.publisher = guh
dita.metadata.default.copyryear = 2015
dita.metadata.default.copyrholder = Simon Stürz
dita.metadata.default.audience = programmer
defines = DECLARE_TYPE_ID
outputdir = html
outputformats = HTML
language = Cpp
naturallanguage = en_US
outputencoding = UTF-8
sourceencoding = UTF-8
syntaxhighlighting = true
versionsym = GUH_VERSION_STRING
headerdirs = ..
headers.fileextensions = "*.h"
@ -16,3 +34,4 @@ exampledirs = ..
sourcedirs = ..
sources.fileextensions = "*.cpp *.qdoc"

8
doc/getting-started-plugins.qdoc
View File

@ -38,7 +38,7 @@
The \b TARGET parameter definens the name of the resulting plugin lib file and should should have following name structure:
\e{guh_deviceplugin\b<pluginName>}
\tt {guh_deviceplugin\b<pluginName>}
In this example the pluginname is \e minimal, which means the lib file name will be \e guh_devicepluginminimal.so. You can check the name of the plugin in the "Project Messages" (\tt{alt + 6} in Qt Creator).
@ -83,7 +83,7 @@
\section2 devicepluginminimal.json
The properties of a plugin will be definend with in the \tt JSON file containing all needed information for guh to load it. The name convention fot the json file is:
\e{deviceplugin\b{<pluginName>}.json}
\tt {deviceplugin\b{<pluginName>}.json}
This file must have a clear, definend structure and looking like this:
@ -124,7 +124,7 @@
\section2 devicepluginminimal.h
The main header file of the plugin. The naming convention is:
\e{deviceplugin\b<pluginName>.h}
\tt {deviceplugin\b<pluginName>.h}
In this file you can find the main class of the plugin: \e DevicePluginMinimal. As you can see the \e DevicePluginMinimal inherits from the class \l{DevicePlugin}. You can check out the \l{DevicePlugin} class description to find how a \l{DevicePlugin} looks like.
@ -157,7 +157,7 @@
\section2 devicepluginminimal.cpp
The implementation of the \l{DevicePlugin}. The naming convention is:
\e{deviceplugin\b<pluginName>.cpp}
\tt {deviceplugin\b<pluginName>.cpp}
\code
#include "devicepluginminimal.h"

16
doc/guh.qdoc
View File

@ -2,19 +2,21 @@
\page index.html
\section1 Overview
The guh backend service consists of three main modules:
The guh daemon consists of three main modules:
\list
\li \l{guhserver}{The guh server}
\list
\li \l{guhserver}{The guh server namespace}
\li \l{Server classes}{The server classes}
\li \l{Rules}{The Rule Engine}
\endlist
\li \l{libguh}{The guh library}
\list
\li \l{Types}{Types used in the guh system}
\li \l{Types of libguh}{Types used in the guh system}
\li \l{Device Plugins}{The Device Plugin API}
\li \l{Hardware Resources}{Hardware resources available for plugins}
\li \l{Type Utils}{Global types in guh}
\endlist
\li \l{Plugins}{The guh plugins}
\list
@ -25,22 +27,26 @@
\endlist
\section1 API's
The guh daemon provides two API's:
\list
\li \l{JSON-RPC API}
\li \l{https://github.com/guh/guh/wiki/REST-Api-documentation}{REST API}
\li \l{JSON-RPC API}{JSON-RPC}
\li \l{https://github.com/guh/guh/wiki/REST-Api-documentation}{REST}
\endlist
\section1 How To's
Here you can find some tutorials for developing and working with the guh:
\list
\li \l{How to write a plugin}
\li \l{Getting started}
\li \l{The plugin JSON File}
\li \l{Tutorial 1}{Tutorial 1 - The "Minimal" plugin}
\li \l{Tutorial 2}{Tutorial 2 - The "NetworkInfo" plugin}
\endlist
\section1 Quicklinks
Overview of all classes and modules in guh
\list
\li \l{All guh Classes}
\li \l{All Modules}
\li \l{All guh Modules}
\endlist
*/

7
doc/guhcore.qdoc
View File

@ -1,7 +0,0 @@
/*!
\page guhcore-index.html
\title guh Core
\annotatedlist server
*/

6
doc/guhserver.qdoc
View File

@ -1,9 +1,7 @@
/*!
\namespace guhserver
\brief The namespace for the guh server.
\inmodule server
\inmodule core
This namespace represents the whole guh server. This prevents duplicated classnames in plugin and core.
This namespace represents the whole guh server. This prevents duplicated class names in plugin and core.
*/

5
doc/html-template.qdocconf
View File

@ -8,8 +8,9 @@ HTML.postheader = \
" <div class=\"breadcrumb toolblock\">\n" \
" <ul>\n" \
" <li class=\"first\"><a href=\"index.html\">Home</a></li>\n" \
" <!-- Breadcrumbs go here -->\n"
" <li class=\"third\"><a href=\"guhserver.html\">Server</a></li>\n" \
" <li class=\"second\"><a href=\"libguh-module.html\">Lib</a></li>\n" \
" <li class=\"second\"><a href=\"plugins.html\">Plugins</a></li>\n"
HTML.postpostheader = \
" </ul>\n" \
" </div>\n" \

9
doc/libguh.qdoc
View File

@ -2,14 +2,15 @@
\module libguh
\title The guh library
\section1 Types
\annotatedlist types
\chapter Types of libguh
\annotatedlist guh-types
\section1 Device Plugins
\chapter Device Plugins
\annotatedlist devices
\section1 Hardware Resources
\chapter Hardware Resources
\annotatedlist hardware
*/

163
doc/plugin-json.qdoc
View File

@ -3,22 +3,31 @@
\title The plugin JSON File
\brief Description of the plugin JSON file structure.
Each \l{DevicePlugin}{Plugin} in guh will be definend in the corresponding JSON file. You can find information how to read JSON \l{http://json.org/}{here}. This file will be loaded from the \l{DeviceManager} to define the plugin and the corresponding DeviceClasses internal. The \tt guh-generateplugininfo precompiler will parse this file and generates a \e plugininfo.h and a \e extern-plugininfo.h file containing the definitions of:
Each \l{DevicePlugin}{Plugin} in guh will be defined in the corresponding JSON file. You can find information how to read JSON \l{http://json.org/}{here}. This file will be loaded from the \l{DeviceManager} to define the plugin and the corresponding DeviceClasses internal.
\section1 The \e guh-generateplugininfo precompiler
The \tt {\b guh-generateplugininfo} precompiler will parse this file and generates a \tt plugininfo.h and a \tt extern-plugininfo.h file containing the definitions of:
\list
\li \b PluginId: <\e idName>PluginId -> the definend UUID for the \l{DevicePlugin}.
\li \b VendorId's: <\e idName>VendorId -> the definend UUID for the corresponding \l{Vendor}.
\li \b DeviceClassId's: <\e idName>DeviceClassId -> the definend UUID for the corresponding \l{DeviceClass}.
\li \b ActionTypeId's: <\e idName>ActionTypeId -> the definend UUID for the corresponding \l{ActionType}.
\li \b StateTypeId's: <\e idName>StateTypeId -> the definend UUID for the corresponding \l{StateType}.
\li \b EventTypeId's: <\e idName>EventTypeId -> the definend UUID for the corresponding \l{EventType}.
\li \b {Logging Category}
\li \l{PluginId}: <\e idName>PluginId -> the defined UUID for the \l{DevicePlugin}.
\li \l{VendorId}: <\e idName>VendorId -> the defined UUID for the corresponding \l{Vendor}.
\li \l{DeviceClassId}: <\e idName>DeviceClassId -> the definend UUID for the corresponding \l{DeviceClass}.
\li \l{ActionTypeId}: <\e idName>ActionTypeId -> the defined UUID for the corresponding \l{ActionType}.
\li \l{StateTypeId}: <\e idName>StateTypeId -> the defidefinednend UUID for the corresponding \l{StateType}.
\li \l{EventTypeId}: <\e idName>EventTypeId -> the defined UUID for the corresponding \l{EventType}.
\li Logging Category
\endlist
The \e plugininfo.h has to be included in the main plugin \tt cpp file (deviceplugin<\e pluginName>.cpp). The \e extern-plugininfo.h can be included in other classes/files of the plugin to get the extern definitions of the ID's and the logging category.
The \tt plugininfo.h has to be included in the main plugin \tt cpp file (\tt{deviceplugin<\b pluginName>.cpp}). The \tt extern-plugininfo.h can be included in other classes/files of the plugin to get the extern definitions of the ID's and the logging category.
The name convention fot the json file is:
\section1 Basic structure
The name convention fot the plugin json file is:
\e{deviceplugin\b{<pluginName>}.json}
\tt{deviceplugin\b{<pluginName>}.json}
The basic structure of a plugin looks like this:
@ -41,7 +50,7 @@
}
\endcode
\warning For each new Object which has an \e uuid value, you need to generate a new uuid. The easyest way to do this is using the comman \tt uuidgen:
\warning For each new Object which has an \e "uuid" value, you need to generate a new UUID. The easyest way to do this is using the command \tt uuidgen:
\code
$ sudo apt-get install uuid-runtime
@ -53,7 +62,11 @@
\endcode
\section1 The Plugin definition
\section1 Writing the plugin JSON file
\section2 The Plugin definition
The parameters of the first Object (\e name, \e idName, \e id and \e vendors) describe the properties of the plugin it self.
\code
@ -72,21 +85,21 @@
\note All parameters \underline{must} be definend!
\list
\li - \e name: The visible name of the plugin \unicode{0x2192} \l{DevicePlugin::pluginName()}
\li - \e idName: This parameter will be used to define the PluginId variable named <idName>PluginId in the plugininfo.h, so it can be used in the code. This parameter also defines the logging categorie for this plugin. The loging category will always definend as \tt dc<idName> and can be used as follows ("idName":"Example"):
\li - \underline{\e name:} The visible name of the plugin \unicode{0x2192} \l{DevicePlugin::pluginName()}
\li - \underline{\e idName:} This parameter will be used to define the PluginId variable named <idName>PluginId in the plugininfo.h, so it can be used in the code. This parameter also defines the logging categorie for this plugin. The loging category will always definend as \tt dc<idName> and can be used as follows (\tt {"idName":"Example"}):
\code
qCdebug(dcExample) << "Hello world!";
qCWarning(dcExample) << "Warning the world!";
\endcode
Please start allways with a capital letter i.e. "idName": "ExamplePlugin". The logging category allowes you to categorise the debug output. It can be configured with the \tt -d argument of guhd (see \tt {$ man guhd}).
\li - \e id: The actual uuid (PluginId) of the plugin \unicode{0x2192} \l{DevicePlugin::pluginId()}
\li - \e vendors: The list of \l{Vendor}{Vendors} objects (see section "\l{The Vendor definition}");
Please start allways with a capital letter i.e. \tt {"idName": "Example"}. The logging category allowes you to categorise the debug output. It can be configured with the \tt -d argument of guhd (see \tt {$ man guhd}).
\li - \underline{\e id:} The actual uuid (\l{PluginId}) of the plugin \unicode{0x2192} \l{DevicePlugin::pluginId()}
\li - \underline{\e vendors:} The list of \l{Vendor}{Vendors} objects (see section "\l{The Vendor definition}");
\endlist
\section1 The Vendor definition
\section2 The Vendor definition
A plugin can support more then one \l{Vendor}, so the parameter \e vendors in the plugin definition is a list. Each element of this list represents a \l{Vendor} in guh.
\code
@ -108,13 +121,13 @@
\note All parameters \underline{must} be definend.
\list
\li - \e name: The visible name of the vendor \unicode{0x2192} \l{Vendor::name()}.
\li - \e idName: This parameter will be used to define the VendorId variable named <idName>VendorId in the plugininfo.h, so it can be used in the code.
\li - \e id: The actual uuid (VendorId) of the plugin \unicode{0x2192} \l{Vendor::id()}.
\li - \e deviceClasses: A list of \l{DeviceClass}{DeviceClasses} objects (see section "\l{The DeviceClass definition}").
\li - \underline{\e name:} The visible name of the vendor \unicode{0x2192} \l{Vendor::name()}.
\li - \underline{\e idName:} This parameter will be used to define the VendorId variable named <idName>VendorId in the plugininfo.h, so it can be used in the code.
\li - \underline{\e id:} The actual uuid (\l{VendorId}) of the plugin \unicode{0x2192} \l{Vendor::id()}.
\li - \underline{\e deviceClasses:} A list of \l{DeviceClass}{DeviceClasses} objects (see section "\l{The DeviceClass definition}").
\endlist
\section1 The DeviceClass definition
\section2 The DeviceClass definition
A \l{Vendor} can support more then one \l{DeviceClass}, so the parameter \e deviceClasses in the vendor definition is a list. Each element of this list represents a \l{DeviceClass} in guh.
\code
@ -152,32 +165,32 @@
A \l{DeviceClass} contains following parameters:
\list
\li - \e name: The visible name of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::name()}
\li - \e idName: This parameter will be used to define the DeviceClassId variable named <idName>DeviceClassId in the plugininfo.h, so it can be used in the code.
\li - \e deviceClassesId: The actual uuid (DeviceClassId) of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::id()}.
\li - \e createMethods: A list of possible \l{DeviceClass::CreateMethod}{CreateMethods} for this device \unicode{0x2192} \l{DeviceClass::createMethods()}. Some devices can be created in different ways. Possible values are:
\li - \underline{\e name:} The visible name of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::name()}
\li - \underline{\e idName:} This parameter will be used to define the DeviceClassId variable named <idName>DeviceClassId in the plugininfo.h, so it can be used in the code.
\li - \underline{\e deviceClassesId:} The actual uuid (\l{DeviceClassId}) of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::id()}.
\li - \underline{\e createMethods:} A list of possible \l{DeviceClass::CreateMethod}{CreateMethods} for this device \unicode{0x2192} \l{DeviceClass::createMethods()}. Some devices can be created in different ways. Possible values are:
\list
\li \e user \unicode{0x2192} \l{DeviceClass::CreateMethodUser}
\li \e discovery \unicode{0x2192} \l{DeviceClass::CreateMethodDiscovery}
\li \e auto \unicode{0x2192} \l{DeviceClass::CreateMethodAuto}
\endlist
\li - \e setupMethod: Definens the \l{DeviceClass::SetupMethod}{SetupMethod} of this device \unicode{0x2192} \l{DeviceClass::setupMethod()}. Possible values are:
\li - \underline{\e setupMethod:} Definens the \l{DeviceClass::SetupMethod}{SetupMethod} of this device \unicode{0x2192} \l{DeviceClass::setupMethod()}. Possible values are:
\list
\li \e justAdd \unicode{0x2192} \l{DeviceClass::SetupMethodJustAdd}
\li \e displayPin \unicode{0x2192} \l{DeviceClass::SetupMethodDisplayPin}
\li \e enterPin \unicode{0x2192} \l{DeviceClass::SetupMethodEnterPin}
\li \e pushButton \unicode{0x2192} \l{DeviceClass::SetupMethodPushButton}
\endlist
\li - \e pairingInfo: The \l{DeviceClass::pairingInfo()}{pairingInfo} will inform the user how to pair the device \unicode{0x2192} \l{DeviceClass::setupMethod()}. This parameter will only be used for \l{DeviceClass::SetupMethodDisplayPin}{DisplayPin} and \l{DeviceClass::SetupMethodEnterPin}{EnterPin} and \l{DeviceClass::SetupMethodPushButton}{PushButton}. Example: "Please press the button on the device before continue."
\li - \e discoveryParamTypes: A list of \l{ParamType}{ParamTypes} which will be needed for discovering a device \unicode{0x2192} \l{DeviceClass::discoveryParamTypes()}. This parameter will only be used for devices with the \l{DeviceClass::CreateMethodDiscovery}{CreateMethodDiscovery} (see section "\l{The ParamType definition}").
\li - \e paramTypes: A list of \l{ParamType}{ParamTypes} which define the paramters of a device \unicode{0x2192} \l{DeviceClass::paramTypes()} (see section "\l{The ParamType definition}").
\li - \e stateTypes: A list of \l{StateType}{StateTypes} of the device \unicode{0x2192} \l{DeviceClass::stateTypes()}. (see section "\l{The StateType definition}").
\li - \e actionTypes: A list of \l{ActionType}{ActionTypes} of the device \unicode{0x2192} \l{DeviceClass::actionTypes()}. (see section "\l{The ActionType definition}").
\li - \e eventTypes: A list of \l{EventType}{EventTypes} of the device \unicode{0x2192} \l{DeviceClass::eventTypes()}. (see section "\l{The EventType definition}").
\li - \underline{\e pairingInfo:} The \l{DeviceClass::pairingInfo()}{pairingInfo} will inform the user how to pair the device \unicode{0x2192} \l{DeviceClass::setupMethod()}. This parameter will only be used for \l{DeviceClass::SetupMethodDisplayPin}{DisplayPin} and \l{DeviceClass::SetupMethodEnterPin}{EnterPin} and \l{DeviceClass::SetupMethodPushButton}{PushButton}. Example: "Please press the button on the device before continue."
\li - \underline{\e discoveryParamTypes:} A list of \l{ParamType}{ParamTypes} which will be needed for discovering a device \unicode{0x2192} \l{DeviceClass::discoveryParamTypes()}. This parameter will only be used for devices with the \l{DeviceClass::CreateMethodDiscovery}{CreateMethodDiscovery} (see section "\l{The ParamType definition}").
\li - \underline{\e paramTypes:} A list of \l{ParamType}{ParamTypes} which define the paramters of a device \unicode{0x2192} \l{DeviceClass::paramTypes()} (see section "\l{The ParamType definition}").
\li - \underline{\e stateTypes:} A list of \l{StateType}{StateTypes} of the device \unicode{0x2192} \l{DeviceClass::stateTypes()} (see section "\l{The StateType definition}").
\li - \underline{\e actionTypes:} A list of \l{ActionType}{ActionTypes} of the device \unicode{0x2192} \l{DeviceClass::actionTypes()} (see section "\l{The ActionType definition}").
\li - \underline{\e eventTypes:} A list of \l{EventType}{EventTypes} of the device \unicode{0x2192} \l{DeviceClass::eventTypes()} (see section "\l{The EventType definition}").
\endlist
\section1 The ParamType definition
\section2 The ParamType definition
A \l{DeviceClass} can have a list of \l{ParamType}{ParamTypes} which will be filled out during the setup and describe the device. Each device should have a parameter "name" to allow the user to give a device an individual name like: "Desk lamp in the living room". \l{ParamType}{ParamTypes} will be used for \e discoveryParamType in the \l{DeviceClass} definition and in the \l{ActionType} and \l{EventType} definition.
\code
@ -203,20 +216,36 @@
\endcode
\list
\li - \e name: The visible name of the \l{ParamType} \unicode{0x2192} \l{ParamType::name()}.
\li - \e type: The data type of this paramter \unicode{0x2192} \l{ParamType::type()}.
\li - \e inputType: A paramter for clients to know which kind of InputType this.
\li - \e defaultValue: Sets the default value of the \{ParamType}. If a parameter will not be set by the user, the parameter will be set to this value \unicode{0x2192} \l{ParamType::defaultValue()}.
\li - \e unit: With this parameter you can specify the unit of the parameter i.e. \unicode{0x00B0}C \unicode{0x2192} DegreeCelsius.
\li - \e minValue: Sets the minimum limit for this \{ParamType}. Can only be set for \e int and \e double values. If the user tries to set the value smaller than the \e minValue, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation.
\li - \e maxValue: Sets the maximum limit for this \{ParamType}. Can only be set for \e int and \e double values. If the user tries to set the value greater than the \e maxValue, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation.
\li - \e allowedValues: Gives you the possibility to define a list of allowed values. If the user tries to set the value which is not in the \e allowedValues list, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation. This is typically used for strings i.e. ["North", "East", "South", "West"].
\li - \e readOnly: Bool value to make this \{ParamType} realOnly. When you want to edit the params of a device you only can edit the parameters which are \tt {"readOnly": false}. If not specified, the parameter is writeable by default.
\li - \underline{\e name:} The visible name of the \l{ParamType} \unicode{0x2192} \l{ParamType::name()}.
\li - \underline{\e type:} The data type of this paramter \unicode{0x2192} \l{ParamType::type()}.
\li - \underline{\e inputType:} A paramter for clients to know which kind of \l{Types::InputType}{InputType} this. See enum \l{Types::InputType} for more information. The expected value for the \e inputType parameter matches the enum name like this:
\tt {Types::InputTypeTextArea} \unicode{0x2192} \tt {"inputType": "TextArea"}
\tt {Types::InputTypePassword} \unicode{0x2192} \tt {"inputType": "Password"}
\tt ...
\li - \underline{\e defaultValue:} Sets the default value of the \{ParamType}. If a parameter will not be set by the user, the parameter will be set to this value \unicode{0x2192} \l{ParamType::defaultValue()}.
\li - \underline{\e unit:} With this parameter you can specify the \l{Types::Unit}{Unit} of the parameter i.e. \unicode{0x00B0}C \unicode{0x2192} DegreeCelsius. See enum \l{Types::Unit} for more information. The expected value for the \e unit parameter matches the enum name like this:
\tt {Types::UnitDegreeCelsius} \unicode{0x2192} \tt {"unit": "DegreeCelsius"}
\tt {Types::UnitMetersPerHour} \unicode{0x2192} \tt {"unit": "MetersPerHour"}
\tt ...
\li - \underline{\e minValue:} Sets the minimum limit for this \l{ParamType}. Can only be set for \e int and \e double values. If the user tries to set the value smaller than the \e minValue, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation.
\li - \underline{\e maxValue:} Sets the maximum limit for this \l{ParamType}. Can only be set for \e int and \e double values. If the user tries to set the value greater than the \e maxValue, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation.
\li - \underline{\e allowedValues:} Gives you the possibility to define a list of allowed values. If the user tries to set the value which is not in the \e allowedValues list, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation. This is typically used for strings i.e. ["North", "East", "South", "West"].
\li - \underline{\e readOnly:} Bool value to make this \l{ParamType} realOnly. When you want to edit the params of a device you only can edit the parameters which are \tt {"readOnly": false}. If not specified, the parameter is writeable by default.
\endlist
\section1 The StateType definition
A \l{DeviceClass} can have a list of \l{StateType}{StateTypes} which allow you to represent a state of a device. A \l{State} can be changed/updated in the plugin code. If you change a state in the plugin using \l{Device::setStateValue()} an \l{Event} will generate automatically in the \l{guhserver::GuhCore}. This \l{Event} has the same uuid (EventTypeId) like the \l{State} which created the "<stateName> changed" \l{Event}. The event will have exactly one \l{Param}, which has the same properties like the \l{StateType} value and contains the new value.
\section2 The StateType definition
A \l{DeviceClass} can have a list of \l{StateType}{StateTypes} which allow you to represent a state of a device. A \l{State} can be changed/updated in the plugin code. If you change a state in the plugin using \l{Device::setStateValue()} an \l{Event} will generate automatically in the \l{guhserver::GuhCore}. This \l{Event} has the same uuid (\l{EventTypeId}) like the \l{State} which created the "<stateName> changed" \l{Event}. The event will have exactly one \l{Param}, which has the same properties like the \l{StateType} value and contains the new value.
A \l{StateType} has following parameters:
@ -240,20 +269,20 @@ A \l{StateType} has following parameters:
\endcode
\list
\li - \e name: The visible name of the \l{ParamType} \unicode{0x2192} \l{ParamType::name()}.
\li - \e idName: This parameter will be used to define the StateTypeId variable named <idName>StateTypeId in the plugininfo.h, so it can be used in the code.
\li - \e id: The actual uuid (StateTypeId) of the \l{StateType} \unicode{0x2192} \l{StateType::id()}.
\li - \e type: The data type of this state \unicode{0x2192} \l{StateType::type()}.
\li - \e unit: With this parameter you can specify the unit of the state value i.e. \unicode{0x00B0}C \unicode{0x2192} DegreeCelsius.
\li - \e defaultValue: The state will be initialized with this value.
\li - \e writable: If you define the \e writable object an \l{ActionType} will be created to set the \l{State} value. The created \l{ActionType} has the same uuid (ActionTypeId) like the \l{StateType} uuid and will be named "set <stateName>". Since a \l{ParamType} has some properties which are not in the \{StateType} definition like \e allowedValues or \e minValue / \e maxValue, you can specify them in the \e writable Object.
\li - \underline{\e name:} The visible name of the \l{ParamType} \unicode{0x2192} \l{ParamType::name()}.
\li - \underline{\e idName:} This parameter will be used to define the StateTypeId variable named <idName>StateTypeId in the plugininfo.h, so it can be used in the code.
\li - \underline{\e id:} The actual uuid (\l{StateTypeId}) of the \l{StateType} \unicode{0x2192} \l{StateType::id()}.
\li - \underline{\e type:} The data type of this state \unicode{0x2192} \l{StateType::type()}.
\li - \underline{\e unit:} With this parameter you can specify the unit of the state value i.e. \unicode{0x00B0}C \unicode{0x2192} DegreeCelsius.
\li - \underline{\e defaultValue:} The state will be initialized with this value.
\li - \underline{\e writable:} If you define the \e writable object an \l{ActionType} will be created to set the \l{State} value. The created \l{ActionType} has the same uuid (\l{ActionTypeId}) like the \l{StateType} uuid and will be named "set <stateName>". Since a \l{ParamType} has some properties which are not in the \l{StateType} definition like \e allowedValues or \e minValue / \e maxValue, you can specify them in the \e writable Object.
If a \l{StateType} has the property \e writable the \l{DeviceManager} will create automatically an \l{ActionType} for this state, which will also have exactly one \l{Param} with the same properties like the \l{StateType}. The created \l{ActionType} has the same uuid (ActionTypeId) like the \l{StateType} uuid and will be named "set <stateName>".
If a \l{StateType} has the property \e writable the \l{DeviceManager} will create automatically an \l{ActionType} for this state, which will also have exactly one \l{Param} with the same properties like the \l{StateType}. The created \l{ActionType} has the same uuid (\l{ActionTypeId}) like the \l{StateType} uuid and will be named "set <stateName>".
This mechanism was created to ensure that the \l{EventType} and \l{ActionType} which correspond to a certain \l{StateType} will always be equal. This makes it possible for clients to know that an \l{Action} will set the \a value of a \l{State}, and an \l{Event} was generated by the corresponding \l{State}.
\tt {StateTypeId == EventTypeId == ActionTypeId}
\tt {\l{StateTypeId} == \l{EventTypeId} == \l{ActionTypeId}}
Example \l{StateType}: Following \l{StateType} stands for a volume \l{State} named \e volume. The value of this \l{State} has the data type \tt int and the unit \tt \%. This \l{StateType} is writable, which means there will be an \l{ActionType} generated with \e id \tt 9bc84381-785f-46bf-94c8-6e35116f50d3. The generated \l{ActionType} will have one \e paramType which has the \e name = \tt volume, \e type = \tt int, \e minValue = \tt 0, \e maxValue =\tt 100, \e unit = \tt Percentage. The \l{ActionType} name will be "set volume". If the value of the \l{State} will be changed, an \l{Event} will be generated. The \l{ParamType} of the event will be equal to the \l{ParamType} of the generated \l{ActionType}.
@ -306,7 +335,7 @@ This mechanism was created to ensure that the \l{EventType} and \l{ActionType} w
\endcode
\endlist
\section1 The ActionType definition
\section2 The ActionType definition
A \l{DeviceClass} can have more then one \l{ActionType}, so the parameter \e actionTypes in the \l{DeviceClass} definition is a list. Each element of this list represents an \l{ActionType} in guh.
\code
@ -326,13 +355,13 @@ This mechanism was created to ensure that the \l{EventType} and \l{ActionType} w
\endcode
\list
\li - \e name: The visible name of the \l{ActionType} \unicode{0x2192} \l{ActionType::name()}.
\li - \e idName: This parameter will be used to define the ActionTypeId variable named <idName>ActionTypeId in the plugininfo.h, so it can be used in the code.
\li - \e id: The actual uuid (ActionTypeId) of the \l{ActionType} \unicode{0x2192} \l{ActionType::id()}.
\li - \e paramTypes: A list of \l{ParamType}{ParamTypes} (see section "\l{The ParamType definition}") for this \l{ActionType}. This parameter is optional. You can also create an \l{ActionType} which has no \l{ParamType}{ParamTypes}.
\li - \underline{\e name:} The visible name of the \l{ActionType} \unicode{0x2192} \l{ActionType::name()}.
\li - \underline{\e idName:} This parameter will be used to define the ActionTypeId variable named <idName>ActionTypeId in the plugininfo.h, so it can be used in the code.
\li - \underline{\e id:} The actual uuid (\l{ActionTypeId}) of the \l{ActionType} \unicode{0x2192} \l{ActionType::id()}.
\li - \underline{\e paramTypes:} A list of \l{ParamType}{ParamTypes} (see section "\l{The ParamType definition}") for this \l{ActionType}. This parameter is optional. You can also create an \l{ActionType} which has no \l{ParamType}{ParamTypes}.
\endlist
\section1 The EventType definition
\section2 The EventType definition
A \l{DeviceClass} can have more then one \l{EventType}, so the parameter \e eventTypes in the \l{DeviceClass} definition is a list. Each element of this list represents an \l{EventType} in guh.
\code
@ -352,10 +381,10 @@ This mechanism was created to ensure that the \l{EventType} and \l{ActionType} w
\endcode
\list
\li - \e name: The visible name of the \l{EventType} \unicode{0x2192} \l{EventType::name()}.
\li - \e idName: This parameter will be used to define the EventTypeId variable named <idName>EventTypeId in the plugininfo.h, so it can be used in the code.
\li - \e id: The actual uuid (EventTypeId) of the \l{EventType} \unicode{0x2192} \l{EventType::id()}.
\li - \e paramTypes: A list of \l{ParamType}{ParamTypes} (see section "\l{The ParamType definition}") for this \l{EventType}. This parameter is optional. You can also create an \l{EventType} which has no \l{ParamType}{ParamTypes}.
\li - \underline{\e name:} The visible name of the \l{EventType} \unicode{0x2192} \l{EventType::name()}.
\li - \underline{\e idName:} This parameter will be used to define the EventTypeId variable named <idName>EventTypeId in the plugininfo.h, so it can be used in the code.
\li - \underline{\e id:} The actual uuid (\l{EventTypeId}) of the \l{EventType} \unicode{0x2192} \l{EventType::id()}.
\li - \underline{\e paramTypes:} A list of \l{ParamType}{ParamTypes} (see section "\l{The ParamType definition}") for this \l{EventType}. This parameter is optional. You can also create an \l{EventType} which has no \l{ParamType}{ParamTypes}.
\endlist
*/

7
doc/server-classes.qdoc Normal file
View File

@ -0,0 +1,7 @@
/*!
\page server-classes.html
\title Server classes
\annotatedlist server
*/

16
doc/style.css
View File

@ -228,7 +228,7 @@
/* end font style elements */
/* global settings*/
.header, .footer
.header
{
display: block;
clear: both;
@ -236,6 +236,14 @@
background: #404244;
height: 11.5em;
}
.footer
{
display: block;
clear: both;
overflow: hidden;
background: #404244;
height: 3.5em;
}
/* end global settings*/
/* header elements */
@ -602,16 +610,16 @@
.footer
{
color: #393735;
font-size: 1em;
font-size: 0.8em;
text-align: center;
padding-top: 1.5em;
padding-top: 0.75em;
padding-bottom: 1em;
background-color: #E6E7E8;
margin: 0;
}
.footer p
{
margin: 0.25em
margin: 1.2em
}
.small
{

7
doc/tutorial2.qdoc Normal file
View File

@ -0,0 +1,7 @@
/*!
\page tutorial2.html
\title Tutorial 2
*/

6
doc/types.qdoc
View File

@ -1,6 +1,6 @@
/*!
\page types.html
\title Types
\page libguh-types.html
\title Types of libguh
\annotatedlist types
\annotatedlist guh-types
*/

305
doc/typeutils.qdoc Normal file
View File

@ -0,0 +1,305 @@
/*!
\page typeutils.h
\title Type Utils
\chapter Types::StateOperator
\table
\header
\li Constant
\li Value
\li Description
\row
\li Types::StateOperatorAnd
\li 0
\li The logical AND \tt & operator for two \l{State}{States}
\row
\li Types::StateOperatorOr
\li 1
\li The logical OR \tt | operator for two \l{State}{States}
\endtable
\chapter Types::ValueOperator
\table
\header
\li Constant
\li Value
\li Description
\row
\li Types::ValueOperatorEquals
\li 0
\li The \tt = operator to compare two \a values of a \l{Param}.
\row
\li Types::ValueOperatorNotEquals
\li 1
\li The \tt != operator to compare two \a values of a \l{Param}.
\row
\li Types::ValueOperatorLess
\li 2
\li The \tt < operator to compare two \a values of a \l{Param}.
\row
\li Types::ValueOperatorGreater
\li 3
\li The \tt > operator to compare two \a values of a \l{Param}.
\row
\li Types::ValueOperatorLessOrEqual
\li 4
\li The \tt <= operator to compare two \a values of a \l{Param}.
\row
\li Types::ValueOperatorGreaterOrEqual
\li 5
\li The \tt >= operator to compare two \a values of a \l{Param}.
\endtable
\chapter Types::InputType
\table
\header
\li Constant
\li Value
\li Description
\row
\li Types::InputTypeNone
\li 0
\li The \l{ParamType} has no \l{Types::InputType}{InputType}
\row
\li Types::InputTypeTextLine
\li 1
\li The \l{ParamType} suggests a string text line as \l{Types::InputType}{InputType}
\row
\li Types::InputTypeTextArea
\li 2
\li The \l{ParamType} suggests a string text area as \l{Types::InputType}{InputType}
\row
\li Types::InputTypePassword
\li 3
\li The \l{ParamType} indicates that this is a password \l{Types::InputType}{InputType}. Maby the characters should be covered.
\row
\li Types::InputTypeSearch
\li 4
\li The \l{ParamType} indicates that this is a search \l{Types::InputType}{InputType}.
\row
\li Types::InputTypeMail
\li 5
\li The \l{ParamType} indicates that a mail address is requested as \l{Types::InputType}{InputType}.
\row
\li Types::InputTypeIPv4Address
\li 6
\li The \l{ParamType} indicates that a IPv4 address is requested as \l{Types::InputType}{InputType}.
\row
\li Types::InputTypeIPv6Address
\li 7
\li The \l{ParamType} indicates that a IPv6 address is requested as \l{Types::InputType}{InputType}.
\row
\li Types::InputTypeUrl
\li 8
\li The \l{ParamType} indicates that a URL is requested as \l{Types::InputType}{InputType}.
\row
\li Types::InputTypeMacAddress
\li 9
\li The \l{ParamType} indicates that a MAC hardware address is requested as \l{Types::InputType}{InputType}.
\endtable
\chapter Types::Unit
\table
\header
\li Constant
\li Value
\li Description
\row
\li Types::UnitNone
\li 0
\li The value of the \l{Param} has no unit.
\row
\li Types::UnitSeconds
\li 1
\li The value of the \l{Param} has unit \tt [s] \unicode{0x2192} seconds.
\row
\li Types::UnitMinutes
\li 2
\li The value of the \l{Param} has unit \tt [min] \unicode{0x2192} minutes.
\row
\li Types::UnitHours
\li 3
\li The value of the \l{Param} has unit \tt [h] \unicode{0x2192} hours.
\row
\li Types::UnitUnixTime
\li 4
\li The value of the \l{Param} has unit \tt [s] \unicode{0x2192} seconds since epoch.
\row
\li Types::UnitMeterPerSecond
\li 5
\li The value of the \l{Param} has unit \tt [m/s] \unicode{0x2192} meters per second.
\row
\li Types::UnitKiloMeterPerHour
\li 6
\li The value of the \l{Param} has unit \tt [km/h] \unicode{0x2192} kilo meters per hour.
\row
\li Types::UnitDegree
\li 7
\li The value of the \l{Param} has unit \tt {[\unicode{0x00B0}]} \unicode{0x2192} degree.
\row
\li Types::UnitRadiant
\li 8
\li The value of the \l{Param} has unit \tt [rad] \unicode{0x2192} radiant.
\row
\li Types::UnitDegreeCelsius
\li 9
\li The value of the \l{Param} has unit \tt {[\unicode{0x00B0} C]} \unicode{0x2192} degree celsius.
\row
\li Types::UnitDegreeKelvin
\li 10
\li The value of the \l{Param} has unit \tt {[K]} \unicode{0x2192} kelvin.
\row
\li Types::UnitMired
\li 11
\li The value of the \l{Param} has unit \tt {[mir]} \unicode{0x2192} mired.
\row
\li Types::UnitMilliBar
\li 12
\li The value of the \l{Param} has unit \tt {[mbar]} \unicode{0x2192} milli bar.
\row
\li Types::UnitBar
\li 13
\li The value of the \l{Param} has unit \tt {[bar]} \unicode{0x2192} bar.
\row
\li Types::UnitPascal
\li 14
\li The value of the \l{Param} has unit \tt {[Pa]} \unicode{0x2192} pascal.
\row
\li Types::UnitHectoPascal
\li 15
\li The value of the \l{Param} has unit \tt {[hPa]} \unicode{0x2192} hecto pascal.
\row
\li Types::UnitAtmosphere
\li 16
\li The value of the \l{Param} has unit \tt {[atm]} \unicode{0x2192} atmosphere.
\row
\li Types::UnitLumen
\li 17
\li The value of the \l{Param} has unit \tt {[lm]} \unicode{0x2192} lumen.
\row
\li Types::UnitLux
\li 18
\li The value of the \l{Param} has unit \tt {[lx]} \unicode{0x2192} lux.
\row
\li Types::UnitCandela
\li 19
\li The value of the \l{Param} has unit \tt {[cd]} \unicode{0x2192} candela.
\row
\li Types::UnitMilliMeter
\li 20
\li The value of the \l{Param} has unit \tt {[mm]} \unicode{0x2192} milli meter.
\row
\li Types::UnitCentiMeter
\li 21
\li The value of the \l{Param} has unit \tt {[cm]} \unicode{0x2192} centi meter.
\row
\li Types::UnitMeter
\li 22
\li The value of the \l{Param} has unit \tt {[m]} \unicode{0x2192} meter.
\row
\li Types::UnitKiloMeter
\li 23
\li The value of the \l{Param} has unit \tt {[km]} \unicode{0x2192} kilo meter.
\row
\li Types::UnitGram
\li 24
\li The value of the \l{Param} has unit \tt {[g]} \unicode{0x2192} gram.
\row
\li Types::UnitKiloGram
\li 25
\li The value of the \l{Param} has unit \tt {[gg]} \unicode{0x2192} kilo gram.
\row
\li Types::UnitDezibel
\li 26
\li The value of the \l{Param} has unit \tt {[db]} \unicode{0x2192} dezibel.
\row
\li Types::UnitKiloByte
\li 27
\li The value of the \l{Param} has unit \tt {[kB]} \unicode{0x2192} kilo byte.
\row
\li Types::UnitMegaByte
\li 28
\li The value of the \l{Param} has unit \tt {[mB]} \unicode{0x2192} mega byte.
\row
\li Types::UnitGigaByte
\li 29
\li The value of the \l{Param} has unit \tt {[GB]} \unicode{0x2192} giga byte.
\row
\li Types::UnitTeraByte
\li 30
\li The value of the \l{Param} has unit \tt {[TB]} \unicode{0x2192} tera byte.
\row
\li Types::UnitMilliWatt
\li 31
\li The value of the \l{Param} has unit \tt {[mW]} \unicode{0x2192} milli watt.
\row
\li Types::UnitWatt
\li 32
\li The value of the \l{Param} has unit \tt {[W]} \unicode{0x2192} watt.
\row
\li Types::UnitKiloWatt
\li 33
\li The value of the \l{Param} has unit \tt {[kW]} \unicode{0x2192} kilo watt.
\row
\li Types::UnitKiloWattHour
\li 34
\li The value of the \l{Param} has unit \tt {[kWh]} \unicode{0x2192} kilo watt hour.
\row
\li Types::UnitPercentage
\li 35
\li The value of the \l{Param} has unit \tt {[\%]} \unicode{0x2192} percentage.
\row
\li Types::UnitEuro
\li 36
\li The value of the \l{Param} has unit \tt {[€]} \unicode{0x2192} euro.
\row
\li Types::UnitDollar
\li 37
\li The value of the \l{Param} has unit \tt {[\$]} \unicode{0x2192} dollar.
\endtable
\chapter UUID Types
\section2 PluginId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{DevicePlugin}.
\section2 VendorId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{Vendor}.
\section2 DeviceClassId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{DeviceClass}.
\section2 DeviceId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{Device}.
\section2 DeviceDescriptorId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{DeviceDescriptor}.
\section2 EventTypeId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{EventType}.
\section2 EventId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{Event}.
\section2 StateTypeId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{StateType}.
\section2 StateId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{State}.
\section2 ActionTypeId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{ActionType}.
\section2 ActionId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{Action} and \l{RuleAction}.
\section2 RuleId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a \l{guhserver::Rule}.
\section2 PairingTransactionId
This class is a subclass of \l{http://doc.qt.io/qt-5/quuid.html}{QUuid} and represents the \e id of a pairing transaction.
*/

11
doc/write-plugins.qdoc
View File

@ -3,19 +3,14 @@
\title How to write a plugin
\brief This tutorial shows you how to write a plugin for your own device / service / protocol.
\chapter Create the build environment
Assuming you are working an an Ubuntu system here are the steps how to set up the build environment.
\section1 Install guh
\section1 Install Qt
\section2 Install Qt
\section1 Install guh dependencys
\section2 Install guh dependencys
\code
$ sudo apt-get install guh libguh1-dev

1
libguh/libguh.pro
View File

@ -40,7 +40,6 @@ SOURCES += plugin/device.cpp \
loggingcategories.cpp \
guhsettings.cpp \
HEADERS += plugin/device.h \
plugin/deviceclass.h \
plugin/deviceplugin.h \

15
libguh/plugin/deviceplugin.cpp
View File

@ -32,8 +32,10 @@
/*!
\fn DeviceManager::HardwareResources DevicePlugin::requiredHardware() const
Return flags describing the common hardware resources required by this plugin.
\sa DevicePlugin::transmitData(), DevicePlugin::radioData(), DevicePlugin::guhTimer()
Return flags describing the common hardware resources required by this plugin. If you want to
use more than one resource, you can combine them ith the OR operator.
\sa DeviceManager::HardwareResource
*/
/*!
@ -53,6 +55,7 @@
If the plugin has requested the UPnP device list using \l{DevicePlugin::upnpDiscover()}, this slot will be called after 3
seconds (search timeout). The \a upnpDeviceDescriptorList will contain the description of all UPnP devices available
in the network.
\sa upnpDiscover(), UpnpDeviceDescriptor, UpnpDiscovery::discoveryFinished()
*/
@ -60,12 +63,20 @@
\fn void DevicePlugin::upnpNotifyReceived(const QByteArray &notifyData)
If a UPnP device will notify a NOTIFY message in the network, the \l{UpnpDiscovery} will catch the
notification data and call this method with the \a notifyData.
\note Only if if the plugin has requested the \l{DeviceManager::HardwareResourceUpnpDisovery} resource
using \l{DevicePlugin::requiredHardware()}, this slot will be called.
\sa UpnpDiscovery
*/
/*!
\fn DevicePlugin::networkManagerReplyReady(QNetworkReply *reply)
This method will be called whenever a pending network \a reply for this plugin is finished.
\note Only if if the plugin has requested the \l{DeviceManager::HardwareResourceNetworkManager}
resource using \l{DevicePlugin::requiredHardware()}, this slot will be called.
\sa NetworkManager::replyReady()
*/

2
libguh/types/action.cpp
View File

@ -23,7 +23,7 @@
\class Action
\brief Holds information required to execute an action described by a \l{ActionType}.
\ingroup types
\ingroup guh-types
\inmodule libguh
It is bound to a \l{Device} and an \l{ActionType} and holds the parameters

2
libguh/types/actiontype.cpp
View File

@ -23,7 +23,7 @@
\class ActionType
\brief Describes an \l{Action} for a \l{Device}.
\ingroup types
\ingroup guh-types
\inmodule libguh
ActionTypes are contained in \l{DeviceClass} templates returned

2
libguh/types/event.cpp
View File

@ -23,7 +23,7 @@
\class Event
\brief Holds information required to emit a event described by a \l{EventType}.
\ingroup types
\ingroup guh-types
\inmodule libguh
It is bound to a \l{Device} and a \l{EventType} and holds the parameters

2
libguh/types/eventdescriptor.cpp
View File

@ -23,7 +23,7 @@
\class EventDescriptor
\brief Describes a certain \l{Event}.
\ingroup types
\ingroup guh-types
\inmodule libguh
An EventDescriptor describes an \l{Event} in order to match it with a \l{guhserver::Rule}.

2
libguh/types/eventtype.cpp
View File

@ -23,7 +23,7 @@
\class EventType
\brief Describes a \l{Event} for a \l{Device}.
\ingroup types
\ingroup guh-types
\inmodule libguh
\sa Event, EventDescriptor

2
libguh/types/param.cpp
View File

@ -23,7 +23,7 @@
\class Param
\brief Holds the parameters of a Param.
\ingroup types
\ingroup guh-types
\inmodule libguh
\sa Device, ParamType, ParamDescriptor

2
libguh/types/paramdescriptor.cpp
View File

@ -23,7 +23,7 @@
\class ParamDescriptor
\brief Describes a certain \l{Param}.
\ingroup types
\ingroup guh-types
\inmodule libguh
An ParamDescriptor describes a \l{Param} in order to match it with a \l{guhserver::Rule}.

2
libguh/types/paramtype.cpp
View File

@ -23,7 +23,7 @@
\class ParamType
\brief Describes a certain ParamType.
\ingroup types
\ingroup guh-types
\inmodule libguh
\sa Device, Param, ParamDescriptor

2
libguh/types/ruleaction.cpp
View File

@ -23,7 +23,7 @@
\class RuleAction
\brief Describes an action for a \l{guhserver::Rule}.
\ingroup types
\ingroup guh-types
\inmodule libguh
A RuleAction describes a special form of an \l{Action} for a \l{guhserver::Rule}. The main difference is

2
libguh/types/ruleactionparam.cpp
View File

@ -23,7 +23,7 @@
\class RuleActionParam
\brief Holds the parameters for a \l{RuleAction}.
\ingroup types
\ingroup guh-types
\inmodule libguh
A RuleActionParam allows rules to take over an \l{Event} parameter into a rule

2
libguh/types/state.cpp
View File

@ -23,7 +23,7 @@
\class State
\brief Holds the parameters of a State of a \l{Device}.
\ingroup types
\ingroup guh-types
\inmodule libguh
States hold the state values for devices. A State is associated to a \l{Device} by

2
libguh/types/statedescriptor.cpp
View File

@ -23,7 +23,7 @@
\class StateDescriptor
\brief Describes a certain \l{State}.
\ingroup types
\ingroup guh-types
\inmodule libguh
An StateDescriptor describes a \l{State} in order to match it with a \l{guhserver::Rule}.

2
libguh/types/statetype.cpp
View File

@ -23,7 +23,7 @@
\class StateType
\brief Describes the Type of a \l{State} from \l{Device}.
\ingroup types
\ingroup guh-types
\inmodule libguh
\sa State, StateDescriptor

2
libguh/types/vendor.cpp
View File

@ -23,7 +23,7 @@
\class Vendor
\brief Holds information about a the vendor of a \l{Device}.
\ingroup types
\ingroup guh-types
\inmodule libguh
\sa DevicePlugin

2
libguh/typeutils.h
View File

@ -130,6 +130,8 @@ public:
StateOperatorAnd,
StateOperatorOr
};
Types(QObject *parent = 0);
};
Q_DECLARE_METATYPE(Types::ValueOperator)

3
server/guhcore.cpp
View File

@ -23,8 +23,7 @@
\class guhserver::GuhCore
\brief The main entry point for the Guh Server and the place where all the messages are dispatched.
\ingroup core
\inmodule server
\inmodule core
GuhCore is a singleton instance and the main entry point of the Guh daemon. It is responsible to
instantiate, set up and connect all the other components.

4
server/httpreply.cpp
View File

@ -22,8 +22,8 @@
\class guhserver::HttpReply
\brief Represents a reply of the guh webserver to a \l{HttpRequest}.
\ingroup core
\inmodule server
\ingroup api
\inmodule core
This class holds the header and the payload data of a network reply and represents a response
from the guh webserver to a \l{HttpRequest}.

4
server/httprequest.cpp
View File

@ -22,8 +22,8 @@
\class guhserver::HttpRequest
\brief Represents a HTTP request from a client to the guh \l{WebServer}.
\ingroup core
\inmodule server
\ingroup api
\inmodule core
This class holds the header and the payload data of a network request from a client to the \l{WebServer}.

22
server/jsonrpc/jsonrpcserver.cpp
View File

@ -19,6 +19,23 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class guhserver::JsonRPCServer
\brief This class provides a JSON-RPC API interface to the \l{TransportInterface}{TransportInterfaces}.
\ingroup server
\inmodule core
The \l{JsonRPCServer} class provides the server interface for a JSON-RPC API call. This class
communicates with \l{TransportInterface}{TransportInterfaces} and processes the
JSON-RPC request in the corresponding \l{JsonHandler}. The \l{JsonRPCServer} it self is also
an \l{JsonHandler} and provides the introspection, version and notification control methods
for the \l{JSON-RPC API}.
\sa ServerManager, TransportInterface, TcpServer, WebSocketServer
*/
#include "jsonrpcserver.h"
#include "jsontypes.h"
#include "jsonhandler.h"
@ -54,6 +71,7 @@
namespace guhserver {
/*! Constructs a \l{JsonRPCServer} with the given \a sslConfiguration and \a parent. */
JsonRPCServer::JsonRPCServer(const QSslConfiguration &sslConfiguration, QObject *parent):
JsonHandler(parent),
#ifdef TESTING_ENABLED
@ -113,6 +131,7 @@ JsonRPCServer::JsonRPCServer(const QSslConfiguration &sslConfiguration, QObject
QMetaObject::invokeMethod(this, "setup", Qt::QueuedConnection);
}
/*! Returns the \e namespace of \l{JsonHandler}. */
QString JsonRPCServer::name() const
{
return QStringLiteral("JSONRPC");
@ -158,6 +177,7 @@ JsonReply* JsonRPCServer::SetNotificationStatus(const QVariantMap &params)
return createReply(returns);
}
/*! Returns the list of registred \l{JsonHandler}{JsonHandlers} and their name.*/
QHash<QString, JsonHandler *> JsonRPCServer::handlers() const
{
return m_handlers;
@ -182,8 +202,6 @@ void JsonRPCServer::processData(const QUuid &clientId, const QString &targetName
int commandId = message.value("id").toInt();
QVariantMap params = message.value("params").toMap();
emit commandReceived(targetNamespace, method, params);
JsonHandler *handler = m_handlers.value(targetNamespace);
QPair<bool, QString> validationResult = handler->validateParams(method, params);
if (!validationResult.first) {

3
server/jsonrpc/jsonrpcserver.h
View File

@ -65,9 +65,6 @@ public:
QHash<QString, JsonHandler*> handlers() const;
signals:
void commandReceived(const QString &targetNamespace, const QString &command, const QVariantMap &params);
private slots:
void setup();

49
server/rest/restresource.cpp
View File

@ -18,6 +18,45 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class guhserver::RestResource
\brief This class provides an interface for REST API resources.
\ingroup api
\inmodule core
The \l{RestResource} class provides an interface for subclassing a new resource for
the REST API. A resource represents an Object in the core like \l{Device}{Devices}
or \l{DevicePlugin}{Plugins}. A \l{RestResource} will be identified by it's
\l{RestResource::name()}{name}.
Each subclass of \l{RestResource} has to implement the method \l{RestResource::proccessRequest()}
where a valid \l{HttpRequest} will be processed.
This name of the resource will define the endpoint of the an API call:
\code
http://localhost:3333/api/v1/<resourceName>
\endcode
\sa RestServer
*/
/*! \fn QString guhserver::RestResource::name() const;
This method must be implemented in a subclass of \l{RestResource}. It returns
the endpoint name of this \l{RestResource} i.e. if this method returns \tt "example"
the API resource will be accessable with the URL:
\code
http://localhost:3333/api/v1/example
\endcode
*/
/*! \fn HttpReply *guhserver::RestResource::proccessRequest(const HttpRequest &request, const QStringList &urlTokens)
This method will be called from the \l{RestServer} once a \l{HttpRequest} \a request was identified to belong
to this \l{RestResource}. The given \a urlTokens contain the full list of URL tokens from this request.
*/
#include "restresource.h"
#include "httprequest.h"
#include "loggingcategories.h"
@ -28,15 +67,18 @@
namespace guhserver {
/*! Constructs a \l{RestResource} with the given \a parent. */
RestResource::RestResource(QObject *parent) :
QObject(parent)
{
}
/*! Pure virtual destructor for this \l{RestResource}. */
RestResource::~RestResource()
{
}
/*! Returns the pointer to a new created \l{HttpReply} initialized with \l{HttpReply::Ok} and \l{HttpReply::TypeSync}. */
HttpReply *RestResource::createSuccessReply()
{
HttpReply *reply = new HttpReply(HttpReply::Ok, HttpReply::TypeSync);
@ -44,6 +86,7 @@ HttpReply *RestResource::createSuccessReply()
return reply;
}
/*! Returns the pointer to a new created error \l{HttpReply} initialized with the given \a statusCode and \l{HttpReply::TypeSync}. */
HttpReply *RestResource::createErrorReply(const HttpReply::HttpStatusCode &statusCode)
{
HttpReply *reply = new HttpReply(statusCode, HttpReply::TypeSync);
@ -51,12 +94,18 @@ HttpReply *RestResource::createErrorReply(const HttpReply::HttpStatusCode &statu
return reply;
}
/*! Returns the pointer to a new created \l{HttpReply} initialized with \l{HttpReply::Ok} and \l{HttpReply::TypeAsync}. */
HttpReply *RestResource::createAsyncReply()
{
HttpReply *reply = new HttpReply(HttpReply::Ok, HttpReply::TypeAsync);
return reply;
}
/*! This method can be used from every \l{RestResource} in order to verify if the \a payload of a
\l{HttpRequest} is a valid JSON document. Returns \tt true and the valid \e QVariant if there
was no error while parsing JSON. Returns \tt false and an invalid \e QVariant if the \a payload
could not be parsed.
*/
QPair<bool, QVariant> RestResource::verifyPayload(const QByteArray &payload)
{
QVariant data;

17
server/rest/restserver.cpp
View File

@ -18,6 +18,22 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class guhserver::RestServer
\brief This class provides the REST API interface to the \l{WebServer}{WebServers}.
\ingroup server
\inmodule core
The \l{RestServer} class provides the server interface for a REST API call. The \l{RestServer}
will create a \l{WebServer} object. The \l{WebServer} will parse the \l{HttpRequest} and emits
the signal \l{WebServer::httpRequestReady()}. This signal will be catched from this \l{RestServer}
and processed by the corresponding \l{RestResource}. Once the \l{HttpRequest} is finished, the
\l{RestServer} will send a \l{HttpReply} back to the client using \l{WebServer::sendHttpReply()}.
\sa ServerManager, WebServer, HttpRequest, HttpReply
*/
#include "restserver.h"
#include "loggingcategories.h"
#include "httprequest.h"
@ -29,6 +45,7 @@
namespace guhserver {
/*! Constructs a \l{RestServer} with the given \a sslConfiguration and \a parent. */
RestServer::RestServer(const QSslConfiguration &sslConfiguration, QObject *parent) :
QObject(parent)
{

4
server/rule.cpp
View File

@ -23,8 +23,8 @@
\class guhserver::Rule
\brief This class represents a rule.
\ingroup core
\inmodule server
\ingroup rules
\inmodule core
A Rule is always triggered by an \l{EventDescriptor}, has \l{State}{States}
to be compared and \l{RuleAction}{RuleActions} to be executed.

4
server/ruleengine.cpp
View File

@ -24,8 +24,8 @@
\brief The Engine that evaluates \l{Rule}{Rules} and finds
\l{Action}{Actions} to be executed.
\ingroup core
\inmodule server
\ingroup rules
\inmodule core
You can add, remove and update rules and query the engine for actions to be executed
for a given \l{Event} described by an \l{EventDescriptor}.

4
server/servermanager.cpp
View File

@ -22,8 +22,8 @@
\class guhserver::ServerManager
\brief This class represents the manager of all server interfaces of the guh server.
\ingroup core
\inmodule server
\ingroup server
\inmodule core
The \l{ServerManager} starts the \l{JsonRPCServer} and the \l{RestServer}. He also loads
and provides the SSL configurations for the secure \l{WebServer} and \l{WebSocketServer}

4
server/tcpserver.cpp
View File

@ -23,8 +23,8 @@
\class guhserver::TcpServer
\brief This class represents the tcp server for guhd.
\ingroup core
\inmodule server
\ingroup server
\inmodule core
\inherits TransportInterface

4
server/transportinterface.cpp
View File

@ -22,8 +22,8 @@
\class guhserver::TransportInterface
\brief This class provides an interface for the JSON servers.
\ingroup core
\inmodule server
\ingroup server
\inmodule core
\sa WebSocketServer, TcpServer
*/

4
server/webserver.cpp
View File

@ -22,8 +22,8 @@
\class guhserver::WebServer
\brief This class represents the web server for guhd.
\ingroup core
\inmodule server
\ingroup server
\inmodule core
The \l{WebServer} class provides a HTTP/1.1 web server. The web server
provides access to the guh-webinterface and the path can be specified

4
server/websocketserver.cpp
View File

@ -22,8 +22,8 @@
\class guhserver::WebSocketServer
\brief This class represents the websocket server for guhd.
\ingroup core
\inmodule server
\ingroup server
\inmodule core
\note The WebSocketServer is only available for builds with Qt version greater than Qt 5.3.0!