QNetworkAccessBackend Class

QNetworkAccessBackend is the base class for implementing support for schemes used by QNetworkAccessManager. \since 6.0 \internal. More...

Header: #include <QNetworkAccessBackend>
Inherits: QObject

Public Types

enum class IOFeature { None, ZeroCopy, NeedResetableUpload }
flags IOFeatures
enum class SecurityFeature { None, TLS }
flags SecurityFeatures
enum class TargetType { Networked, Local }
flags TargetTypes

Public Functions

QNetworkAccessBackend(TargetTypes targetTypes, SecurityFeatures securityFeatures, IOFeatures ioFeatures)
QNetworkAccessBackend(TargetTypes targetTypes)
QNetworkAccessBackend(TargetTypes targetTypes, SecurityFeatures securityFeatures)
QNetworkAccessBackend(TargetTypes targetTypes, IOFeatures ioFeatures)
virtual ~QNetworkAccessBackend()
virtual void advanceReadPointer(qint64 distance)
QIODevice *createUploadByteDevice()
QVariant header(QNetworkRequest::KnownHeaders header) const
virtual void ignoreSslErrors()
virtual void ignoreSslErrors(const QList<QSslError> &errors)
IOFeatures ioFeatures() const
bool isCachingEnabled() const
QAbstractNetworkCache *networkCache() const
QNetworkAccessManager::Operation operation() const
QList<QNetworkProxy> proxyList() const
QByteArray rawHeader(const QByteArray &header) const
virtual qint64 read(char *data, qint64 maxlen)
virtual QByteArrayView readPointer()
SecurityFeatures securityFeatures() const
void setAttribute(QNetworkRequest::Attribute attribute, const QVariant &value)
void setCachingEnabled(bool canCache)
void setHeader(QNetworkRequest::KnownHeaders header, const QVariant &value)
void setRawHeader(const QByteArray &header, const QByteArray &value)
virtual void setSslConfiguration(const QSslConfiguration &configuration)
void setUrl(const QUrl &url)
virtual QSslConfiguration sslConfiguration() const
virtual bool start()
TargetTypes targetTypes() const
QIODevice *uploadByteDevice()
QUrl url() const
virtual bool wantToRead()

Public Slots

void readyRead()

Protected Slots

void authenticationRequired(QAuthenticator *authenticator)
void error(QNetworkReply::NetworkError code, const QString &errorString)
void finished()
void metaDataChanged()
void proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)
void redirectionRequested(const QUrl &destination)

Detailed Description

The class is considered semi-private and as such requires linking to "NetworkPrivate" to access the header. Furthermore it means the class is not under the same binary compatibility restrictions as the rest of Qt. While we still try to avoid breakage it may still occur. The class is primarily meant to be used by plugins which would be recompiled every time Qt is updated.

This class can be derived from to add support for further schemes in QNetworkAccessManager.

The design of QNetworkAccessBackend makes it possible to specialize behavior as needed for certain backends. This was done using the (currently) 3 enums TargetType, SecurityFeatures and IOFeatures. For example while only open() and close() are abstract functions you are also required to implement either read() or readPointer() and advanceReadPointer() depending on whether you enable IOFeature::ZeroCopy or not. Read more about it in the documentation for each of the enumerators.

See also TargetType, SecurityFeatures, and IOFeatures.

Member Type Documentation

enum class QNetworkAccessBackend::IOFeature
flags QNetworkAccessBackend::IOFeatures

Use the values in this enum to specify what type of IO features the plugin may utilize.

ConstantValueDescription
QNetworkAccessBackend::IOFeature::None0x0No specific features are claimed to be supported.
QNetworkAccessBackend::IOFeature::ZeroCopy0x1The plugin will have raw data available in contiguous segments and can return a pointer to the data at request. Claiming to support this requires implementing readPointer() and advanceReadPointer().
QNetworkAccessBackend::IOFeature::NeedResetableUpload0x2The plugin may encounter scenarios where data to upload that has already been consumed needs to be restored and re-sent. E.g. some data was consumed and sent before a redirect response was received, and after the redirect the previously-consumed data needs to be re-sent.

The IOFeatures type is a typedef for QFlags<IOFeature>. It stores an OR combination of IOFeature values.

enum class QNetworkAccessBackend::SecurityFeature
flags QNetworkAccessBackend::SecurityFeatures

Use the values in this enum to specify what type of security features the plugin may utilize. Setting the right type(s) can be important, for example: setSslConfiguration() may not be called for any plugin that do not claim to support TLS.

ConstantValueDescription
QNetworkAccessBackend::SecurityFeature::None0x0No specific features are claimed to be supported.
QNetworkAccessBackend::SecurityFeature::TLS0x1The plugin supports and expects to use TLS.

The SecurityFeatures type is a typedef for QFlags<SecurityFeature>. It stores an OR combination of SecurityFeature values.

enum class QNetworkAccessBackend::TargetType
flags QNetworkAccessBackend::TargetTypes

Use the values in this enum to specify what type of target the plugin supports. Setting the right type can be important, for example: proxyList() is only available for a Networked plugin.

ConstantValueDescription
QNetworkAccessBackend::TargetType::Networked0x1The plugin supports and expect to connect to networked resources. E.g. over TCP, UDP or similar.
QNetworkAccessBackend::TargetType::Local0x2The plugin supports and expects to access local files, generate data and/or locally connected devices.

The TargetTypes type is a typedef for QFlags<TargetType>. It stores an OR combination of TargetType values.

Member Function Documentation

QNetworkAccessBackend::QNetworkAccessBackend(TargetTypes targetTypes, SecurityFeatures securityFeatures, IOFeatures ioFeatures)

Constructs the QNetworkAccessBackend. You can opt in to specific backend behaviors with targetTypes, securityFeatures and ioFeatures. See their respective enums and values for more information.

See also TargetType, SecurityFeature, and IOFeature.

QNetworkAccessBackend::QNetworkAccessBackend(TargetTypes targetTypes)

This is an overloaded function.

QNetworkAccessBackend::QNetworkAccessBackend(TargetTypes targetTypes, SecurityFeatures securityFeatures)

This is an overloaded function.

QNetworkAccessBackend::QNetworkAccessBackend(TargetTypes targetTypes, IOFeatures ioFeatures)

This is an overloaded function.

[virtual noexcept] QNetworkAccessBackend::~QNetworkAccessBackend()

Destructs the QNetworkAccessBackend base class.

[virtual] void QNetworkAccessBackend::advanceReadPointer(qint64 distance)

This function is to notify your class that distance bytes have been read using readPointer and next time readPointer() is called those bytes should not be included.

Note: This will only be called if IOFeature::ZeroCopy was specified in the call to the constructor.

See also readPointer.

[protected slot] void QNetworkAccessBackend::authenticationRequired(QAuthenticator *authenticator)

Call this slot if the remote resource requests authentication. This may cause the QNetworkAccessManager::authenticationRequired() signal to be emitted if the credentials are not already stored in an internal cache. The credentials will be stored in authenticator. While authenticator is a pointer, passing nullptr is invalid.

QIODevice *QNetworkAccessBackend::createUploadByteDevice()

Creates a QIODevice for the data provided to upload, if any.

Emission of upload progress is handled internally as the device gets read from.

Returns a pointer to a device with data or nullptr if there was no data to upload.

[protected slot] void QNetworkAccessBackend::error(QNetworkReply::NetworkError code, const QString &errorString)

Call this slot if an error occurs. An error would be something you cannot recover from (e.g. the file requested is missing). The code and errorString is transferred to and stored in the QNetworkReply and the code is emitted through the QNetworkReply::errorOccurred() signal.

[protected slot] void QNetworkAccessBackend::finished()

Call this slot when there will be no more data available, regardless of whether the transfer was successful or unsuccessful. For unsuccessful transfers make sure to call error() first!

Returns the value of the header. If no such header was known it returns a default-constructed QVariant.

See also setHeader, rawHeader, and setRawHeader.

[virtual] void QNetworkAccessBackend::ignoreSslErrors()

This function will be called when the user wants to ignore all TLS handshake errors. Derive this function if TLS is supported.

See also SecurityFeature and securityFeatures.

[virtual] void QNetworkAccessBackend::ignoreSslErrors(const QList<QSslError> &errors)

This function will be called when the user wants to ignore specific errors. Derive this function if TLS is supported.

See also SecurityFeature and securityFeatures.

[noexcept] IOFeatures QNetworkAccessBackend::ioFeatures() const

Returns the I/O features that the backend claims to support.

See also IOFeature.

bool QNetworkAccessBackend::isCachingEnabled() const

Returns true if setCachingEnabled was previously called with true. Returns false otherwise, which is the default value.

See also setCachingEnabled.

[protected slot] void QNetworkAccessBackend::metaDataChanged()

Call this slot, if appropriate, after having processed and updated metadata (e.g. headers).

QAbstractNetworkCache *QNetworkAccessBackend::networkCache() const

Returns the network cache object that was available when the request was started. Returns nullptr if none was available.

QNetworkAccessManager::Operation QNetworkAccessBackend::operation() const

Returns the operation which was requested when calling QNetworkAccessManager.

[protected slot] void QNetworkAccessBackend::proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)

Call this slot if, when connecting through a proxy, it requests authentication. This may cause the QNetworkAccessManager::proxyAuthenticationRequired() signal to be emitted if the credentials are not already stored in an internal cache. To be able to make the lookup in the cache and potentially the subsequent request the proxy needs to be known. The credentials will be stored in authenticator. While authenticator is a pointer, passing nullptr is invalid.

QList<QNetworkProxy> QNetworkAccessBackend::proxyList() const

Returns a list of proxies configured for the URL returned by url().

It is only valid to call this function if TargetType::Networked was specified in the call to the constructor.

QByteArray QNetworkAccessBackend::rawHeader(const QByteArray &header) const

Returns the value of the header. If no such header was known it returns a default-constructed QVariant.

See also setHeader, rawHeader, and setRawHeader.

[virtual] qint64 QNetworkAccessBackend::read(char *data, qint64 maxlen)

Implement this function to support reading from the resource made available by your plugin. Store data in data, up to a maximum of maxlen bytes. Then return the total amount of bytes that was copied.

See also readPointer and wantToRead.

[virtual] QByteArrayView QNetworkAccessBackend::readPointer()

The data which the returned value views must stay valid until at least the next call to a non-const function. advanceReadPointer will be called if any of the data was used.

Note: This will only be called if IOFeature::ZeroCopy was specified in the call to the constructor.

See also advanceReadPointer and read.

[slot] void QNetworkAccessBackend::readyRead()

Call this slot when you have more data available to notify the backend that we can attempt to read again.

[protected slot] void QNetworkAccessBackend::redirectionRequested(const QUrl &destination)

Call this slot if, when connecting to the resource, a redirect to destination was requested.

[noexcept] SecurityFeatures QNetworkAccessBackend::securityFeatures() const

Returns the security related features that the backend claims to support.

See also SecurityFeature.

void QNetworkAccessBackend::setAttribute(QNetworkRequest::Attribute attribute, const QVariant &value)

Set attribute to value. If value.isValid() returns false then the attribute is unset.

This value is accessible on the QNetworkReply instance which was returned when calling one of the appropriate functions on QNetworkAccessManager.

void QNetworkAccessBackend::setCachingEnabled(bool canCache)

If canCache is true then this hints to us that we can cache the reply that is created.

See also isCachingEnabled.

void QNetworkAccessBackend::setHeader(QNetworkRequest::KnownHeaders header, const QVariant &value)

Sets the value of the header to value. This can be queried on the QNetworkReply instance which was returned when calling one of the appropriate functions on QNetworkAccessManager.

See also header, rawHeader, and setRawHeader.

void QNetworkAccessBackend::setRawHeader(const QByteArray &header, const QByteArray &value)

Sets the value of the header to value.

This value is accessible on the QNetworkReply instance which was returned when calling one of the appropriate functions on QNetworkAccessManager.

See also header, rawHeader, and setRawHeader.

[virtual] void QNetworkAccessBackend::setSslConfiguration(const QSslConfiguration &configuration)

Passes a configuration with the user's desired TLS configuration. If you don't have the TLS security feature this may not be called.

See also sslConfiguration(), SecurityFeature, and securityFeatures.

void QNetworkAccessBackend::setUrl(const QUrl &url)

Sets the URL of the reply. This could e.g. be needed if a redirect or similar was performed.

See also url().

[virtual] QSslConfiguration QNetworkAccessBackend::sslConfiguration() const

Override this and return the QSslConfiguration used if you have the TLS security feature

See also setSslConfiguration(), SecurityFeature, and securityFeatures.

[virtual] bool QNetworkAccessBackend::start()

Prepares the backend and calls open(). E.g. for TargetType::Networked it will prepare proxyList().

See also TargetType and targetTypes.

[noexcept] TargetTypes QNetworkAccessBackend::targetTypes() const

Returns the TargetTypes that the backend claims to target.

See also TargetType.

QIODevice *QNetworkAccessBackend::uploadByteDevice()

Returns the upload byte device associated with the current request. This does not create the request but simply returns the pointer stored in this base class so it doesn't need to be stored in the subclass too.

QUrl QNetworkAccessBackend::url() const

Returns the current URL of the reply

See also setUrl().

[virtual] bool QNetworkAccessBackend::wantToRead()

This is called before we read if there are no bytes available and we are ready to read more. Return true if new data was made available.

See also read and readPointer.