QRestAccessManager Class

The QRestAccessManager is a networking convenience class for RESTful client applications. More...

Header: #include <QRestAccessManager>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network
Since: Qt 6.7
Inherits: QObject
Status: Preliminary

This class is under development and is subject to change.

Note: All functions in this class are reentrant.

Public Functions

QRestAccessManager(QObject *parent = nullptr)
virtual ~QRestAccessManager() override
void abortRequests()
QRestReply *deleteResource(const QNetworkRequest &request, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
bool deletesRepliesOnFinished() const
QRestReply *get(const QNetworkRequest &request, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *get(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *get(const QNetworkRequest &request, const QJsonObject &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *get(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *head(const QNetworkRequest &request, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkAccessManager *networkAccessManager() const
QRestReply *patch(const QNetworkRequest &request, const QJsonObject &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *patch(const QNetworkRequest &request, const QJsonArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *patch(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *patch(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *patch(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *post(const QNetworkRequest &request, const QJsonObject &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *post(const QNetworkRequest &request, const QJsonArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *post(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *post(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *post(const QNetworkRequest &request, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *post(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *put(const QNetworkRequest &request, const QJsonObject &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *put(const QNetworkRequest &request, const QJsonArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *put(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *put(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *put(const QNetworkRequest &request, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *put(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QRestReply *sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
void setDeletesRepliesOnFinished(bool autoDelete)
void setTransferTimeout(std::chrono::milliseconds timeout)
std::chrono::milliseconds transferTimeout() const

Signals

void authenticationRequired(QRestReply *reply, QAuthenticator *authenticator)
void proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)
void requestFinished(QRestReply *reply)
QDebug operator<<(QDebug debug, const QRestAccessManager &manager)

Detailed Description

QRestAccessManager provides a networking API for typical REST client applications. It provides the means to issue HTTP requests such as GET and POST. The responses to these requests can be handled with traditional Qt signal and slot mechanisms, as well as by providing callbacks directly - see Issuing Network Requests and Handling Replies.

The class is a wrapper on top of QNetworkAccessManager, and it both amends convenience methods and omits typically less used features. These features are still accessible by configuring the underlying QNetworkAccessManager directly. QRestAccessManager is closely related to the QRestReply class, which it returns when issuing network requests.

QRestAccessManager and related QRestReply classes can only be used in the thread they live in. For further information see QObject thread affinity documentation.

Issuing Network Requests and Handling Replies

Network requests are initiated with a function call corresponding to the desired HTTP method, such as get() and post().

Using Signals and Slots

The function returns a QRestReply* object, whose signals can be used to follow up on the completion of the request in a traditional Qt-signals-and-slots way.

Here's an example of how you could send a GET request and handle the response:

 QRestReply *reply = manager->get(request);
 QObject::connect(reply, &QRestReply::finished, this, &MyClass::handleFinished);

Using Callbacks and Context Objects

The functions also take a context object of QObject (subclass) type and a callback function as parameters. The callback takes one QRestReply* as a parameter. The callback can be any callable, incl. a pointer-to-member-function..

These callbacks are invoked when the QRestReply has finished processing (also in the case the processing finished due to an error).

The context object can be nullptr, although, generally speaking, this is discouraged. Using a valid context object ensures that if the context object is destroyed during request processing, the callback will not be called. Stray callbacks which access a destroyed context is a source of application misbehavior.

Here's an example of how you could send a GET request and check the response:

 // With lambda
 manager->get(request, this, [this](QRestReply *reply) {
     if (reply->isSuccess()) {
         // ...
     }
 });
 // With member function
 manager->get(request, this, &MyClass::handleFinished);

Many of the functions take in data for sending to a server. The data is supplied as the second parameter after the request.

Here's an example of how you could send a POST request and check the response:

 QJsonObject myJson;
 // ...
 manager->post(request, myJson, this, [this](QRestReply *reply) {
     if (!reply->isSuccess()) {
         // ...
     }
     if (std::optional json = reply->json()) {
         // use *json
     }
 });

Supported data types

The following table summarizes the methods and the supported data types. X means support.

Data typeget()post()put()head()patch()deleteResource()sendCustomRequest()
No dataX--X-X-
QByteArrayXXX-X-X
QJsonObject *)XXX-X--
QJsonArray *)-XX-X--
QVariantMap **)-XX-X--
QHttpMultiPart-XX---X
QIODeviceXXX-X-X

*) QJsonObject and QJsonArray are sent in QJsonDocument::Compact format, and the Content-Type header is set to application/json if the Content-Type header was not set

**) QVariantMap is converted to and treated as a QJsonObject

See also QRestReply, QNetworkRequestFactory, and QNetworkAccessManager.

Member Function Documentation

[explicit] QRestAccessManager::QRestAccessManager(QObject *parent = nullptr)

Constructs a QRestAccessManager and sets parent as the parent object.

[override virtual noexcept] QRestAccessManager::~QRestAccessManager()

Destroys the QRestAccessManager object and frees up any resources, including any unfinished QRestReply objects.

void QRestAccessManager::abortRequests()

Aborts all unfinished network requests. Calling this function is same as calling QRestReply::abort() for all individual unfinished requests.

See also QRestReply::abort() and QNetworkReply::abort().

[signal] void QRestAccessManager::authenticationRequired(QRestReply *reply, QAuthenticator *authenticator)

This signal is emitted when the final server requires authentication. The authentication relates to the provided reply instance, and any credentials are to be filled in the provided authenticator instance.

See QNetworkAccessManager::authenticationRequired() for details.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::deleteResource(const QNetworkRequest &request, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

Issues an HTTP DELETE based on request.

The optional callback and context object can be provided for handling the request completion as illustrated below:

 manager->deleteResource(request, this, [this](QRestReply *reply) {
     if (reply->isSuccess())
         // ...
 });

Alternatively the signals of the returned QRestReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

deleteResource() request does not support providing data.

See also QRestReply, QRestReply::finished(), and QRestAccessManager::requestFinished().

bool QRestAccessManager::deletesRepliesOnFinished() const

Returns whether QRestAccessManager is currently configured to automatically delete replies once they have finished. By default this is true.

See also setDeletesRepliesOnFinished().

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::get(const QNetworkRequest &request, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

Issues an HTTP GET based on request.

The optional callback and context object can be provided for handling the request completion as illustrated below:

 manager->get(request, this, [this](QRestReply *reply) {
     if (!reply->isSuccess())
         // handle error
     if (std::optional json = reply->json())
         // use *json
 });

Alternatively the signals of the returned QRestReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

See also QRestReply, QRestReply::finished(), and QRestAccessManager::requestFinished().

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::get(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

Issues an HTTP GET based on request and provided data.

The optional callback and context object can be provided for handling the request completion as illustrated below:

 manager->get(request, myData, this, [this](QRestReply *reply) {
     if (reply->isSuccess())
         // ...
 });

Alternatively the signals of the returned QRestReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

See also QRestReply, QRestReply::finished(), and QRestAccessManager::requestFinished().

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::get(const QNetworkRequest &request, const QJsonObject &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::get(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

Issues an HTTP HEAD based on request.

The optional callback and context object can be provided for handling the request completion as illustrated below:

 manager->head(request, this, [this](QRestReply *reply) {
     if (reply->isSuccess())
         // ...
 });

Alternatively the signals of the returned QRestReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

head() request does not support providing data.

See also QRestReply, QRestReply::finished(), and QRestAccessManager::requestFinished().

QNetworkAccessManager *QRestAccessManager::networkAccessManager() const

Returns the underlying QNetworkAccessManager instance. The instance can be used for accessing less-frequently used features and configurations.

See also QNetworkAccessManager.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::patch(const QNetworkRequest &request, const QJsonObject &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

Issues an HTTP PATCH based on request.

The optional callback and context object can be provided for handling the request completion as illustrated below:

 manager->patch(request, myData, this, [this](QRestReply *reply) {
     if (reply->isSuccess())
         // ...
 });

Alternatively the signals of the returned QRestReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

The patch() method always requires data parameter. The following data types are supported:

*) Sent in QJsonDocument::Compact format, and the Content-Type header is set to application/json if the Content-Type header was not set **) QVariantMap is converted to and treated as a QJsonObject

See also QRestReply, QRestReply::finished(), and QRestAccessManager::requestFinished().

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::patch(const QNetworkRequest &request, const QJsonArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::patch(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::patch(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::patch(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::post(const QNetworkRequest &request, const QJsonObject &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

Issues an HTTP POST based on request.

The optional callback and context object can be provided for handling the request completion as illustrated below:

 manager->post(request, myData, this, [this](QRestReply *reply) {
     if (reply->isSuccess())
         // ...
 });

Alternatively, the signals of the returned QRestReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

The post() method always requires data parameter. The following data types are supported:

*) Sent in QJsonDocument::Compact format, and the Content-Type header is set to application/json if the Content-Type header was not set **) QVariantMap is converted to and treated as a QJsonObject

See also QRestReply, QRestReply::finished(), and QRestAccessManager::requestFinished().

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::post(const QNetworkRequest &request, const QJsonArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::post(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::post(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::post(const QNetworkRequest &request, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::post(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

[signal] void QRestAccessManager::proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)

This signal is emitted when a proxy authentication requires action. The proxy details are in proxy object, and any credentials are to be filled in the provided authenticator object.

See QNetworkAccessManager::proxyAuthenticationRequired() for details.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::put(const QNetworkRequest &request, const QJsonObject &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

Issues an HTTP PUT based on request.

The optional callback and context object can be provided for handling the request completion as illustrated below:

 manager->put(request, myData, this, [this](QRestReply *reply) {
     if (reply->isSuccess())
         // ...
 });

Alternatively the signals of the returned QRestReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

The put() method always requires data parameter. The following data types are supported:

*) Sent in QJsonDocument::Compact format, and the Content-Type header is set to application/json if the Content-Type header was not set **) QVariantMap is converted to and treated as a QJsonObject

See also QRestReply, QRestReply::finished(), and QRestAccessManager::requestFinished().

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::put(const QNetworkRequest &request, const QJsonArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::put(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::put(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::put(const QNetworkRequest &request, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::put(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

[signal] void QRestAccessManager::requestFinished(QRestReply *reply)

This signal is emitted whenever a pending network reply is finished. reply parameter will contain a pointer to the reply that has just finished. This signal is emitted in tandem with the QRestReply::finished() signal. QRestReply provides functions for checking the status of the request, as well as for acquiring any received data.

Note: Do not delete reply object in the slot connected to this signal. Use deleteLater() if needed. See also deletesRepliesOnFinished().

See also QRestReply::finished().

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

Issues request based HTTP request with custom method and the provided data.

The optional callback and context object can be provided for handling the request completion as illustrated below:

 manager->sendCustomRequest(request, "MYMETHOD",  myData,  this, [this](QRestReply *reply) {
     if (reply->isSuccess())
         // ...
 });

Alternatively the signals of the returned QRestReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QRestReply *QRestAccessManager::sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

This is an overloaded function.

void QRestAccessManager::setDeletesRepliesOnFinished(bool autoDelete)

Enables or disables automatic deletion of QRestReply instances once the request has finished, according to the provided autoDelete parameter. The deletion is done with deleteLater() so that using the replies in directly-connected slots or callbacks is safe.

See also deletesRepliesOnFinished().

void QRestAccessManager::setTransferTimeout(std::chrono::milliseconds timeout)

Sets timeout used for transfers.

See also QNetworkAccessManager::setTransferTimeout(), transferTimeout(), and QNetworkRequestFactory::setTransferTimeout().

std::chrono::milliseconds QRestAccessManager::transferTimeout() const

Returns the timeout used for transfers.

See also setTransferTimeout(), QNetworkAccessManager::transferTimeoutAsDuration(), and QNetworkRequestFactory::transferTimeout().

Related Non-Members

QDebug operator<<(QDebug debug, const QRestAccessManager &manager)

Writes manager into debug stream.

See also Debugging Techniques.