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

add CoAP documentation

Browse Source
This commit is contained in:
Simon Stürz 2015-11-24 14:41:28 +01:00 committed by Michael Zanetti
parent 1caab0efdc
commit 3023634a11
9 changed files with 377 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/coap.qdoc Normal file
View File

@ -0,0 +1,10 @@
/*!
\page coap-overview.html
\title CoAP
In order to interact with a CoAP (Constrained Application Protocol) server guh provides following classes:
\annotatedlist coap
*/

3
doc/guh.qdoc
View File

@ -17,8 +17,9 @@
\li \l{Types of libguh}
\li \l{Device Plugins}{The Device Plugin API}
\li \l{Hardware Resources}{Hardware resources available for plugins}
\li \l{GuhSettings}{Settings of guh}
\li \l{GuhSettings}{Settings API of guh}
\li \l{Type Utils}{Global types of guh (Type Utils)}
\li \l{CoAP}{The CoAP API}
\endlist
\li \l{Plugins}{The guh plugins}
\list

55
libguh/coap/coap.cpp
View File

@ -18,10 +18,55 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class Coap
\brief The client connection class to a CoAP server.
\ingroup coap
\inmodule libguh
The Coap class provides a signal solt based communication with a \l{https://tools.ietf.org/html/rfc7252}{CoAP (Constrained Application Protocol)}
server. The API of this class was inspired by the \l{http://doc.qt.io/qt-5/qnetworkaccessmanager.html}{QNetworkAccessManager} and was
written according to the \l{https://tools.ietf.org/html/rfc7252}{RFC7252}.
This class supports also blockwise transfere according to the \l{https://tools.ietf.org/html/draft-ietf-core-block-18}{IETF V18} specifications.
\sa CoapReply, CoapRequest
\section2 Example
\code
MyClass::MyClass(QObject *parent) :
QObject(parent)
{
Coap *coap = new Coap(this);
connect(coap, SIGNAL(replyFinished(CoapReply*)), this, SLOT(onReplyFinished(CoapReply*)));
CoapRequest request(QUrl("coap://coap.me/hello"));
coap->get(request);
}
\endcode
\code
void MyClass::onReplyFinished(CoapReply *reply)
{
if (reply->error() != CoapReply::NoError) {
qWarning() << "Reply finished with error" << reply->errorString();
}
qDebug() << "Reply finished" << reply;
reply->deleteLater();
}
\endcode
*/
/*! \fn void Coap::replyFinished(CoapReply *reply);
This signal is emitted when a \a reply is finished.
*/
#include "coap.h"
#include "coappdu.h"
#include "coapoption.h"
/*! Constructs a coap access manager with the given \a parent and \a port. */
Coap::Coap(QObject *parent, const quint16 &port) :
QObject(parent),
m_reply(0)
@ -34,6 +79,8 @@ Coap::Coap(QObject *parent, const quint16 &port) :
connect(m_socket, SIGNAL(readyRead()), this, SLOT(onReadyRead()));
}
/*! Performs a ping request to the CoAP server specified in the given \a request.
* Returns a \l{CoapReply} to match the response with the request. */
CoapReply *Coap::ping(const CoapRequest &request)
{
CoapReply *reply = new CoapReply(request, this);
@ -59,6 +106,8 @@ CoapReply *Coap::ping(const CoapRequest &request)
return reply;
}
/*! Performs a GET request to the CoAP server specified in the given \a request.
* Returns a \l{CoapReply} to match the response with the request. */
CoapReply *Coap::get(const CoapRequest &request)
{
CoapReply *reply = new CoapReply(request, this);
@ -84,6 +133,8 @@ CoapReply *Coap::get(const CoapRequest &request)
return reply;
}
/*! Performs a PUT request to the CoAP server specified in the given \a request and \a data.
* Returns a \l{CoapReply} to match the response with the request. */
CoapReply *Coap::put(const CoapRequest &request, const QByteArray &data)
{
CoapReply *reply = new CoapReply(request, this);
@ -110,6 +161,8 @@ CoapReply *Coap::put(const CoapRequest &request, const QByteArray &data)
return reply;
}
/*! Performs a POST request to the CoAP server specified in the given \a request and \a data.
* Returns a \l{CoapReply} to match the response with the request. */
CoapReply *Coap::post(const CoapRequest &request, const QByteArray &data)
{
CoapReply *reply = new CoapReply(request, this);
@ -136,6 +189,8 @@ CoapReply *Coap::post(const CoapRequest &request, const QByteArray &data)
return reply;
}
/*! Performs a DELETE request to the CoAP server specified in the given \a request.
* Returns a \l{CoapReply} to match the response with the request. */
CoapReply *Coap::deleteResource(const CoapRequest &request)
{
CoapReply *reply = new CoapReply(request, this);

57
libguh/coap/coapoption.cpp
View File

@ -18,35 +18,92 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class CoapOption
\brief Represents the option of a Coap PDU.
\ingroup coap
\inmodule libguh
The CoapOption class provides an easy way to create / parse CoAP options of a CoAP PDU (Protocol Data Unit). An options
can be compared with a HTTP header.
*/
/*! \enum CoapOption::Option
Represents the known CoAP options according to \l{https://tools.ietf.org/html/rfc7252#section-3.1}{RFC7252}.
\value IfMatch
\value UriHost
\value ETag
\value IfNoneMatch
\value UriPort
\value LocationPath
\value UriPath
\value ContentFormat
\value MaxAge
\value UriQuery
\value Accept
\value LocationQuery
\value Block2
\value Block1
\value ProxyUri
\value ProxyScheme
\value Size1
*/
#include "coapoption.h"
#include <QMetaEnum>
/*! Constructs a \l{CoapOption} . */
CoapOption::CoapOption()
{
}
/*! Constructs a \l{CoapOption} with the given \a option and option \a data. */
CoapOption::CoapOption(const CoapOption::Option &option, const QByteArray &data) :
m_option(option),
m_data(data)
{
}
/*! Sets the option value of this CoapOption to the given \a option . */
void CoapOption::setOption(const CoapOption::Option &option)
{
m_option = option;
}
/*! Returns the option value of this CoapOption. */
CoapOption::Option CoapOption::option() const
{
return m_option;
}
/*! Sets the data of this CoapOption to the given \a data. */
void CoapOption::setData(const QByteArray &data)
{
m_data = data;
}
/*! Returns the data of this CoapOption. */
QByteArray CoapOption::data() const
{
return m_data;

108
libguh/coap/coappdu.cpp
View File

@ -18,6 +18,114 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class CoapPdu
\brief Represents a CoAP protocol data unit (PDU).
\ingroup coap
\inmodule libguh
*/
/*! \enum CoapPdu::MessageType
\value Confirmable
\value NonConfirmable
\value Acknowledgement
\value Reset
*/
/*! \enum CoapPdu::StatusCode
The CoAP status codes.
Methods: \l{https://tools.ietf.org/html/rfc7252#section-5.8}
Status codes: \l{https://tools.ietf.org/html/rfc7252#section-12.1.2}
\value Empty
0.00 Empty (i.e. response to ping request)
\value Get
The GET method
\value Post
The POST method
\value Put
The PUT method
\value Delete
The DELETE method
\value Created
2.01 Created
\value Deleted
2.02 Deleted
\value Valid
2.03 Valid
\value Changed
2.04 Changed
\value Content
2.05 Content
\value Continue
2.31 Continue (from \l{https://tools.ietf.org/html/draft-ietf-core-block-18}{Blockwise V18})
\value BadRequest
4.00 Bad Request
\value Unauthorized
4.01 Unauthorized
\value BadOption
4.02 Bad Option
\value Forbidden
4.03 Forbidden
\value NotFound
4.04 Not Found
\value MethodNotAllowed
4.05 Method Not Allowed
\value NotAcceptable
4.06 Not Acceptable
\value RequestEntityIncomplete
4.08 Request Entity Incomplete (from \l{https://tools.ietf.org/html/draft-ietf-core-block-18}{Blockwise V18})
\value PreconditionFailed
4.12 Precondition Failed
\value RequestEntityTooLarge
4.13 Request Entity Too Large (from \l{https://tools.ietf.org/html/draft-ietf-core-block-18}{Blockwise V18})
\value UnsupportedContentFormat
4.15 UnsupportedContentFormat
\value InternalServerError
5.00 Internal Server Error
\value NotImplemented
5.01 Not Implemented
\value BadGateway
5.02 Bad Gateway
\value ServiceUnavailabl
5.03 Service Unavailabl
\value GatewayTimeout
5.04 Gateway Timeout
\value ProxyingNotSupported
5.05 Proxying Not Supported
*/
/*! \enum CoapPdu::ContentType
The CoAP content types.
\value TextPlain
\value ApplicationLink
\value ApplicationXml
\value ApplicationOctet
\value ApplicationExi
\value ApplicationJson
*/
/*! \enum CoapPdu::Error
\value NoError
\value InvalidTokenError
\value InvalidPduSizeError
\value InvalidOptionDeltaError
\value InvalidOptionLengthError
\value UnknownOptionError
};
*/
#include "coappdu.h"
#include "coapoption.h"

89
libguh/coap/coapreply.cpp
View File

@ -18,36 +18,125 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class CoapReply
\brief Represents a reply of a CoAP request.
\ingroup coap
\inmodule libguh
The CoapReply class contains the data and headers for a request sent with \l{Coap} client.
\note Please don't forget to delete the reply once it is finished.
\section2 Example
\code
Coap *coap = new Coap(this);
connect(coap, SIGNAL(replyFinished(CoapReply*)), this, SLOT(onReplyFinished(CoapReply*)));
CoapRequest request(QUrl("coap://example.com/"));
CoapReply *reply = coap->ping(request);
\endcode
\code
void MyClass::onReplyFinished(CoapReply *reply)
{
if (reply->error() != CoapReply::NoError) {
qWarning() << "Reply finished with error" << reply->errorString();
}
qDebug() << "Reply finished" << reply;
reply->deleteLater();
}
\endcode
\sa Coap, CoapRequest
*/
/*! \fn void CoapReply::timeout();
This signal is emitted when the reply took to long.
*/
/*! \fn void CoapReply::finished();
This signal is emitted when the reply is finished.
*/
/*! \fn void CoapReply::error(const Error &code);
This signal is emitted when an error occured.
\sa error(), errorString()
*/
/*! \enum CoapReply::Error
\value NoError
No error occured. Everything ok.
\value HostNotFoundError
The remote host name was not found (invalid hostname).
\value TimeoutError
The server did not respond after 4 retransmissions.
\value InvalidUrlSchemeError
The given URL does not have a valid scheme.
\value InvalidPduError
The package data unit (PDU) could not be parsed successfully.
*/
#include "coapreply.h"
#include "coappdu.h"
#include <QMetaEnum>
/*! Returns the request for this CoapReply. */
CoapRequest CoapReply::request() const
{
return m_request;
}
/*! Returns the payload of this CoapReply. The payload will be available once the CoapReply is finished.
\sa isFinished
*/
QByteArray CoapReply::payload() const
{
return m_payload;
}
/*! Returns true if the reply is finished.
\sa finished()
*/
bool CoapReply::isFinished() const
{
return m_isFinished;
}
/*! Returns true if the reply is running.
\sa finished()
*/
bool CoapReply::isRunning() const
{
return m_timer->isActive();
}
/*! Returns error code of the reply.
\sa errorString()
*/
CoapReply::Error CoapReply::error() const
{
return m_error;
}
/*! Returns error string of the reply.
\sa error()
*/
QString CoapReply::errorString() const
{
QString errorString;

18
libguh/coap/coaprequest.cpp
View File

@ -18,8 +18,18 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class CoapRequest
\brief Represents a request to a CoAP server.
\ingroup coap
\inmodule libguh
*/
#include "coaprequest.h"
/*! Constructs a CoAP request for the given \a url. */
CoapRequest::CoapRequest(const QUrl &url) :
m_url(url),
m_contentType(CoapPdu::TextPlain),
@ -28,31 +38,39 @@ CoapRequest::CoapRequest(const QUrl &url) :
{
}
/*! Sets the URL of this CoAP request to the given \a url. */
void CoapRequest::setUrl(const QUrl &url)
{
m_url = url;
}
/*! Returns the URL of this CoAP request. */
QUrl CoapRequest::url() const
{
return m_url;
}
/*! Sets the \l{CoapPdu::ContentType}{ContentType} of this CoAP request to the given \a contentType.
* This method will only be used with the PUT and POST method and should describe the content format
* of the payload. */
void CoapRequest::setContentType(const CoapPdu::ContentType contentType)
{
m_contentType = contentType;
}
/*! Returns the content format of the payload. */
CoapPdu::ContentType CoapRequest::contentType() const
{
return m_contentType;
}
/*! Sets the \l{CoapPdu::MessageType}{MessageType} of this CoAP request to the given \a messageType. */
void CoapRequest::setMessageType(const CoapPdu::MessageType &messageType)
{
m_messageType = messageType;
}
/*! Returns the message type of this CoapRequest. */
CoapPdu::MessageType CoapRequest::messageType() const
{
return m_messageType;

13
libguh/coap/corelink.cpp
View File

@ -18,6 +18,19 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class CoreLink
\brief Represents a link of a CoRE link format.
\ingroup coap
\inmodule libguh
This class represents a Constrained RESTful Environments (CoRE) Link format according to the
\l{http://tools.ietf.org/html/rfc6690}{RFC6690} specification.
*/
#include "corelink.h"
#include <QMetaEnum>

25
libguh/coap/corelinkparser.cpp
View File

@ -18,10 +18,34 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*!
\class CoreLinkParser
\brief Provides an easy way to parse a CoRE link list.
\ingroup coap
\inmodule libguh
\section2 Example
\code
if (reply->contentType == CoapPdu::ApplicationLink) {
CoreLinkParser parser(reply->payload());
foreach (const CoreLink &link, parser.links()) {
qDebug() << link;
}
}
\endcode
\sa CoreLink
*/
#include "corelinkparser.h"
#include <QDebug>
/*! Constructs a CoRE link parser. The given \a data should contain a CoRE link list. */
CoreLinkParser::CoreLinkParser(const QByteArray &data, QObject *parent) :
QObject(parent),
m_data(data)
@ -55,6 +79,7 @@ CoreLinkParser::CoreLinkParser(const QByteArray &data, QObject *parent) :
}
}
/*! Returns the parsed list of \l{CoreLink}{CoreLinks}.*/
QList<CoreLink> CoreLinkParser::links() const
{
return m_links;