Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
Convenience class for grouping remote server endpoints that share common network request properties. More...
#include <qnetworkrequestfactory.h>
Public Member Functions | |
Q_NETWORK_EXPORT | QNetworkRequestFactory () |
Creates a new QNetworkRequestFactory object. | |
Q_NETWORK_EXPORT | QNetworkRequestFactory (const QUrl &baseUrl) |
Creates a new QNetworkRequestFactory object, initializing the base URL to baseUrl. | |
Q_NETWORK_EXPORT | ~QNetworkRequestFactory () |
Destroys this QNetworkRequestFactory object. | |
Q_NETWORK_EXPORT | QNetworkRequestFactory (const QNetworkRequestFactory &other) |
Creates a copy of other. | |
QNetworkRequestFactory (QNetworkRequestFactory &&other) noexcept=default | |
Move-constructs the factory from other. | |
Q_NETWORK_EXPORT QNetworkRequestFactory & | operator= (const QNetworkRequestFactory &other) |
Creates a copy of other and returns a reference to this factory. | |
void | swap (QNetworkRequestFactory &other) noexcept |
Swaps this factory with other. | |
Q_NETWORK_EXPORT QUrl | baseUrl () const |
Returns the base URL used for the individual requests. | |
Q_NETWORK_EXPORT void | setBaseUrl (const QUrl &url) |
Sets the base URL used in individual requests to url. | |
Q_NETWORK_EXPORT QNetworkRequest | createRequest () const |
Returns a QNetworkRequest. | |
Q_NETWORK_EXPORT QNetworkRequest | createRequest (const QUrlQuery &query) const |
Returns a QNetworkRequest. | |
Q_NETWORK_EXPORT QNetworkRequest | createRequest (const QString &path) const |
Returns a QNetworkRequest. | |
Q_NETWORK_EXPORT QNetworkRequest | createRequest (const QString &path, const QUrlQuery &query) const |
Returns a QNetworkRequest. | |
Q_NETWORK_EXPORT void | setCommonHeaders (const QHttpHeaders &headers) |
Sets headers that are common to all requests. | |
Q_NETWORK_EXPORT QHttpHeaders | commonHeaders () const |
Returns the currently set headers. | |
Q_NETWORK_EXPORT void | clearCommonHeaders () |
Clears current headers. | |
Q_NETWORK_EXPORT QByteArray | bearerToken () const |
Returns the bearer token that has been set. | |
Q_NETWORK_EXPORT void | setBearerToken (const QByteArray &token) |
Sets the bearer token to token. | |
Q_NETWORK_EXPORT void | clearBearerToken () |
Clears the bearer token. | |
Q_NETWORK_EXPORT QString | userName () const |
Returns the username set to this factory. | |
Q_NETWORK_EXPORT void | setUserName (const QString &userName) |
Sets the username of this factory to userName. | |
Q_NETWORK_EXPORT void | clearUserName () |
Clears the username set to this factory. | |
Q_NETWORK_EXPORT QString | password () const |
Returns the password set to this factory. | |
Q_NETWORK_EXPORT void | setPassword (const QString &password) |
Sets the password of this factory to password. | |
Q_NETWORK_EXPORT void | clearPassword () |
Clears the password set to this factory. | |
Q_NETWORK_EXPORT void | setTransferTimeout (std::chrono::milliseconds timeout) |
Sets timeout used for transfers. | |
Q_NETWORK_EXPORT std::chrono::milliseconds | transferTimeout () const |
Returns the timeout used for transfers. | |
Q_NETWORK_EXPORT QUrlQuery | queryParameters () const |
Returns query parameters that are added to individual requests' query parameters. | |
Q_NETWORK_EXPORT void | setQueryParameters (const QUrlQuery &query) |
Sets query parameters that are added to individual requests' query parameters. | |
Q_NETWORK_EXPORT void | clearQueryParameters () |
Clears the query parameters. | |
Q_NETWORK_EXPORT void | setPriority (QNetworkRequest::Priority priority) |
Q_NETWORK_EXPORT QNetworkRequest::Priority | priority () const |
Q_NETWORK_EXPORT QVariant | attribute (QNetworkRequest::Attribute attribute) const |
Q_NETWORK_EXPORT QVariant | attribute (QNetworkRequest::Attribute attribute, const QVariant &defaultValue) const |
Q_NETWORK_EXPORT void | setAttribute (QNetworkRequest::Attribute attribute, const QVariant &value) |
Q_NETWORK_EXPORT void | clearAttribute (QNetworkRequest::Attribute attribute) |
Q_NETWORK_EXPORT void | clearAttributes () |
Friends | |
Q_NETWORK_EXPORT QDebug | operator<< (QDebug debug, const QNetworkRequestFactory &reply) |
Writes factory into debug stream. | |
Convenience class for grouping remote server endpoints that share common network request properties.
\inmodule QtNetwork
\preliminary
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: \list
An example of usage:
Definition at line 28 of file qnetworkrequestfactory.h.
QNetworkRequestFactory::QNetworkRequestFactory | ( | ) |
Creates a new QNetworkRequestFactory object.
Use setBaseUrl() to set a valid base URL for the requests.
Definition at line 58 of file qnetworkrequestfactory.cpp.
|
explicit |
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:
Definition at line 75 of file qnetworkrequestfactory.cpp.
|
default |
Destroys this QNetworkRequestFactory object.
|
default |
Creates a copy of other.
|
defaultnoexcept |
Move-constructs the factory from other.
QVariant QNetworkRequestFactory::attribute | ( | QNetworkRequest::Attribute | attribute | ) | const |
Returns the value associated with attribute. If the attribute has not been set, returns a default-constructed \l QVariant.
Definition at line 549 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::attributes, and QHash< Key, T >::value().
QVariant QNetworkRequestFactory::attribute | ( | QNetworkRequest::Attribute | attribute, |
const QVariant & | defaultValue ) const |
Returns the value associated with attribute. If the attribute has not been set, returns defaultValue.
Definition at line 563 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::attributes, and QHash< Key, T >::value().
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.
Definition at line 134 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::baseUrl.
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 \l commonHeaders() listing. If the \l commonHeaders() also lists Authorization
header, it will be overwritten.
Definition at line 293 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::bearerToken.
void QNetworkRequestFactory::clearAttribute | ( | QNetworkRequest::Attribute | attribute | ) |
Clears attribute set to this factory.
Definition at line 576 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::attributes, QHash< Key, T >::contains(), QExplicitlySharedDataPointer< T >::detach(), and QHash< Key, T >::remove().
void QNetworkRequestFactory::clearAttributes | ( | ) |
Clears any attributes set to this factory.
Definition at line 591 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::attributes, QHash< Key, T >::clear(), QExplicitlySharedDataPointer< T >::detach(), and QHash< Key, T >::isEmpty().
void QNetworkRequestFactory::clearBearerToken | ( | ) |
Clears the bearer token.
Definition at line 317 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::bearerToken, QByteArray::clear(), QExplicitlySharedDataPointer< T >::detach(), and QByteArray::isEmpty().
void QNetworkRequestFactory::clearCommonHeaders | ( | ) |
Clears current headers.
Definition at line 266 of file qnetworkrequestfactory.cpp.
References QHttpHeaders::clear(), QExplicitlySharedDataPointer< T >::detach(), QNetworkRequestFactoryPrivate::headers, and QHttpHeaders::isEmpty().
void QNetworkRequestFactory::clearPassword | ( | ) |
Clears the password set to this factory.
Definition at line 398 of file qnetworkrequestfactory.cpp.
References QString::clear(), QExplicitlySharedDataPointer< T >::detach(), QString::isEmpty(), and QNetworkRequestFactoryPrivate::password.
void QNetworkRequestFactory::clearQueryParameters | ( | ) |
Clears the query parameters.
Definition at line 469 of file qnetworkrequestfactory.cpp.
References QUrlQuery::clear(), QExplicitlySharedDataPointer< T >::detach(), QUrlQuery::isEmpty(), and QNetworkRequestFactoryPrivate::queryParameters.
void QNetworkRequestFactory::clearUserName | ( | ) |
Clears the username set to this factory.
Definition at line 357 of file qnetworkrequestfactory.cpp.
References QString::clear(), QExplicitlySharedDataPointer< T >::detach(), QString::isEmpty(), and QNetworkRequestFactoryPrivate::userName.
QHttpHeaders QNetworkRequestFactory::commonHeaders | ( | ) | const |
Returns the currently set headers.
Definition at line 256 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::headers.
QNetworkRequest QNetworkRequestFactory::createRequest | ( | ) | const |
Returns a QNetworkRequest.
The returned request is filled with the data that this factory has been configured with.
Definition at line 189 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::newRequest(), and QNetworkRequestFactoryPrivate::requestUrl().
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).
Definition at line 202 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::newRequest(), and QNetworkRequestFactoryPrivate::requestUrl().
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.
Definition at line 231 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::newRequest(), and QNetworkRequestFactoryPrivate::requestUrl().
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.
Definition at line 215 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::newRequest(), and QNetworkRequestFactoryPrivate::requestUrl().
|
default |
Creates a copy of other and returns a reference to this factory.
Move-assigns other and returns a reference to this factory.
QString QNetworkRequestFactory::password | ( | ) | const |
Returns the password set to this factory.
Definition at line 370 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::password.
Referenced by setPassword().
QNetworkRequest::Priority QNetworkRequestFactory::priority | ( | ) | const |
Returns the priority assigned to any future requests created by this factory.
Definition at line 504 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::priority.
Referenced by setPriority().
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 \l 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.
Definition at line 444 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::queryParameters.
void QNetworkRequestFactory::setAttribute | ( | QNetworkRequest::Attribute | attribute, |
const QVariant & | value ) |
Sets the value associated with attribute to value. If the attribute is already set, the previous value is replaced. The attributes are set to any future requests created by this factory.
Definition at line 520 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::attributes, QNetworkRequest::ConnectionEncryptedAttribute, QExplicitlySharedDataPointer< T >::detach(), QNetworkRequest::Http2WasUsedAttribute, QNetworkRequest::HttpPipeliningWasUsedAttribute, QNetworkRequest::HttpReasonPhraseAttribute, QNetworkRequest::HttpStatusCodeAttribute, QHash< Key, T >::insert(), QNetworkRequest::OriginalContentLengthAttribute, qCWarning, QNetworkRequest::RedirectionTargetAttribute, and QNetworkRequest::SourceIsFromCacheAttribute.
Sets the base URL used in individual requests to url.
Definition at line 144 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::baseUrl, QExplicitlySharedDataPointer< T >::detach(), and url.
void QNetworkRequestFactory::setBearerToken | ( | const QByteArray & | token | ) |
Sets the bearer token to token.
Definition at line 303 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::bearerToken, QExplicitlySharedDataPointer< T >::detach(), and token.
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.
Definition at line 245 of file qnetworkrequestfactory.cpp.
References QExplicitlySharedDataPointer< T >::detach(), and QNetworkRequestFactoryPrivate::headers.
Sets the password of this factory to password.
The password is set in the request URL when \l createRequest() is called. The QRestAccessManager / QNetworkAccessManager will attempt to use these credentials when the server indicates that authentication is required.
Definition at line 385 of file qnetworkrequestfactory.cpp.
References QExplicitlySharedDataPointer< T >::detach(), password(), and QNetworkRequestFactoryPrivate::password.
void QNetworkRequestFactory::setPriority | ( | QNetworkRequest::Priority | priority | ) |
Sets the priority for any future requests created by this factory to priority.
The default priority is \l QNetworkRequest::NormalPriority.
Definition at line 488 of file qnetworkrequestfactory.cpp.
References QExplicitlySharedDataPointer< T >::detach(), priority(), and QNetworkRequestFactoryPrivate::priority.
Sets query parameters that are added to individual requests' query parameters.
Definition at line 455 of file qnetworkrequestfactory.cpp.
References QExplicitlySharedDataPointer< T >::detach(), and QNetworkRequestFactoryPrivate::queryParameters.
void QNetworkRequestFactory::setTransferTimeout | ( | std::chrono::milliseconds | timeout | ) |
Sets timeout used for transfers.
Definition at line 412 of file qnetworkrequestfactory.cpp.
References QExplicitlySharedDataPointer< T >::detach(), and QNetworkRequestFactoryPrivate::transferTimeout.
Sets the username of this factory to userName.
The username is set in the request URL when \l createRequest() is called. The QRestAccessManager / QNetworkAccessManager will attempt to use these credentials when the server indicates that authentication is required.
Definition at line 346 of file qnetworkrequestfactory.cpp.
References QExplicitlySharedDataPointer< T >::detach(), userName(), and QNetworkRequestFactoryPrivate::userName.
|
inlinenoexcept |
Swaps this factory with other.
This operation is very fast and never fails.
Definition at line 40 of file qnetworkrequestfactory.h.
std::chrono::milliseconds QNetworkRequestFactory::transferTimeout | ( | ) | const |
Returns the timeout used for transfers.
Definition at line 427 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::transferTimeout.
QString QNetworkRequestFactory::userName | ( | ) | const |
Returns the username set to this factory.
Definition at line 331 of file qnetworkrequestfactory.cpp.
References QNetworkRequestFactoryPrivate::userName.
Referenced by setUserName().
|
friend |
Writes factory into debug stream.
Definition at line 704 of file qnetworkrequestfactory.cpp.