QRestReply Class

QRestReply is the class for following up the requests sent with QRestAccessManager. More...

Header: #include <QRestReply>
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

virtual ~QRestReply() override
QByteArray body()
qint64 bytesAvailable() const
QNetworkReply::NetworkError error() const
QString errorString() const
bool hasError() const
int httpStatus() const
bool isFinished() const
bool isHttpStatusSuccess() const
bool isSuccess() const
std::optional<QJsonDocument> json(QJsonParseError *error = nullptr)
QNetworkReply *networkReply() const
QString text()

Public Slots

void abort()

Signals

void downloadProgress(qint64 bytesReceived, qint64 bytesTotal, QRestReply *reply)
void errorOccurred(QRestReply *reply)
void finished(QRestReply *reply)
void readyRead(QRestReply *reply)
void uploadProgress(qint64 bytesSent, qint64 bytesTotal, QRestReply *reply)
QDebug operator<<(QDebug debug, const QRestReply *reply)

Detailed Description

QRestReply is a convenience class for typical RESTful client applications. It wraps the more detailed QNetworkReply and provides convenience methods for data and status handling.

See also QRestAccessManager and QNetworkReply.

Member Function Documentation

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

Destroys this QRestReply object.

See also abort().

[slot] void QRestReply::abort()

Aborts the network operation immediately. The finished() signal will be emitted.

See also QRestAccessManager::abortRequests() and QNetworkReply::abort().

QByteArray QRestReply::body()

Returns the received data as a QByteArray.

Calling this function consumes the data received so far, and any further calls to get response data will return empty until further data has been received.

See also json(), text(), bytesAvailable(), and readyRead().

qint64 QRestReply::bytesAvailable() const

Returns the number of bytes available.

See also body.

[signal] void QRestReply::downloadProgress(qint64 bytesReceived, qint64 bytesTotal, QRestReply *reply)

This signal is emitted to indicate the progress of the download part of this network reply.

The bytesReceived parameter indicates the number of bytes received, while bytesTotal indicates the total number of bytes expected to be downloaded. If the number of bytes to be downloaded is not known, for instance due to a missing Content-Length header, bytesTotal will be -1.

See QNetworkReply::downloadProgress() documentation for more details.

See also bytesAvailable(), readyRead(), and uploadProgress().

QNetworkReply::NetworkError QRestReply::error() const

Returns the last error, if any. The errors include errors such as network and protocol errors, but exclude cases when the server successfully responded with an HTTP status.

See also httpStatus(), isSuccess(), hasError(), and errorString().

[signal] void QRestReply::errorOccurred(QRestReply *reply)

This signal is emitted if, while processing reply, an error occurs that is considered to be a network/protocol error. These errors are disctinct from HTTP error responses such as 500 Internal Server Error. This signal is emitted together with the finished() signal, and often connecting to that is sufficient.

See also finished(), isFinished(), httpStatus(), and error().

QString QRestReply::errorString() const

Returns a human-readable description of the last network error.

See also httpStatus(), isSuccess(), hasError(), and error().

[signal] void QRestReply::finished(QRestReply *reply)

This signal is emitted when reply has finished processing. This signal is emitted also in cases when the reply finished due to network or protocol errors (the server did not reply with an HTTP status).

See also isFinished(), httpStatus(), and error().

bool QRestReply::hasError() const

Returns whether an error has occurred. This includes errors such as network and protocol errors, but excludes cases where the server successfully responded with an HTTP error status (for example 500 Internal Server Error). Use httpStatus() or isHttpStatusSuccess() to get the HTTP status information.

See also httpStatus(), isSuccess(), error(), and errorString().

int QRestReply::httpStatus() const

Returns the HTTP status received in the server response. The value is 0 if not available (the status line has not been received, yet).

Note: The HTTP status is reported as indicated by the received HTTP response. It is possible that an error() occurs after receiving the status, for instance due to network disconnection while receiving a long response. These potential subsequent errors are not represented by the reported HTTP status.

See also isSuccess(), hasError(), and error().

bool QRestReply::isFinished() const

Returns whether the network request has finished.

bool QRestReply::isHttpStatusSuccess() const

Returns whether the HTTP status is between 200..299.

See also isSuccess(), httpStatus(), hasError(), and error().

bool QRestReply::isSuccess() const

Returns whether the HTTP status is between 200..299 and no further errors have occurred while receiving the response (for example abrupt disconnection while receiving the body data). This function is a convenient way to check whether the response is considered successful.

See also httpStatus(), hasError(), and error().

std::optional<QJsonDocument> QRestReply::json(QJsonParseError *error = nullptr)

Returns the received data as a QJsonDocument.

The returned value is wrapped in std::optional. If the conversion from the received data fails (empty data or JSON parsing error), std::nullopt is returned, and error is filled with details.

Calling this function consumes the received data, and any further calls to get response data will return empty.

This function returns std::nullopt and will not consume any data if the reply is not finished. If error is passed, it will be set to QJsonParseError::NoError to distinguish this case from an actual error.

See also body(), text(), finished(), and isFinished().

QNetworkReply *QRestReply::networkReply() const

Returns a pointer to the underlying QNetworkReply wrapped by this object.

[signal] void QRestReply::readyRead(QRestReply *reply)

This signal is emitted when reply has received new data.

See also body(), bytesAvailable(), and isFinished().

QString QRestReply::text()

Returns the received data as a QString.

The received data is decoded into a QString (UTF-16). The decoding uses the Content-Type header's charset parameter to determine the source encoding, if available. If the encoding information is not available or not supported by QStringConverter, UTF-8 is used as a default.

Calling this function consumes the data received so far. Returns a default constructed value if no new data is available, or if the decoding is not supported by QStringConverter, or if the decoding has errors (for example invalid characters).

See also json(), body(), isFinished(), and finished().

[signal] void QRestReply::uploadProgress(qint64 bytesSent, qint64 bytesTotal, QRestReply *reply)

This signal is emitted to indicate the progress of the upload part of reply.

The bytesSent parameter indicates the number of bytes already uploaded, while bytesTotal indicates the total number of bytes still to upload.

If the number of bytes to upload is not known, bytesTotal will be -1.

See QNetworkReply::uploadProgress() documentation for more details.

See also QNetworkReply::uploadProgress() and downloadProgress().

Related Non-Members

QDebug operator<<(QDebug debug, const QRestReply *reply)

Writes the reply into the debug object for debugging purposes.

See also Debugging Techniques.