QRestAccessManager Class

The QRestAccessManager is a convenience wrapper for QNetworkAccessManager. 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(QNetworkAccessManager *manager, QObject *parent = nullptr)
virtual ~QRestAccessManager() override
QNetworkReply *deleteResource(const QNetworkRequest &request, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *get(const QNetworkRequest &request, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *get(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *get(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *get(const QNetworkRequest &request, const QJsonDocument &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *head(const QNetworkRequest &request, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkAccessManager *networkAccessManager() const
QNetworkReply *patch(const QNetworkRequest &request, const QJsonDocument &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *patch(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *patch(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *patch(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *post(const QNetworkRequest &request, const QJsonDocument &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *post(const QNetworkRequest &request, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *post(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *post(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *post(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *put(const QNetworkRequest &request, const QJsonDocument &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *put(const QNetworkRequest &request, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *put(const QNetworkRequest &request, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *put(const QNetworkRequest &request, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *put(const QNetworkRequest &request, const QVariantMap &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, const QByteArray &data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, QHttpMultiPart *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)
QNetworkReply *sendCustomRequest(const QNetworkRequest &request, const QByteArray &method, QIODevice *data, const QRestAccessManager::ContextTypeForFunctor<Functor> *context, Functor &&callback)

Detailed Description

QRestAccessManager is a convenience wrapper on top of QNetworkAccessManager. It amends datatypes and HTTP methods that are useful for typical RESTful client applications.

The usual Qt networking features are accessible by configuring the wrapped QNetworkAccessManager directly. QRestAccessManager does not take ownership of the wrapped QNetworkAccessManager.

QRestAccessManager and related QRestReply classes can only be used in the thread they live in. See QObject thread affinity for more information.

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 QNetworkReply* 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:

QNetworkReply *reply = manager->get(request);
QObject::connect(reply, &QNetworkReply::finished, this, [reply]() {
    // The reply may be wrapped in the finish handler:
    QRestReply restReply(reply);
    if (restReply.isSuccess())
        // ...
});

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, including a pointer-to-member-function.

These callbacks are invoked when the reply 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:

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

The provided QRestReply& is valid only while the callback executes. If you need it for longer, you can either move it to another QRestReply, or construct a new one and initialize it with the QNetworkReply (see QRestReply::networkReply()).

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
QJsonDocument *)XXX-X--
QVariantMap **)-XX-X--
QHttpMultiPart-XX---X
QIODeviceXXX-X-X

*) QJsonDocument is 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(QNetworkAccessManager *manager, QObject *parent = nullptr)

Constructs a QRestAccessManager object and sets parent as the parent object, and manager as the underlying QNetworkAccessManager which is used for communication.

See also networkAccessManager().

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

Destroys the QRestAccessManager object.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QNetworkReply *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 QNetworkReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

deleteResource() request does not support providing data.

See also QRestReply.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QNetworkReply *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.readJson())
        // use *json
});

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

See also QRestReply.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QNetworkReply *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 QNetworkReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

See also QRestReply.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QNetworkReply *QRestAccessManager::get(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> > QNetworkReply *QRestAccessManager::get(const QNetworkRequest &request, const QJsonDocument &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 QNetworkReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

head() request does not support providing data.

See also QRestReply.

QNetworkAccessManager *QRestAccessManager::networkAccessManager() const

Returns the underlying QNetworkAccessManager instance.

See also QNetworkAccessManager.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QNetworkReply *QRestAccessManager::patch(const QNetworkRequest &request, const QJsonDocument &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 QNetworkReply* 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.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QNetworkReply *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> > QNetworkReply *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> > QNetworkReply *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> > QNetworkReply *QRestAccessManager::post(const QNetworkRequest &request, const QJsonDocument &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 QNetworkReply* 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.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QNetworkReply *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> > QNetworkReply *QRestAccessManager::post(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> > QNetworkReply *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> > QNetworkReply *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> > QNetworkReply *QRestAccessManager::put(const QNetworkRequest &request, const QJsonDocument &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 QNetworkReply* 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.

template <typename Functor, QRestAccessManager::if_compatible_callback<Functor> > QNetworkReply *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> > QNetworkReply *QRestAccessManager::put(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> > QNetworkReply *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> > QNetworkReply *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> > QNetworkReply *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 QNetworkReply* object can be used. For further information see Issuing Network Requests and Handling Replies.

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

This is an overloaded function.

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

This is an overloaded function.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.