From 610fc77ded266a0298f4251e88ac80c9a45670b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Sat, 8 Aug 2015 18:10:32 +0200 Subject: [PATCH] add typeutils documentation --- doc/allmodules.qdoc | 4 +- doc/config.qdocconf | 19 ++ doc/getting-started-plugins.qdoc | 8 +- doc/guh.qdoc | 16 +- doc/guhcore.qdoc | 7 - doc/guhserver.qdoc | 6 +- doc/html-template.qdocconf | 5 +- doc/libguh.qdoc | 9 +- doc/plugin-json.qdoc | 163 ++++++++++------- doc/server-classes.qdoc | 7 + doc/style.css | 16 +- doc/tutorial2.qdoc | 7 + doc/types.qdoc | 6 +- doc/typeutils.qdoc | 305 +++++++++++++++++++++++++++++++ doc/write-plugins.qdoc | 11 +- libguh/libguh.pro | 1 - libguh/plugin/deviceplugin.cpp | 15 +- libguh/types/action.cpp | 2 +- libguh/types/actiontype.cpp | 2 +- libguh/types/event.cpp | 2 +- libguh/types/eventdescriptor.cpp | 2 +- libguh/types/eventtype.cpp | 2 +- libguh/types/param.cpp | 2 +- libguh/types/paramdescriptor.cpp | 2 +- libguh/types/paramtype.cpp | 2 +- libguh/types/ruleaction.cpp | 2 +- libguh/types/ruleactionparam.cpp | 2 +- libguh/types/state.cpp | 2 +- libguh/types/statedescriptor.cpp | 2 +- libguh/types/statetype.cpp | 2 +- libguh/types/vendor.cpp | 2 +- libguh/typeutils.h | 2 + server/guhcore.cpp | 3 +- server/httpreply.cpp | 4 +- server/httprequest.cpp | 4 +- server/jsonrpc/jsonrpcserver.cpp | 22 ++- server/jsonrpc/jsonrpcserver.h | 3 - server/rest/restresource.cpp | 49 +++++ server/rest/restserver.cpp | 17 ++ server/rule.cpp | 4 +- server/ruleengine.cpp | 4 +- server/servermanager.cpp | 4 +- server/tcpserver.cpp | 4 +- server/transportinterface.cpp | 4 +- server/webserver.cpp | 4 +- server/websocketserver.cpp | 4 +- 46 files changed, 613 insertions(+), 152 deletions(-) delete mode 100644 doc/guhcore.qdoc create mode 100644 doc/server-classes.qdoc create mode 100644 doc/tutorial2.qdoc create mode 100644 doc/typeutils.qdoc diff --git a/doc/allmodules.qdoc b/doc/allmodules.qdoc index f1138a13..0383a195 100644 --- a/doc/allmodules.qdoc +++ b/doc/allmodules.qdoc @@ -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 */ diff --git a/doc/config.qdocconf b/doc/config.qdocconf index b2b694b5..a6a48592 100644 --- a/doc/config.qdocconf +++ b/doc/config.qdocconf @@ -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" + diff --git a/doc/getting-started-plugins.qdoc b/doc/getting-started-plugins.qdoc index 5143fea2..3e79f73e 100644 --- a/doc/getting-started-plugins.qdoc +++ b/doc/getting-started-plugins.qdoc @@ -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} + \tt {guh_deviceplugin\b} 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{}.json} + \tt {deviceplugin\b{}.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.h} + \tt {deviceplugin\b.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.cpp} + \tt {deviceplugin\b.cpp} \code #include "devicepluginminimal.h" diff --git a/doc/guh.qdoc b/doc/guh.qdoc index 430a2d71..3be2b66c 100644 --- a/doc/guh.qdoc +++ b/doc/guh.qdoc @@ -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 */ diff --git a/doc/guhcore.qdoc b/doc/guhcore.qdoc deleted file mode 100644 index a1f12fd4..00000000 --- a/doc/guhcore.qdoc +++ /dev/null @@ -1,7 +0,0 @@ -/*! - \page guhcore-index.html - \title guh Core - - \annotatedlist server -*/ - diff --git a/doc/guhserver.qdoc b/doc/guhserver.qdoc index 6ce2299c..dbd3d2b5 100644 --- a/doc/guhserver.qdoc +++ b/doc/guhserver.qdoc @@ -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. */ - - diff --git a/doc/html-template.qdocconf b/doc/html-template.qdocconf index b3ccb3a5..670fa0a6 100644 --- a/doc/html-template.qdocconf +++ b/doc/html-template.qdocconf @@ -8,8 +8,9 @@ HTML.postheader = \ "
\n" \ " \n" \ "
\n" \ diff --git a/doc/libguh.qdoc b/doc/libguh.qdoc index 019b6831..de4cec18 100644 --- a/doc/libguh.qdoc +++ b/doc/libguh.qdoc @@ -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 + */ diff --git a/doc/plugin-json.qdoc b/doc/plugin-json.qdoc index af31a5ef..c9408fce 100644 --- a/doc/plugin-json.qdoc +++ b/doc/plugin-json.qdoc @@ -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{}.json} + \tt{deviceplugin\b{}.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 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 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 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 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 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 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 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 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 " 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 " 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 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 ". 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 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 ". 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 ". +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 ". 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 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 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 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 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 */ diff --git a/doc/server-classes.qdoc b/doc/server-classes.qdoc new file mode 100644 index 00000000..9c45541a --- /dev/null +++ b/doc/server-classes.qdoc @@ -0,0 +1,7 @@ +/*! + \page server-classes.html + \title Server classes + + \annotatedlist server +*/ + diff --git a/doc/style.css b/doc/style.css index 694cc049..09e420f9 100644 --- a/doc/style.css +++ b/doc/style.css @@ -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 { diff --git a/doc/tutorial2.qdoc b/doc/tutorial2.qdoc new file mode 100644 index 00000000..623259ec --- /dev/null +++ b/doc/tutorial2.qdoc @@ -0,0 +1,7 @@ +/*! + \page tutorial2.html + \title Tutorial 2 + +*/ + + diff --git a/doc/types.qdoc b/doc/types.qdoc index f1ff8f2d..05c38cc7 100644 --- a/doc/types.qdoc +++ b/doc/types.qdoc @@ -1,6 +1,6 @@ /*! - \page types.html - \title Types + \page libguh-types.html + \title Types of libguh - \annotatedlist types + \annotatedlist guh-types */ diff --git a/doc/typeutils.qdoc b/doc/typeutils.qdoc new file mode 100644 index 00000000..21ff3604 --- /dev/null +++ b/doc/typeutils.qdoc @@ -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. + +*/ + diff --git a/doc/write-plugins.qdoc b/doc/write-plugins.qdoc index c48c3d45..cfcc7ef1 100644 --- a/doc/write-plugins.qdoc +++ b/doc/write-plugins.qdoc @@ -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 diff --git a/libguh/libguh.pro b/libguh/libguh.pro index 7ee2155a..44a12cc7 100644 --- a/libguh/libguh.pro +++ b/libguh/libguh.pro @@ -40,7 +40,6 @@ SOURCES += plugin/device.cpp \ loggingcategories.cpp \ guhsettings.cpp \ - HEADERS += plugin/device.h \ plugin/deviceclass.h \ plugin/deviceplugin.h \ diff --git a/libguh/plugin/deviceplugin.cpp b/libguh/plugin/deviceplugin.cpp index 3d1f1669..d5843bf5 100644 --- a/libguh/plugin/deviceplugin.cpp +++ b/libguh/plugin/deviceplugin.cpp @@ -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 ¬ifyData) 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() */ diff --git a/libguh/types/action.cpp b/libguh/types/action.cpp index 73ba1f21..73580926 100644 --- a/libguh/types/action.cpp +++ b/libguh/types/action.cpp @@ -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 diff --git a/libguh/types/actiontype.cpp b/libguh/types/actiontype.cpp index f066388f..a652b3f1 100644 --- a/libguh/types/actiontype.cpp +++ b/libguh/types/actiontype.cpp @@ -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 diff --git a/libguh/types/event.cpp b/libguh/types/event.cpp index c0b74bab..060b6517 100644 --- a/libguh/types/event.cpp +++ b/libguh/types/event.cpp @@ -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 diff --git a/libguh/types/eventdescriptor.cpp b/libguh/types/eventdescriptor.cpp index d0f34108..b87b66de 100644 --- a/libguh/types/eventdescriptor.cpp +++ b/libguh/types/eventdescriptor.cpp @@ -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}. diff --git a/libguh/types/eventtype.cpp b/libguh/types/eventtype.cpp index def4f5df..6b0e11ec 100644 --- a/libguh/types/eventtype.cpp +++ b/libguh/types/eventtype.cpp @@ -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 diff --git a/libguh/types/param.cpp b/libguh/types/param.cpp index 2bfbe9b8..3d781397 100644 --- a/libguh/types/param.cpp +++ b/libguh/types/param.cpp @@ -23,7 +23,7 @@ \class Param \brief Holds the parameters of a Param. - \ingroup types + \ingroup guh-types \inmodule libguh \sa Device, ParamType, ParamDescriptor diff --git a/libguh/types/paramdescriptor.cpp b/libguh/types/paramdescriptor.cpp index 5f2bc288..a204d354 100644 --- a/libguh/types/paramdescriptor.cpp +++ b/libguh/types/paramdescriptor.cpp @@ -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}. diff --git a/libguh/types/paramtype.cpp b/libguh/types/paramtype.cpp index 89ae8e13..0515d56c 100644 --- a/libguh/types/paramtype.cpp +++ b/libguh/types/paramtype.cpp @@ -23,7 +23,7 @@ \class ParamType \brief Describes a certain ParamType. - \ingroup types + \ingroup guh-types \inmodule libguh \sa Device, Param, ParamDescriptor diff --git a/libguh/types/ruleaction.cpp b/libguh/types/ruleaction.cpp index 2e031e48..4daf7bac 100644 --- a/libguh/types/ruleaction.cpp +++ b/libguh/types/ruleaction.cpp @@ -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 diff --git a/libguh/types/ruleactionparam.cpp b/libguh/types/ruleactionparam.cpp index 633357ed..1fbc4c20 100644 --- a/libguh/types/ruleactionparam.cpp +++ b/libguh/types/ruleactionparam.cpp @@ -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 diff --git a/libguh/types/state.cpp b/libguh/types/state.cpp index 2f0330d7..f75a68d5 100644 --- a/libguh/types/state.cpp +++ b/libguh/types/state.cpp @@ -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 diff --git a/libguh/types/statedescriptor.cpp b/libguh/types/statedescriptor.cpp index 62631c8a..a9d95569 100644 --- a/libguh/types/statedescriptor.cpp +++ b/libguh/types/statedescriptor.cpp @@ -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}. diff --git a/libguh/types/statetype.cpp b/libguh/types/statetype.cpp index 080d7270..0c9a808d 100644 --- a/libguh/types/statetype.cpp +++ b/libguh/types/statetype.cpp @@ -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 diff --git a/libguh/types/vendor.cpp b/libguh/types/vendor.cpp index f88ce957..f134c18c 100644 --- a/libguh/types/vendor.cpp +++ b/libguh/types/vendor.cpp @@ -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 diff --git a/libguh/typeutils.h b/libguh/typeutils.h index 0a874b0f..fdfc55f8 100644 --- a/libguh/typeutils.h +++ b/libguh/typeutils.h @@ -130,6 +130,8 @@ public: StateOperatorAnd, StateOperatorOr }; + + Types(QObject *parent = 0); }; Q_DECLARE_METATYPE(Types::ValueOperator) diff --git a/server/guhcore.cpp b/server/guhcore.cpp index eb370fac..dfb8895c 100644 --- a/server/guhcore.cpp +++ b/server/guhcore.cpp @@ -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. diff --git a/server/httpreply.cpp b/server/httpreply.cpp index 75157b2c..f431dca7 100644 --- a/server/httpreply.cpp +++ b/server/httpreply.cpp @@ -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}. diff --git a/server/httprequest.cpp b/server/httprequest.cpp index 03de030a..af678987 100644 --- a/server/httprequest.cpp +++ b/server/httprequest.cpp @@ -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}. diff --git a/server/jsonrpc/jsonrpcserver.cpp b/server/jsonrpc/jsonrpcserver.cpp index 08bc437a..44089e38 100644 --- a/server/jsonrpc/jsonrpcserver.cpp +++ b/server/jsonrpc/jsonrpcserver.cpp @@ -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 ¶ms) return createReply(returns); } +/*! Returns the list of registred \l{JsonHandler}{JsonHandlers} and their name.*/ QHash 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 validationResult = handler->validateParams(method, params); if (!validationResult.first) { diff --git a/server/jsonrpc/jsonrpcserver.h b/server/jsonrpc/jsonrpcserver.h index 1db55866..6cec9460 100644 --- a/server/jsonrpc/jsonrpcserver.h +++ b/server/jsonrpc/jsonrpcserver.h @@ -65,9 +65,6 @@ public: QHash handlers() const; -signals: - void commandReceived(const QString &targetNamespace, const QString &command, const QVariantMap ¶ms); - private slots: void setup(); diff --git a/server/rest/restresource.cpp b/server/rest/restresource.cpp index a61ded20..b9fe1b6b 100644 --- a/server/rest/restresource.cpp +++ b/server/rest/restresource.cpp @@ -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/ + \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 RestResource::verifyPayload(const QByteArray &payload) { QVariant data; diff --git a/server/rest/restserver.cpp b/server/rest/restserver.cpp index 819d54d9..fe7e4fd6 100644 --- a/server/rest/restserver.cpp +++ b/server/rest/restserver.cpp @@ -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) { diff --git a/server/rule.cpp b/server/rule.cpp index 26cbda22..901ef7bf 100644 --- a/server/rule.cpp +++ b/server/rule.cpp @@ -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. diff --git a/server/ruleengine.cpp b/server/ruleengine.cpp index d3063554..44b597c6 100644 --- a/server/ruleengine.cpp +++ b/server/ruleengine.cpp @@ -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}. diff --git a/server/servermanager.cpp b/server/servermanager.cpp index 7863e513..316d1efa 100644 --- a/server/servermanager.cpp +++ b/server/servermanager.cpp @@ -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} diff --git a/server/tcpserver.cpp b/server/tcpserver.cpp index 5cd62673..07e3dfab 100644 --- a/server/tcpserver.cpp +++ b/server/tcpserver.cpp @@ -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 diff --git a/server/transportinterface.cpp b/server/transportinterface.cpp index 6a6c5fc8..7e223ed1 100644 --- a/server/transportinterface.cpp +++ b/server/transportinterface.cpp @@ -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 */ diff --git a/server/webserver.cpp b/server/webserver.cpp index e9ca8336..0144a57c 100644 --- a/server/webserver.cpp +++ b/server/webserver.cpp @@ -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 diff --git a/server/websocketserver.cpp b/server/websocketserver.cpp index 93ac47da..0d8ec35d 100644 --- a/server/websocketserver.cpp +++ b/server/websocketserver.cpp @@ -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!