QNetworkRequestFactory Class

Convenience class for grouping remote server endpoints that share common network request properties. More...

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

This class is under development and is subject to change.

Public Functions

QNetworkRequestFactory()
QNetworkRequestFactory(const QUrl &baseUrl)
QNetworkRequestFactory(const QNetworkRequestFactory &other)
QNetworkRequestFactory(QNetworkRequestFactory &&other)
~QNetworkRequestFactory()
QUrl baseUrl() const
QByteArray bearerToken() const
void clearBearerToken()
void clearCommonHeaders()
void clearPassword()
void clearQueryParameters()
void clearUserName()
QHttpHeaders commonHeaders() const
QNetworkRequest createRequest() const
QNetworkRequest createRequest(const QUrlQuery &query) const
QNetworkRequest createRequest(const QString &path) const
QNetworkRequest createRequest(const QString &path, const QUrlQuery &query) const
QString password() const
QUrlQuery queryParameters() const
void setBaseUrl(const QUrl &url)
void setBearerToken(const QByteArray &token)
void setCommonHeaders(const QHttpHeaders &headers)
void setPassword(const QString &password)
void setQueryParameters(const QUrlQuery &query)
void setSslConfiguration(const QSslConfiguration &configuration)
void setTransferTimeout(std::chrono::milliseconds timeout)
void setUserName(const QString &userName)
QSslConfiguration sslConfiguration() const
void swap(QNetworkRequestFactory &other)
std::chrono::milliseconds transferTimeout() const
QString userName() const
QNetworkRequestFactory &operator=(const QNetworkRequestFactory &other)
QNetworkRequestFactory &operator=(QNetworkRequestFactory &&other)
QDebug operator<<(QDebug debug, const QNetworkRequestFactory &factory)

Detailed Description

REST servers often have endpoints that require the same headers and other data. Grouping such endpoints with a QNetworkRequestFactory makes it more convenient to issue requests to these endpoints; only the typically varying parts such as path and query parameters are provided when creating a new request.

Basic usage steps of QNetworkRequestFactory are as follows:

  • Instantiation
  • Setting the data common to all requests
  • Issuing requests

An example of usage:

// Instantiate a factory somewhere suitable in the application
QNetworkRequestFactory api{{"https://example.com/v1"_L1}};

// Set bearer token
api.setBearerToken("my_token");

// Issue requests (reply handling omitted for brevity)
manager.get(api.createRequest("models"_L1)); // https://example.com/v1/models
// The conventional leading '/' for the path can be used as well
manager.get(api.createRequest("/models"_L1)); // https://example.com/v1/models

Member Function Documentation

QNetworkRequestFactory::QNetworkRequestFactory()

Creates a new QNetworkRequestFactory object. Use setBaseUrl() to set a valid base URL for the requests.

See also QNetworkRequestFactory(const QUrl &baseUrl) and setBaseUrl().

[explicit] QNetworkRequestFactory::QNetworkRequestFactory(const QUrl &baseUrl)

Creates a new QNetworkRequestFactory object, initializing the base URL to baseUrl. The base URL is used to populate subsequent network requests.

If the URL contains a path component, it will be extracted and used as a base path in subsequent network requests. This means that any paths provided when requesting individual requests will be appended to this base path, as illustrated below:

// Here the API version v2 is used as the base path:
QNetworkRequestFactory api{{"https://example.com/v2"_L1}};
// ...
manager.get(api.createRequest("models"_L1)); // https://example.com/v2/models
// Equivalent with a leading '/'
manager.get(api.createRequest("/models"_L1)); // https://example.com/v2/models

QNetworkRequestFactory::QNetworkRequestFactory(const QNetworkRequestFactory &other)

Creates a copy of other.

[noexcept] QNetworkRequestFactory::QNetworkRequestFactory(QNetworkRequestFactory &&other)

Move-constructs the factory from other.

Note: The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

[noexcept] QNetworkRequestFactory::~QNetworkRequestFactory()

Destroys this QNetworkRequestFactory object.

QUrl QNetworkRequestFactory::baseUrl() const

Returns the base URL used for the individual requests.

The base URL may contain a path component. This path is used as path "prefix" for the paths that are provided when generating individual requests.

See also setBaseUrl().

QByteArray QNetworkRequestFactory::bearerToken() const

Returns the bearer token that has been set.

The bearer token, if present, is used to set the Authorization: Bearer my_token header for requests. This is a common authorization convention and is provided as an additional convenience.

The means to acquire the bearer token vary. Standard methods include OAuth2 and the service provider's website/dashboard. It is expected that the bearer token changes over time. For example, when updated with a refresh token, always setting the new token again ensures that subsequent requests have the latest, valid token.

The presence of the bearer token does not impact the commonHeaders() listing. If the commonHeaders() also lists Authorization header, it will be overwritten.

See also setBearerToken() and commonHeaders().

void QNetworkRequestFactory::clearBearerToken()

Clears the bearer token.

See also bearerToken().

void QNetworkRequestFactory::clearCommonHeaders()

Clears current headers.

See also commonHeaders() and setCommonHeaders().

void QNetworkRequestFactory::clearPassword()

Clears the password set to this factory.

See also password(), setPassword(), and userName().

void QNetworkRequestFactory::clearQueryParameters()

Clears the query parameters.

See also queryParameters().

void QNetworkRequestFactory::clearUserName()

Clears the username set to this factory.

QHttpHeaders QNetworkRequestFactory::commonHeaders() const

Returns the currently set headers.

See also setCommonHeaders() and clearCommonHeaders().

QNetworkRequest QNetworkRequestFactory::createRequest() const

Returns a QNetworkRequest.

The returned request is filled with the data that this factory has been configured with.

See also createRequest(const QUrlQuery&) and createRequest(const QString&, const QUrlQuery&).

QNetworkRequest QNetworkRequestFactory::createRequest(const QUrlQuery &query) const

Returns a QNetworkRequest.

The returned request's URL is formed by appending the provided query to the baseUrl.

See also createRequest(const QString &, const QUrlQuery &), createRequest(), and baseUrl().

QNetworkRequest QNetworkRequestFactory::createRequest(const QString &path) const

Returns a QNetworkRequest.

The returned request's URL is formed by appending the provided path to the baseUrl (which may itself have a path component).

See also createRequest(const QString &, const QUrlQuery &), createRequest(), and baseUrl().

QNetworkRequest QNetworkRequestFactory::createRequest(const QString &path, const QUrlQuery &query) const

Returns a QNetworkRequest.

The returned requests URL is formed by appending the provided path and query to the baseUrl (which may have a path component).

If the provided path contains query items, they will be combined with the items in query.

See also createRequest(const QUrlQuery&), createRequest(), and baseUrl().

QString QNetworkRequestFactory::password() const

Returns the password set to this factory.

See also setPassword(), password(), clearPassword(), and userName().

QUrlQuery QNetworkRequestFactory::queryParameters() const

Returns query parameters that are added to individual requests' query parameters. The query parameters are added to any potential query parameters provided with the individual createRequest() calls.

Use cases for using repeating query parameters are server dependent, but typical examples include language setting ?lang=en, format specification ?format=json, API version specification ?version=1.0 and API key authentication.

See also setQueryParameters(), clearQueryParameters(), and createRequest().

void QNetworkRequestFactory::setBaseUrl(const QUrl &url)

Sets the base URL used in individual requests to url.

See also baseUrl().

void QNetworkRequestFactory::setBearerToken(const QByteArray &token)

Sets the bearer token to token.

See also bearerToken() and clearBearerToken().

void QNetworkRequestFactory::setCommonHeaders(const QHttpHeaders &headers)

Sets headers that are common to all requests.

These headers are added to individual requests' headers. This is a convenience mechanism for setting headers that repeat across requests.

See also commonHeaders(), clearCommonHeaders(), and createRequest().

void QNetworkRequestFactory::setPassword(const QString &password)

Sets the password of this factory to password.

The password is set in the request URL when createRequest() is called. The QRestAccessManager / QNetworkAccessManager will attempt to use these credentials when the server indicates that authentication is required.

See also password(), clearPassword(), and userName().

void QNetworkRequestFactory::setQueryParameters(const QUrlQuery &query)

Sets query parameters that are added to individual requests' query parameters.

See also queryParameters() and clearQueryParameters().

void QNetworkRequestFactory::setSslConfiguration(const QSslConfiguration &configuration)

Sets the SSL configuration to configuration.

See also sslConfiguration().

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

Sets timeout used for transfers.

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

void QNetworkRequestFactory::setUserName(const QString &userName)

Sets the username of this factory to userName.

The username is set in the request URL when createRequest() is called. The QRestAccessManager / QNetworkAccessManager will attempt to use these credentials when the server indicates that authentication is required.

See also userName(), clearUserName(), and password().

QSslConfiguration QNetworkRequestFactory::sslConfiguration() const

Returns the SSL configuration set to this factory. The SSL configuration is set to each individual request.

See also setSslConfiguration().

[noexcept] void QNetworkRequestFactory::swap(QNetworkRequestFactory &other)

Swaps this factory with other. This operation is very fast and never fails.

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

Returns the timeout used for transfers.

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

QString QNetworkRequestFactory::userName() const

Returns the username set to this factory.

See also setUserName(), clearUserName(), and password().

QNetworkRequestFactory &QNetworkRequestFactory::operator=(const QNetworkRequestFactory &other)

Creates a copy of other and returns a reference to this factory.

[noexcept] QNetworkRequestFactory &QNetworkRequestFactory::operator=(QNetworkRequestFactory &&other)

Move-assigns other and returns a reference to this factory.

Note: The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

Related Non-Members

QDebug operator<<(QDebug debug, const QNetworkRequestFactory &factory)

Writes factory into debug stream.

See also Debugging Techniques.

© 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.