A class to handle replies for JSON requests. More...

#include <restreply.h>

Inheritance diagram for QtRestClient::RestReply:

Public Types
enum	Error { Error::Network, Error::Parser, Error::Failure, Error::Deserialization }
	Defines the different possible error types. More...

using	DataType = std::variant< std::nullopt_t, QCborValue, QJsonValue >
	Internal datatype that unites JSON and CBOR data in a typesafe union.

Public Slots
void	abort ()
	Aborts the request by calling QNetworkReply::abort.

void	retry ()
	Tries to make the same request again, and reuses this rest reply. More...

void	retryAfter (std::chrono::milliseconds mSecs)
	Tries to make the same request again after a delay, and reuses this rest reply. More...

void	setAutoDelete (bool autoDelete)
	WRITE accessor for RestReply::autoDelete.

void	setAllowEmptyReplies (bool allowEmptyReplies)
	WRITE accessor for RestReply::allowEmptyReplies.

void	setAsync (bool async)
	WRITE accessor for RestReply::async.

Signals
void	completed (int httpStatus, const DataType &reply, QPrivateSignal)
	Is emitted when the request completed, i.e. succeeded or failed.

void	succeeded (int httpStatus, const DataType &reply, QPrivateSignal)
	Is emitted when the request succeeded.

void	failed (int httpStatus, const DataType &reason, QPrivateSignal)
	Is emitted when the request failed.

void	error (const QString &errorString, int error, Error errorType, QPrivateSignal)
	Is emitted when a network or json parse error occured.

void	networkError (QNetworkReply::NetworkError error)
	Forwards QNetworkReply::error(QNetworkReply::NetworkError)

void	sslErrors (const QList< QSslError > &errors, bool &ignoreErrors)
	Forwards QNetworkReply::sslErrors.

void	downloadProgress (qint64 bytesReceived, qint64 bytesTotal)
	Forwards QNetworkReply::downloadProgress.

void	uploadProgress (qint64 bytesSent, qint64 bytesTotal)
	Forwards QNetworkReply::uploadProgress.

void	autoDeleteChanged (bool autoDelete, QPrivateSignal)
	NOTIFY accessor for RestReply::autoDelete.

void	allowEmptyRepliesChanged (bool allowEmptyReplies, QPrivateSignal)
	NOTIFY accessor for RestReply::allowEmptyReplies.

void	asyncChanged (bool async, QPrivateSignal)
	NOTIFY accessor for RestReply::async.

Public Member Functions
	RestReply (QNetworkReply networkReply, QObject parent=nullptr)
	Creates a new reply based on a network reply.

	RestReply (const QFuture< QNetworkReply * > &networkReplyFuture, QObject *parent=nullptr)
	Creates a new reply based on a future network reply.

	RestReply (QNetworkReply networkReply, QThreadPool asyncPool, QObject *parent=nullptr)
	Creates a new reply based on a network reply and a threadpool.

	RestReply (const QFuture< QNetworkReply * > &networkReplyFuture, QThreadPool asyncPool, QObject parent=nullptr)
	Creates a new reply based on a future network reply and a threadpool.

template<typename TFn >
RestReply *	onSucceeded (TFn &&handler)
	Set a handler to be called if the request succeeded. More...

template<typename TFn >
RestReply *	onSucceeded (QObject *scope, TFn &&handler)
	Set a handler to be called if the request succeeded. More...

template<typename TFn >
RestReply *	onFailed (TFn &&handler)
	Set a handler to be called if the request failed. More...

template<typename TFn >
RestReply *	onFailed (QObject *scope, TFn &&handler)
	Set a handler to be called if the request failed. More...

template<typename TFn >
RestReply *	onCompleted (TFn &&handler)
	Set a handler to be called when the request was completed, regardless of success or failure. More...

template<typename TFn >
RestReply *	onCompleted (QObject *scope, TFn &&handler)
	Set a handler to be called when the request was completed, regardless of success or failure. More...

RestReply *	onError (std::function< void(QString, int, Error)> handler)
	Set a handler to be called if a network error or json parse error occures. More...

RestReply *	onError (QObject *scope, std::function< void(QString, int, Error)> handler)
	Set a handler to be called if a network error or json parse error occures. More...

template<typename TFn >
RestReply *	onAllErrors (const std::function< void(QString, int, Error)> &handler, TFn &&failureTransformer)
	Set a handler to be called if the request did not succeed. More...

template<typename TFn >
RestReply *	onAllErrors (QObject *scope, const std::function< void(QString, int, Error)> &handler, TFn &&failureTransformer)
	Set a handler to be called if the request did not succeed. More...

Q_INVOKABLE RestReply *	makeAsync (QThreadPool *threadPool=QThreadPool::globalInstance())
	WRITE accessor for RestReply::async.

Q_INVOKABLE RestReply *	disableAutoDelete ()
	WRITE accessor for RestReply::autoDelete.

bool	autoDelete () const
	READ accessor for RestReply::autoDelete.

bool	allowsEmptyReplies () const
	READ accessor for RestReply::allowEmptyReplies.

bool	isAsync () const
	READ accessor for RestReply::async.

Q_INVOKABLE QNetworkReply *	networkReply () const
	Returns the network reply associated with the rest reply.

RestReplyAwaitable	awaitable ()
	Returns an awaitable object for this reply.

Public Member Functions inherited from QObject
virtual const QMetaObject *	metaObject () const const

	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const const

void	setObjectName (const QString &name)

bool	isWidgetType () const const

bool	isWindowType () const const

bool	signalsBlocked () const const

bool	blockSignals (bool block)

QThread *	thread () const const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

const QObjectList &	children () const const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectTree ()

void	dumpObjectInfo ()

void	dumpObjectTree () const const

void	dumpObjectInfo () const const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const const

QList< QByteArray >	dynamicPropertyNames () const const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

bool	inherits (const char *className) const const

void	deleteLater ()

	Q_DISABLE_COPY (Class)

	Q_DISABLE_MOVE (Class)

	Q_DISABLE_COPY_MOVE (Class)

T	qobject_cast (QObject *object)

T	qobject_cast (const QObject *object)

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

	Q_CLASSINFO (Name, Value)

	Q_INTERFACES (...)

	Q_PROPERTY (...)

	Q_ENUMS (...)

	Q_FLAGS (...)

	Q_ENUM (...)

	Q_FLAG (...)

	Q_ENUM_NS (...)

	Q_FLAG_NS (...)

	Q_OBJECT Q_OBJECT

	Q_GADGET Q_GADGET

	Q_NAMESPACE Q_NAMESPACE

	Q_SIGNALS Q_SIGNALS

	Q_SIGNAL Q_SIGNAL

	Q_SLOTS Q_SLOTS

	Q_SLOT Q_SLOT

	Q_EMIT Q_EMIT

	Q_INVOKABLE Q_INVOKABLE

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

Properties
bool	autoDelete
	Speciefies, whether the reply should be automatically deleted. More...

bool	allowEmptyReplies
	Speciefies, whether empty rest replies are allowed. More...

bool	async
	Specifies, whether the reply should be handled on a threadpool or not. More...

Properties inherited from QObject
	objectName

Additional Inherited Members
Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Public Attributes inherited from QObject
typedef	QObjectList

Protected Member Functions inherited from QObject
QObject *	sender () const const

int	senderSignalIndex () const const

int	receivers (const char *signal) const const

bool	isSignalConnected (const QMetaMethod &signal) const const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Detailed Description

A class to handle replies for JSON requests.

This class is used as base class for kinds of replies. Extending classes simply wrap it's functionality.

Definition of "Failure"

When using the replies, you will see a FailureError and onFailure methods. THose are not network errors or json errors. A failure means that the server sent a valid reply, but with a HTTP-Statuscode, that is not positive (2XX), the result is treated as a failure. In most cases, those are 4XX errors, like 400 or 404. In some cases, the servers still send some kind of JSON as a reply. Those can be retrieved as "error objects"

See also: GenericRestReply, RestClass

Definition at line 23 of file restreply.h.

Member Enumeration Documentation

◆ Error

enum QtRestClient::RestReply::Error

strong

Defines the different possible error types.

Enumerator
Network	Indicates a network error, i.e. no internet.
Parser	Indicates that parsing the received JSON or CBOR data failed.
Failure	Indicates that the server sent a failure for the request.
Deserialization	Indicates that deserializing the received data to the target object failed. Generic replies only!

Definition at line 45 of file restreply.h.

Member Function Documentation

◆ onAllErrors() [1/2]

template<typename TFn >

QtRestClient::RestReply::onAllErrors	(	const std::function< void(QString, int, Error)> &	handler,
		TFn &&	failureTransformer
	)

Set a handler to be called if the request did not succeed.

Parameters

handler	The function to be called on any error
failureTransformer	(optional) A function to be called to extract an error string from the failure JSON

Returns: A reference to this reply

The handlers arguments are:

The error string (QString)
- For network error: QNetworkReply::errorString
- For json error: QJsonParseError::errorString
- For failure error: failureTransformer
The error code (int)
- For network error: QNetworkReply::error
- For json error: QJsonParseError::error
- For failure error: The HTTP-Status code
The error type (RestReply::Error, either RestReply::Error::NetworkError, RestReply::Error::ParseError or RestReply::Error::FailureError)

The failureTransformer can have the following signature:

(<data>, int): QString (HTTP reply body, HTTP status code)

The <data> part can be any of the following:

<jdata>
<cdata>
std::variant<std::nullopt_t, <cdata>, <jdata>>
std::variant<<cdata>, <jdata>>

See also: RestReply::onError, RestReply::onFailed, GenericRestReply::onAllErrors

Definition at line 242 of file restreply.h.

◆ onAllErrors() [2/2]

template<typename TFn >

QtRestClient::RestReply::onAllErrors	(	QObject *	scope,
		const std::function< void(QString, int, Error)> &	handler,
		TFn &&	failureTransformer
	)

Set a handler to be called if the request did not succeed.

Parameters

scope	A scope to limit the callback to
handler	The function to be called on any error
failureTransformer	(optional) A function to be called to extract an error string from the failure JSON

Returns: A reference to this reply

The handlers arguments are:

The error string (QString)
- For network error: QNetworkReply::errorString
- For json error: QJsonParseError::errorString
- For failure error: failureTransformer
The error code (int)
- For network error: QNetworkReply::error
- For json error: QJsonParseError::error
- For failure error: The HTTP-Status code
The error type (RestReply::Error, either RestReply::Error::NetworkError, RestReply::Error::ParseError or RestReply::Error::FailureError)

The failureTransformer can have the following signature:

(<data>, int): QString (HTTP reply body, HTTP status code)

The <data> part can be any of the following:

<jdata>
<cdata>
std::variant<std::nullopt_t, <cdata>, <jdata>>
std::variant<<cdata>, <jdata>>

See also: RestReply::onError, RestReply::onFailed, GenericRestReply::onAllErrors

Definition at line 248 of file restreply.h.

◆ onCompleted() [1/2]

template<typename TFn >

QtRestClient::RestReply::onCompleted	(	QObject *	scope,
		TFn &&	handler
	)

Set a handler to be called when the request was completed, regardless of success or failure.

Parameters

scope	(optional) A scope to limit the callback to
handler	The function to be called on success

Returns: A reference to this reply

The handlers can have the following signatures:

(): any
(int): any (HTTP status code)
(<data>): any (HTTP reply body)
(int, <data>): any (HTTP status code, HTTP reply body)
(int, RestReply::DataType): any (HTTP status code, HTTP reply body)

The <data> part can be any of the following:

<jdata>
<cdata>
std::variant<std::nullopt_t, <cdata>, <jdata>>
std::variant<<cdata>, <jdata>>

See also: RestReply::onFailed, RestReply::onSucceeded, GenericRestReply::onCompleted

Definition at line 233 of file restreply.h.

◆ onCompleted() [2/2]

template<typename TFn >

QtRestClient::RestReply::onCompleted ( TFn && handler )

Set a handler to be called when the request was completed, regardless of success or failure.

Parameters

handler The function to be called on success

Returns: A reference to this reply

The handlers can have the following signatures:

(): any
(int): any (HTTP status code)
(<data>): any (HTTP reply body)
(int, <data>): any (HTTP status code, HTTP reply body)
(int, RestReply::DataType): any (HTTP status code, HTTP reply body)

The <data> part can be any of the following:

<jdata>
<cdata>
std::variant<std::nullopt_t, <cdata>, <jdata>>
std::variant<<cdata>, <jdata>>

See also: RestReply::onFailed, RestReply::onSucceeded, GenericRestReply::onCompleted

Definition at line 227 of file restreply.h.

◆ onError() [1/2]

QtRestClient::RestReply::onError	(	QObject *	scope,
		std::function< void(QString, int, Error)>	handler
	)

Set a handler to be called if a network error or json parse error occures.

Parameters

scope	A scope to limit the callback to
handler	The function to be called on a network/json error

Returns: A reference to this reply

The handlers arguments are:

The error string (QString)
- For network error: QNetworkReply::errorString
- For json error: QJsonParseError::errorString
The error code (int)
- For network error: QNetworkReply::error
- For json error: QJsonParseError::error
The error type (RestReply::Error, either RestReply::Error::NetworkError or RestReply::Error::ParseError)

See also: RestReply::onAllErrors, GenericRestReply::onAllErrors

◆ onError() [2/2]

QtRestClient::RestReply::onError ( std::function< void(QString, int, Error)> handler )

Set a handler to be called if a network error or json parse error occures.

Parameters

handler The function to be called on a network/json error

Returns: A reference to this reply

The handlers arguments are:

The error string (QString)
- For network error: QNetworkReply::errorString
- For json error: QJsonParseError::errorString
The error code (int)
- For network error: QNetworkReply::error
- For json error: QJsonParseError::error
The error type (RestReply::Error, either RestReply::Error::NetworkError or RestReply::Error::ParseError)

See also: RestReply::onAllErrors, GenericRestReply::onAllErrors

◆ onFailed() [1/2]

template<typename TFn >

QtRestClient::RestReply::onFailed	(	QObject *	scope,
		TFn &&	handler
	)

Set a handler to be called if the request failed.

Parameters

scope	A scope to limit the callback to
handler	The function to be called on failure

Returns: A reference to this reply

The handlers can have the following signatures:

(): any
(int): any (HTTP status code)
(<data>): any (HTTP reply body)
(int, <data>): any (HTTP status code, HTTP reply body)
(int, RestReply::DataType): any (HTTP status code, HTTP reply body)

The <data> part can be any of the following:

<jdata>
<cdata>
std::variant<std::nullopt_t, <cdata>, <jdata>>
std::variant<<cdata>, <jdata>>

See also: RestReply::onAllErrors, RestReply::onSucceeded, RestReply::onCompleted, GenericRestReply::onFailed

Definition at line 218 of file restreply.h.

◆ onFailed() [2/2]

template<typename TFn >

QtRestClient::RestReply::onFailed ( TFn && handler )

Set a handler to be called if the request failed.

Parameters

handler The function to be called on failure

Returns: A reference to this reply

The handlers can have the following signatures:

(): any
(int): any (HTTP status code)
(<data>): any (HTTP reply body)
(int, <data>): any (HTTP status code, HTTP reply body)
(int, RestReply::DataType): any (HTTP status code, HTTP reply body)

The <data> part can be any of the following:

<jdata>
<cdata>
std::variant<std::nullopt_t, <cdata>, <jdata>>
std::variant<<cdata>, <jdata>>

See also: RestReply::onAllErrors, RestReply::onSucceeded, RestReply::onCompleted, GenericRestReply::onFailed

Definition at line 212 of file restreply.h.

◆ onSucceeded() [1/2]

template<typename TFn >

QtRestClient::RestReply::onSucceeded	(	QObject *	scope,
		TFn &&	handler
	)

Set a handler to be called if the request succeeded.

Parameters

scope	A scope to limit the callback to
handler	The function to be called on success

Returns: A reference to this reply

The handlers can have the following signatures:

(): any
(int): any (HTTP status code)
(<data>): any (HTTP reply body)
(int, <data>): any (HTTP status code, HTTP reply body)
(int, RestReply::DataType): any (HTTP status code, HTTP reply body)

The <data> part can be any of the following:

<jdata>
<cdata>
std::variant<std::nullopt_t, <cdata>, <jdata>>
std::variant<<cdata>, <jdata>>

See also: RestReply::onFailed, RestReply::onCompleted, GenericRestReply::onSucceeded

Definition at line 203 of file restreply.h.

◆ onSucceeded() [2/2]

template<typename TFn >

QtRestClient::RestReply::onSucceeded ( TFn && handler )

Set a handler to be called if the request succeeded.

Parameters

handler The function to be called on success

Returns: A reference to this reply

The handlers can have the following signatures:

(): any
(int): any (HTTP status code)
(<data>): any (HTTP reply body)
(int, <data>): any (HTTP status code, HTTP reply body)
(int, RestReply::DataType): any (HTTP status code, HTTP reply body)

The <data> part can be any of the following:

<jdata>
<cdata>
std::variant<std::nullopt_t, <cdata>, <jdata>>
std::variant<<cdata>, <jdata>>

See also: RestReply::onFailed, RestReply::onCompleted, GenericRestReply::onSucceeded

Definition at line 197 of file restreply.h.

◆ retry

QtRestClient::RestReply::retry ( )

slot

Tries to make the same request again, and reuses this rest reply.

This function simply resends the request. Internally, the network reply is exchanged with the new one. This means after a retry the reply will not be deleted. Please not that retry will not immediatly perform the retry, but instead wait for the request to finish, call all handlers, and at the very end check if it should retry. This means you can safely call this method from any handler.

See also: RestReply::abort

◆ retryAfter

QtRestClient::RestReply::retryAfter ( std::chrono::milliseconds mSecs )

slot

Tries to make the same request again after a delay, and reuses this rest reply.

Parameters

mSecs The delay, in milliseconds, to wait before retrying to send

This function simply resends the request. Internally, the network reply is exchanged with the new one. This means after a retry the reply will not be deleted. Please not that retry will not immediatly perform the retry, but instead wait for the request to finish, call all handlers, and at the very end check if it should retry. This means you can safely call this method from any handler.

See also: RestReply::abort

Property Documentation

◆ allowEmptyReplies

QtRestClient::RestReply::allowEmptyReplies

readwrite

Speciefies, whether empty rest replies are allowed.

Default: false

By default, only rest replies that have the NO_CONTENT(204) HTTP status code set are allowed to have an empty body. For all other status codes, the request will fail if the body is not a valid JSON object or array. By setting this property to true, such replies are treated as valid and behave as if that status code was set.

Accessors
READ	allowsEmptyReplies()
WRITE	setAllowEmptyReplies()
NOTIFY	allowEmptyRepliesChanged()
REVISION	2

Definition at line 30 of file restreply.h.

◆ async

QtRestClient::RestReply::async

readwrite

Specifies, whether the reply should be handled on a threadpool or not.

Default: false

If a reply was marked as async, the handler the parses, deserialized and processed the received data will not be run on the replies thread, but on a threadpool. By default, the global threadpool QThreadPool::globalInstance() is used, but calling makeAsync() allows you to specify your own pool.

Warning: Please read the Multithreading section of the README before using the replies in a threaded context.

Accessors
READ	isAsync()
WRITE	setAsync()
WRITE	makeAsync() (indirect)
NOTIFY	asyncChanged()

See also: QThreadPool::globalInstance, RestClient::asyncPool

Definition at line 33 of file restreply.h.

◆ autoDelete

QtRestClient::RestReply::autoDelete

readwrite

Speciefies, whether the reply should be automatically deleted.

Default: true

If set to true, the reply will de deleted automatically, right after all handlers have been called. While it is recommended to use this property, you must be aware that qeued connections will not work if enabled. And of couse this means, that you should not access the reply outside of the handlers after returning to the event loop once.

Accessors
READ	autoDelete()
WRITE	setAutoDelete()
WRITE	disableAutoDelete() (indirect)
NOTIFY	autoDeleteChanged()

Definition at line 28 of file restreply.h.

The documentation for this class was generated from the following files:

restreply.h
restreply.dox

Public Types

Public Slots

Signals

Public Member Functions

Properties

Additional Inherited Members

Detailed Description

Definition of "Failure"

Member Enumeration Documentation

◆ Error

Member Function Documentation

◆ onAllErrors() [1/2]

◆ onAllErrors() [2/2]

◆ onCompleted() [1/2]

◆ onCompleted() [2/2]

◆ onError() [1/2]

◆ onError() [2/2]

◆ onFailed() [1/2]

◆ onFailed() [2/2]

◆ onSucceeded() [1/2]

◆ onSucceeded() [2/2]

◆ retry

◆ retryAfter

Property Documentation

◆ allowEmptyReplies

◆ async

◆ autoDelete