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

add more documentation

Browse Source 
update readme
This commit is contained in:
Simon Stürz 2015-10-05 12:55:15 +02:00 committed by Michael Zanetti
parent eedb67fbb0
commit 88c5778103
16 changed files with 297 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@ -1,12 +1,28 @@
guh
# guh
--------------------------------------------
*guh* (/[guːh]/ - pronounced German and sounds like "*goo*") is an open source home automation server, which allows to control a lot of different devices from many different manufacturers. With the powerful rule engine you are able to connect any device available in the system and create individual scenes and behaviors for your home.
*guh* (/[guːh]/ - pronounced German and sounds like "*goo*") is an open source IoT (Internet of Things) server, which allows to control a lot of different devices from many different manufacturers. With the powerful rule engine you are able to connect any device available in the system and create individual scenes and behaviors for your environment.
In order to use *guh* and find information you can take a look at following links:
## Getting started
--------------------------------------------
In order to getting started with *guh* and find information you can take a look at following links:
* A detailed description how to install and getting started with the *guh* can be found in the [guh | github wiki](https://github.com/guh/guh/wiki).
* A detailed documentation of the source code can be found in the [guh | developer documentation](http://dev.guh.guru/).
* A detailed description how to install and getting started with the *guh* can be found in the
[guh | github wiki](https://github.com/guh/guh/wiki).
* A detailed documentation of the source code can be found in the
[guh | developer documentation](http://dev.guh.guru/).
## Donate
--------------------------------------------
Since guh is free and open source, we are grateful for any help!
[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=SNATFFJGNRUZ6)
## License
--------------------------------------------
> guh is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 of the License.
> Guh is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 of the License.
> Guh is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with guh. If not, see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).

8
doc/guh.qdoc
View File

@ -8,15 +8,17 @@
\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}
\li \l{Server classes}{The server classes}
\li \l{Logging classes}{The Log Engine classes}
\endlist
\li \l{libguh}{The guh library}
\list
\li \l{Types of libguh}{Types used in the guh system}
\li \l{Types of libguh}
\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}
\li \l{GuhSettings}{Settings of guh}
\li \l{Type Utils}{Global types of guh (Type Utils)}
\endlist
\li \l{Plugins}{The guh plugins}
\list

9
doc/logs.qdoc Normal file
View File

@ -0,0 +1,9 @@
/*!
\page logs.html
\title Logging classes
\annotatedlist logs
*/

2
doc/tutorial4.qdoc
View File

@ -42,7 +42,7 @@
As you can see, there is only one \tt bool \l State which has the property \e {"writable"}. This property indicates, that this \l State is writable and we need an \l Action for doing that. You can find more details about this property in \l {The StateType definition} documentation.
We learnend in the previouse tutorial that a \l State will allways generate an \l Event when he changes his \e {value}. This \l Event has the same UUID as the \l State which generated the \l Event. The same thing happens with the \l Action if you make a \l State writable. The devicemanager defines a new \l ActionType which has the same UUID as the \State which will be changed with the \l Action.
We learnend in the previouse tutorial that a \l State will allways generate an \l Event when he changes his \e {value}. This \l Event has the same UUID as the \l State which generated the \l Event. The same thing happens with the \l Action if you make a \l State writable. The devicemanager defines a new \l ActionType which has the same UUID as the \l State which will be changed with the \l Action.
\tt {\l{StateTypeId} == \l{EventTypeId} == \l{ActionTypeId}}

6
doc/typeutils.qdoc
View File

@ -147,11 +147,11 @@
\row
\li Types::UnitDegreeCelsius
\li 9
\li The value of the \l{Param} has unit \tt {[\unicode{0x00B0} C]} \unicode{0x2192} degree celsius.
\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.
\li The value of the \l{Param} has unit \tt {[\unicode{0x00B0}K]} \unicode{0x2192} kelvin.
\row
\li Types::UnitMired
\li 11
@ -223,7 +223,7 @@
\row
\li Types::UnitMegaByte
\li 28
\li The value of the \l{Param} has unit \tt {[mB]} \unicode{0x2192} mega byte.
\li The value of the \l{Param} has unit \tt {[MB]} \unicode{0x2192} mega byte.
\row
\li Types::UnitGigaByte
\li 29

52
libguh/guhsettings.cpp
View File

@ -18,6 +18,36 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class GuhSettings
\brief The settings class for guh.
\ingroup devices
\inmodule libguh
Depending on how the guh server was started (which user started guhd), the setting have to
be stored in different locations. This class represents a centralized mechanism to store
settings of the system. The different settings are represented ba the \l{SettingsRole} and
can be used everywhere in the project.
*/
/*! \enum GuhSettings::SettingsRole
Represents the role for the \l{GuhSettings}. Each role creates its own settings file.
\value SettingsRoleNone
No role will be used. This sould not be used!
\value SettingsRoleDevices
This role will create the \b{devices.conf} file and is used to store the configured \l{Device}{Devices}.
\value SettingsRoleRules
This role will create the \b{rules.conf} file and is used to store the configured \l{guhserver::Rule}{Rules}.
\value SettingsRolePlugins
This role will create the \b{plugins.conf} file and is used to store the \l{DevicePlugin}{Plugin} configurations.
\value SettingsRoleGlobal
This role will create the \b{guhd.conf} file and is used to store the global settings of the guh system. This settings
file is read only.
*/
#include "guhsettings.h"
#include "unistd.h"
@ -26,6 +56,7 @@
#include <QDir>
#include <QDebug>
/*! Constructs a \l{GuhSettings} instance with the given \a role and \a parent. */
GuhSettings::GuhSettings(const SettingsRole &role, QObject *parent):
QObject(parent),
m_role(role)
@ -96,17 +127,20 @@ GuhSettings::GuhSettings(const SettingsRole &role, QObject *parent):
}
}
/*! Destructor of the GuhSettings.*/
GuhSettings::~GuhSettings()
{
m_settings->sync();
delete m_settings;
}
/*! Returns the \l{SettingsRole} of this \l{GuhSettings}.*/
GuhSettings::SettingsRole GuhSettings::settingsRole() const
{
return m_role;
}
/*! Returns true if guhd is started as \b{root}.*/
bool GuhSettings::isRoot()
{
if (getuid() != 0)
@ -115,6 +149,10 @@ bool GuhSettings::isRoot()
return true;
}
/*! Returns the path where the logging database will be stored.
\sa guhserver::LogEngine
*/
QString GuhSettings::logPath()
{
QString logPath;
@ -131,67 +169,81 @@ QString GuhSettings::logPath()
return logPath;
}
/*! Return a list of all settings keys.*/
QStringList GuhSettings::allKeys() const
{
return m_settings->allKeys();
}
/*! Begins a new group with the given \a prefix.*/
void GuhSettings::beginGroup(const QString &prefix)
{
m_settings->beginGroup(prefix);
}
/*! Returns a list of all key top-level groups that contain keys that can be read
* using the \l{GuhSettings} object.*/
QStringList GuhSettings::childGroups() const
{
return m_settings->childGroups();
}
/*! Returns a list of all top-level keys that can be read using the \l{GuhSettings} object.*/
QStringList GuhSettings::childKeys() const
{
return m_settings->childKeys();
}
/*! Removes all entries in the primary location associated to this \l{GuhSettings} object.*/
void GuhSettings::clear()
{
m_settings->clear();
}
/*! Returns true if there exists a setting called \a key; returns false otherwise. */
bool GuhSettings::contains(const QString &key) const
{
return m_settings->contains(key);
}
/*! Resets the group to what it was before the corresponding beginGroup() call. */
void GuhSettings::endGroup()
{
m_settings->endGroup();
}
/*! Returns the current group. */
QString GuhSettings::group() const
{
return m_settings->group();
}
/*! Returns the path where settings written using this \l{GuhSettings} object are stored. */
QString GuhSettings::fileName() const
{
return m_settings->fileName();
}
/*! Returns true if settings can be written using this \l{GuhSettings} object; returns false otherwise. */
bool GuhSettings::isWritable() const
{
return m_settings->isWritable();
}
/*! Removes the setting key and any sub-settings of \a key. */
void GuhSettings::remove(const QString &key)
{
m_settings->remove(key);
}
/*! Sets the \a value of setting \a key to value. If the \a key already exists, the previous value is overwritten. */
void GuhSettings::setValue(const QString &key, const QVariant &value)
{
//Q_ASSERT_X(m_role != GuhSettings::SettingsRoleGlobal, "GuhSettings", "Bad settings usage. The global settings file should be read only.");
m_settings->setValue(key, value);
}
/*! Returns the value for setting \a key. If the setting doesn't exist, returns \a defaultValue. */
QVariant GuhSettings::value(const QString &key, const QVariant &defaultValue) const
{
return m_settings->value(key, defaultValue);

16
server/httpreply.cpp
View File

@ -111,6 +111,10 @@
This signal is emitted when this async \l{HttpReply} is finished.
*/
/*! \fn QDebug guhserver::operator<< (QDebug debug, const HttpReply &httpReply);
Writes the given \l{HttpReply} \a httpReply to the given \a debug. This method gets used just for debugging.
*/
#include "httpreply.h"
#include <QDateTime>
@ -168,7 +172,9 @@ HttpReply::HttpReply(const HttpReply::HttpStatusCode &statusCode, const HttpRepl
packReply();
}
/*! Set the \l{HttpStatusCode} \a statusCode for this \l{HttpReply}. */
/*! Set the \l{HttpStatusCode} of this \l{HttpReply} to the given \a statusCode.
\sa httpStatusCode()
*/
void HttpReply::setHttpStatusCode(const HttpReply::HttpStatusCode &statusCode)
{
m_statusCode = statusCode;
@ -259,11 +265,17 @@ QByteArray HttpReply::rawHeader() const
return m_rawHeader;
}
/*! Sets the \a close paramter of this \l{HttpReply}. If \a close is true,
the connection of the client will be closed after this reply was sent.
*/
void HttpReply::setCloseConnection(const bool &close)
{
m_closeConnection = close;
}
/*! Returns the connection close paramter of this \l{HttpReply}. If close is true, the connection
of the client will be closed after this reply was sent.
*/
bool HttpReply::closeConnection() const
{
return m_closeConnection;
@ -387,7 +399,7 @@ QByteArray HttpReply::getHeaderType(const HttpReply::HttpHeaderType &headerType)
/*! Starts the timer for an async \l{HttpReply}.
*
* \sa finished()
*/
*/
void HttpReply::startWait()
{
m_timer->start(10000);

13
server/jsonrpc/logginghandler.cpp
View File

@ -19,6 +19,19 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class guhserver::LoggingHandler
\brief This subclass of \l{JsonHandler} processes the JSON requests for the \tt Logging namespace of the JSON-RPC API.
\ingroup json
\inmodule core
This \l{JsonHandler} will be created in the \l{JsonRPCServer} and used to handle JSON-RPC requests
for the \tt {Logging} namespace of the API.
\sa LogEngine, JsonHandler, JsonRPCServer
*/
#include "logginghandler.h"
#include "logging/logengine.h"
#include "logging/logfilter.h"

14
server/jsonrpc/ruleshandler.cpp
View File

@ -19,8 +19,20 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
#include "ruleshandler.h"
/*!
\class guhserver::RulesHandler
\brief This subclass of \l{JsonHandler} processes the JSON requests for the \tt Rules namespace of the JSON-RPC API.
\ingroup json
\inmodule core
This \l{JsonHandler} will be created in the \l{JsonRPCServer} and used to handle JSON-RPC requests
for the \tt {Rules} namespace of the API.
\sa RuleEngine, JsonHandler, JsonRPCServer
*/
#include "ruleshandler.h"
#include "guhcore.h"
#include "ruleengine.h"
#include "loggingcategories.h"

13
server/jsonrpc/statehandler.cpp
View File

@ -19,6 +19,19 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class guhserver::StateHandler
\brief This subclass of \l{JsonHandler} processes the JSON requests for the \tt States namespace of the JSON-RPC API.
\ingroup json
\inmodule core
This \l{JsonHandler} will be created in the \l{JsonRPCServer} and used to handle JSON-RPC requests
for the \tt {States} namespace of the API.
\sa State, JsonHandler, JsonRPCServer
*/
#include "statehandler.h"
#include "guhcore.h"
#include "loggingcategories.h"

88
server/logging/logengine.cpp
View File

@ -19,6 +19,87 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class guhserver::LogEngine
\brief The engine which creates the log databse and provides access to it.
\ingroup logs
\inmodule core
The \l{LogEngine} creates a \l{https://sqlite.org/}{SQLite3} database to stores everything what's
happening in the system. The database can be accessed from the API's. To controll the size of the database the
limit of the databse are 8000 entries.
\sa LogEntry, LogFilter, LogsResource, LoggingHandler
*/
/*! \fn void guhserver::LogEngine::logEntryAdded(const LogEntry &logEntry);
This signal is emitted when an \a logEntry was added to the database.
\sa LogEntry
*/
/*! \fn void guhserver::LogEngine::logDatabaseUpdated();
This signal is emitted when the log database was updated. The log database
will be updated when a \l{LogEntry} was added or when a device was removed
and all corresponding \l{LogEntry}{LogEntries} were removed from the database.
*/
/*!
\class guhserver::Logging
\brief The logging class provides enums and flags for the LogEngine.
\ingroup logs
\inmodule core
\sa LogEngine, LogEntry, LogFilter
*/
/*! \enum guhserver::Logging::LoggingError
Represents the possible errors from the \l{LogEngine}.
\value LoggingErrorNoError
No error happened. Everything is fine.
\value LoggingErrorLogEntryNotFound
The requested \l{LogEntry} could not be found.
\value LoggingErrorInvalidFilterParameter
The given \l{LogFilter} contains an invalid paramter.
*/
/*! \enum guhserver::Logging::LoggingEventType
Represents the event type of this \l{LogEntry}.
\value LoggingEventTypeTrigger
This event type describes an \l{Event} which has triggered.
\value LoggingEventTypeActiveChange
This event type describes an \l{Rule} which has changed its active status.
*/
/*! \enum guhserver::Logging::LoggingLevel
Indicates if the corresponding \l{LogEntry} is an information or an alert.
\value LoggingLevelInfo
This \l{LogEntry} represents an information.
\value LoggingLevelAlert
This \l{LogEntry} represents an alert. Something is not ok.
*/
/*! \enum guhserver::Logging::LoggingSource
Indicates from where the \l{LogEntry} was created. Can be used as flag.
\value LoggingSourceSystem
This \l{LogEntry} was created from the guh system (server).
\value LoggingSourceEvents
This \l{LogEntry} was created from an \l{Event} which trigged.
\value LoggingSourceActions
This \l{LogEntry} was created from an \l{Action} which was executed.
\value LoggingSourceStates
This \l{LogEntry} was created from an \l{State} which hase changed.
\value LoggingSourceRules
This \l{LogEntry} was created from an \l{Rule} which hase changed the active state or triggered.
*/
#include "guhsettings.h"
#include "logengine.h"
#include "loggingcategories.h"
@ -33,10 +114,11 @@
#include <QDateTime>
#define DB_SCHEMA_VERSION 2
#define DB_MAX_SIZE 3000
#define DB_MAX_SIZE 8000
namespace guhserver {
/*! Constructs the log engine with the given \a parent. */
LogEngine::LogEngine(QObject *parent):
QObject(parent)
{
@ -58,6 +140,10 @@ LogEngine::LogEngine(QObject *parent):
initDB();
}
/*! Returns the list of \l{LogEntry}{LogEntries} of the database matching the given \a filter.
\sa LogEntry, LogFilter
*/
QList<LogEntry> LogEngine::logEntries(const LogFilter &filter) const
{
qCDebug(dcLogEngine) << "Read logging database" << m_db.databaseName();

13
server/logging/logentry.cpp
View File

@ -19,6 +19,19 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class guhserver::LogEntry
\brief Represents an entry of the log database.
\ingroup logs
\inmodule core
A \l{LogEntry} represents an a guh event which can be stored from the \l{LogEngine} to the database.
Each LogEntry has a timestamp an can be loaded from the database and stored in the database.
\sa LogEngine, LogFilter, LogsResource, LoggingHandler
*/
/*! \fn QDebug guhserver::operator<< (QDebug dbg, const LogEntry &entry);;
Writes the \l{LogEntry} \a entry to the given \a dbg. This method gets used just for debugging.
*/

13
server/logging/logfilter.cpp
View File

@ -18,6 +18,19 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class guhserver::LogFilter
\brief Represents a filter to access the logging databse.
\ingroup logs
\inmodule core
A \l{LogFilter} can be used to get \l{LogEntry}{LogEntries} from the \l{LogEngine} matching
a certain pattern.
\sa LogEngine, LogEntry, LogsResource, LoggingHandler
*/
#include "logfilter.h"
#include "loggingcategories.h"

5
server/rest/restresource.cpp
View File

@ -87,6 +87,7 @@ HttpReply *RestResource::createSuccessReply()
return reply;
}
/*! Returns the pointer to a new created \l{HttpReply} which represents a response to a CORS request. */
HttpReply *RestResource::createCorsSuccessReply()
{
HttpReply *reply = RestResource::createSuccessReply();
@ -117,6 +118,8 @@ HttpReply *RestResource::createDeviceErrorReply(const HttpReply::HttpStatusCode
return reply;
}
/*! Returns the pointer to a new created \l{HttpReply} with the given \a statusCode and \a ruleError. This method will
* be used to create an error response for the \l{guhserver::RulesResource}{RulesResource}. The \a ruleError will be written in the payload of this reply.*/
HttpReply *RestResource::createRuleErrorReply(const HttpReply::HttpStatusCode &statusCode, const RuleEngine::RuleError &ruleError)
{
HttpReply *reply = new HttpReply(statusCode, HttpReply::TypeSync);
@ -127,6 +130,8 @@ HttpReply *RestResource::createRuleErrorReply(const HttpReply::HttpStatusCode &s
return reply;
}
/*! Returns the pointer to a new created \l{HttpReply} with the given \a statusCode and \a loggingError. This method will
* be used to create an error response for the \l{guhserver::LogsResource}{LogsResource}. The \a loggingError will be written in the payload of this reply.*/
HttpReply *RestResource::createLoggingErrorReply(const HttpReply::HttpStatusCode &statusCode, const Logging::LoggingError &loggingError)
{
HttpReply *reply = new HttpReply(statusCode, HttpReply::TypeSync);

3
server/ruleengine.cpp
View File

@ -21,8 +21,7 @@
/*!
\class guhserver::RuleEngine
\brief The Engine that evaluates \l{Rule}{Rules} and finds
\l{Action}{Actions} to be executed.
\brief The Engine that evaluates \l{Rule}{Rules} and finds \l{Action}{Actions} to be executed.
\ingroup rules
\inmodule core

33
server/webserver.cpp
View File

@ -49,7 +49,7 @@
\note For \tt HTTPS you need to have a certificate and configure it in the \tt SSL-configuration
section of the \tt /etc/guh/guhd.conf file.
\sa WebSocketServer, TcpServer
\sa WebServerClient, WebSocketServer, TcpServer
*/
/*! \fn void guhserver::WebServer::httpRequestReady(const QUuid &clientId, const HttpRequest &httpRequest);
@ -148,11 +148,14 @@ void WebServer::sendHttpReply(HttpReply *reply)
socket->write(reply->data());
}
/*! Returns the port on which the webserver is listening. */
int WebServer::port() const
{
return m_port;
}
/*! Returns the list of addresses on which the webserver is listening. */
QList<QHostAddress> WebServer::serverAddressList()
{
QList<QHostAddress> addresses;
@ -681,22 +684,46 @@ QByteArray WebServer::createServerXmlDocument(QHostAddress address)
}
/*!
\class guhserver::WebServerClient
\brief This class represents a client the web server for guhd.
\ingroup server
\inmodule core
The \l{WebServerClient} represents a client for the guh \l{WebServer}. Each client can
have up to 50 connections and each connection will timeout after 12 seconds if the
connection will not be used.
If all connections of a \l{WebServerClient} are closed, the client will be removed from
system.
\sa WebServer
*/
/*! Constructs a \l{WebServerClient} with the given \a address and \a parent. */
WebServerClient::WebServerClient(const QHostAddress &address, QObject *parent):
QObject(parent),
m_address(address)
{
}
/*! Returns the address of this \l{WebServerClient}. */
QHostAddress WebServerClient::address() const
{
return m_address;
}
/*! Returns the list of connections (sockets) of this \l{WebServerClient}. */
QList<QSslSocket *> WebServerClient::connections()
{
return m_connections;
}
/*! Adds a new connection (\a socket) to this \l{WebServerClient}. A \l{WebServerClient}
* can have up to 50 connecections. The connection will timout and closed if the client
* does not use the connection for 12 seconds.
*/
void WebServerClient::addConnection(QSslSocket *socket)
{
QTimer *timer = new QTimer(this);
@ -710,6 +737,7 @@ void WebServerClient::addConnection(QSslSocket *socket)
timer->start();
}
/*! Removes a connection the given \a socket from the connection list of this \l{WebServerClient}. */
void WebServerClient::removeConnection(QSslSocket *socket)
{
QTimer *timer = m_runningConnections.key(socket);
@ -719,6 +747,9 @@ void WebServerClient::removeConnection(QSslSocket *socket)
timer->deleteLater();
}
/*! Resets the connection timeout for the given \a socket. If the socket will not be used for 12 seconds the
* connection will be closed.
*/
void WebServerClient::resetTimout(QSslSocket *socket)
{
QTimer *timer = 0;