QGIS API Documentation  3.21.0-Master (909859188c)
Signals | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
QgsNetworkAccessManager Class Reference

network access manager for QGIS More...

#include <qgsnetworkaccessmanager.h>

Inheritance diagram for QgsNetworkAccessManager:
Inheritance graph
[legend]

Signals

void authBrowserAborted ()
 Emitted when external browser logins are to be aborted. More...
 
void cookiesChanged (const QList< QNetworkCookie > &cookies)
 Emitted when the cookies changed. More...
 
void downloadProgress (int requestId, qint64 bytesReceived, qint64 bytesTotal)
 Emitted when a network reply receives a progress report. More...
 
void finished (QgsNetworkReplyContent reply)
 Emitted whenever a pending network reply is finished. More...
 
void requestAboutToBeCreated (QgsNetworkRequestParameters request)
 Emitted when a network request is about to be created. More...
 
Q_DECL_DEPRECATED void requestAboutToBeCreated (QNetworkAccessManager::Operation, const QNetworkRequest &, QIODevice *)
 
void requestAuthDetailsAdded (int requestId, const QString &realm, const QString &user, const QString &password)
 Emitted when network authentication details have been added to a request. More...
 
Q_DECL_DEPRECATED void requestCreated (QNetworkReply *)
 
void requestEncounteredSslErrors (int requestId, const QList< QSslError > &errors)
 Emitted when a network request encounters SSL errors. More...
 
void requestRequiresAuth (int requestId, const QString &realm)
 Emitted when a network request prompts an authentication request. More...
 
void requestTimedOut (QgsNetworkRequestParameters request)
 Emitted when a network request has timed out. More...
 
void requestTimedOut (QNetworkReply *)
 

Public Member Functions

 QgsNetworkAccessManager (QObject *parent=nullptr)
 
void abortAuthBrowser ()
 Abort any outstanding external browser login request. More...
 
bool cacheDisabled () const
 Returns true if all network caching is disabled. More...
 
QStringList excludeList () const
 Returns the proxy exclude list. More...
 
const QNetworkProxy & fallbackProxy () const
 Returns the fallback proxy used by the manager. More...
 
void insertProxyFactory (QNetworkProxyFactory *factory)
 Inserts a factory into the proxy factories list. More...
 
QStringList noProxyList () const
 Returns the no proxy list. More...
 
void preprocessRequest (QNetworkRequest *req) const
 Preprocesses request. More...
 
const QList< QNetworkProxyFactory * > proxyFactories () const
 Returns a list of proxy factories used by the manager. More...
 
void removeProxyFactory (QNetworkProxyFactory *factory)
 Removes a factory from the proxy factories list. More...
 
void requestAuthCloseBrowser () const
 Forwards an external browser login closure request to the authentication handler. More...
 
void requestAuthOpenBrowser (const QUrl &url) const
 Forwards an external browser login url opening request to the authentication handler. More...
 
void setAuthHandler (std::unique_ptr< QgsNetworkAuthenticationHandler > handler)
 Sets the application network authentication handler, which is used to respond to network authentication prompts during network requests. More...
 
void setCacheDisabled (bool disabled)
 Sets whether all network caching should be disabled. More...
 
void setFallbackProxyAndExcludes (const QNetworkProxy &proxy, const QStringList &excludes, const QStringList &noProxyURLs)
 Sets the fallback proxy and URLs which shouldn't use it. More...
 
void setSslErrorHandler (std::unique_ptr< QgsSslErrorHandler > handler)
 Sets the application SSL error handler, which is used to respond to SSL errors encountered during network requests. More...
 
void setupDefaultProxyAndCache (Qt::ConnectionType connectionType=Qt::BlockingQueuedConnection)
 Setup the QgsNetworkAccessManager (NAM) according to the user's settings. More...
 
bool useSystemProxy () const
 Returns whether the system proxy should be used. More...
 

Static Public Member Functions

static QgsNetworkReplyContent blockingGet (QNetworkRequest &request, const QString &authCfg=QString(), bool forceRefresh=false, QgsFeedback *feedback=nullptr)
 Posts a GET request to obtain the contents of the target request and returns a new QgsNetworkReplyContent object for reading. More...
 
static QgsNetworkReplyContent blockingPost (QNetworkRequest &request, const QByteArray &data, const QString &authCfg=QString(), bool forceRefresh=false, QgsFeedback *feedback=nullptr)
 Posts a POST request to obtain the contents of the target request, using the given data, and returns a new QgsNetworkReplyContent object for reading. More...
 
static QNetworkRequest::CacheLoadControl cacheLoadControlFromName (const QString &name)
 Returns QNetworkRequest::CacheLoadControl from a name. More...
 
static QString cacheLoadControlName (QNetworkRequest::CacheLoadControl control)
 Returns the name for QNetworkRequest::CacheLoadControl. More...
 
static QgsNetworkAccessManagerinstance (Qt::ConnectionType connectionType=Qt::BlockingQueuedConnection)
 Returns a pointer to the active QgsNetworkAccessManager for the current thread. More...
 
static bool removeRequestPreprocessor (const QString &id)
 Removes the custom pre-processor function with matching id. More...
 
static QString setRequestPreprocessor (const std::function< void(QNetworkRequest *request)> &processor)
 Sets a request pre-processor function, which allows manipulation of a network request before it is processed. More...
 
static void setTimeout (int time)
 Sets the maximum timeout time for network requests, in milliseconds. More...
 
static int timeout ()
 Returns the network timeout length, in milliseconds. More...
 

Static Public Attributes

static const QgsSettingsEntryInteger settingsNetworkTimeout = QgsSettingsEntryInteger( QStringLiteral( "/qgis/networkAndProxy/networkTimeout" ), QgsSettings::NoSection, 60000, QObject::tr( "Network timeout" ) )
 Settings entry network timeout. More...
 

Protected Member Functions

QNetworkReply * createRequest (QNetworkAccessManager::Operation op, const QNetworkRequest &req, QIODevice *outgoingData=nullptr) override
 

Detailed Description

network access manager for QGIS

This class implements the QGIS network access manager. It's a singleton that can be used across QGIS.

Plugins can insert proxy factories and thereby redirect requests to individual proxies.

If no proxy factories are there or none returns a proxy for an URL a fallback proxy can be set. There's also a exclude list that defines URLs that the fallback proxy should not be used for, then no proxy will be used.

Since
1.5

Definition at line 268 of file qgsnetworkaccessmanager.h.

Constructor & Destructor Documentation

◆ QgsNetworkAccessManager()

QgsNetworkAccessManager::QgsNetworkAccessManager ( QObject *  parent = nullptr)

Definition at line 218 of file qgsnetworkaccessmanager.cpp.

Member Function Documentation

◆ abortAuthBrowser()

void QgsNetworkAccessManager::abortAuthBrowser ( )

Abort any outstanding external browser login request.

Note
Background threads will listen to aborted browser request signals from the network manager on the main thread.
Since
QGIS 3.20

Definition at line 574 of file qgsnetworkaccessmanager.cpp.

◆ authBrowserAborted

void QgsNetworkAccessManager::authBrowserAborted ( )
signal

Emitted when external browser logins are to be aborted.

Since
QGIS 3.20

◆ blockingGet()

QgsNetworkReplyContent QgsNetworkAccessManager::blockingGet ( QNetworkRequest &  request,
const QString &  authCfg = QString(),
bool  forceRefresh = false,
QgsFeedback feedback = nullptr 
)
static

Posts a GET request to obtain the contents of the target request and returns a new QgsNetworkReplyContent object for reading.

The current thread will be blocked until the request is returned.

This method is safe to call in either the main thread or a worker thread.

If forceRefresh is false then previously cached replies may be used for the request. If it is set to true then a new query is always performed.

If an authCfg has been specified, then that authentication configuration required will automatically be applied to request. There is no need to manually apply the authentication to the request prior to calling this method.

The optional feedback argument can be used to abort ongoing requests.

The contents of the reply will be returned after the request is completed or an error occurs.

See also
blockingPost()
Since
QGIS 3.6

Definition at line 801 of file qgsnetworkaccessmanager.cpp.

◆ blockingPost()

QgsNetworkReplyContent QgsNetworkAccessManager::blockingPost ( QNetworkRequest &  request,
const QByteArray &  data,
const QString &  authCfg = QString(),
bool  forceRefresh = false,
QgsFeedback feedback = nullptr 
)
static

Posts a POST request to obtain the contents of the target request, using the given data, and returns a new QgsNetworkReplyContent object for reading.

The current thread will be blocked until the request is returned.

This method is safe to call in either the main thread or a worker thread.

If forceRefresh is false then previously cached replies may be used for the request. If it is set to true then a new query is always performed.

If an authCfg has been specified, then that authentication configuration required will automatically be applied to request. There is no need to manually apply the authentication to the request prior to calling this method.

The optional feedback argument can be used to abort ongoing requests.

The contents of the reply will be returned after the request is completed or an error occurs.

See also
blockingGet()
Since
QGIS 3.6

Definition at line 809 of file qgsnetworkaccessmanager.cpp.

◆ cacheDisabled()

bool QgsNetworkAccessManager::cacheDisabled ( ) const
inline

Returns true if all network caching is disabled.

See also
setCacheDisabled()
Note
Not available in Python bindings.
Since
QGIS 3.18

Definition at line 438 of file qgsnetworkaccessmanager.h.

◆ cacheLoadControlFromName()

QNetworkRequest::CacheLoadControl QgsNetworkAccessManager::cacheLoadControlFromName ( const QString &  name)
static

Returns QNetworkRequest::CacheLoadControl from a name.

See also
cacheLoadControlName()

Definition at line 608 of file qgsnetworkaccessmanager.cpp.

◆ cacheLoadControlName()

QString QgsNetworkAccessManager::cacheLoadControlName ( QNetworkRequest::CacheLoadControl  control)
static

Returns the name for QNetworkRequest::CacheLoadControl.

See also
cacheLoadControlFromName()

Definition at line 592 of file qgsnetworkaccessmanager.cpp.

◆ cookiesChanged

void QgsNetworkAccessManager::cookiesChanged ( const QList< QNetworkCookie > &  cookies)
signal

Emitted when the cookies changed.

Since
QGIS 3.22

◆ createRequest()

QNetworkReply * QgsNetworkAccessManager::createRequest ( QNetworkAccessManager::Operation  op,
const QNetworkRequest &  req,
QIODevice *  outgoingData = nullptr 
)
overrideprotected

Definition at line 299 of file qgsnetworkaccessmanager.cpp.

◆ downloadProgress

void QgsNetworkAccessManager::downloadProgress ( int  requestId,
qint64  bytesReceived,
qint64  bytesTotal 
)
signal

Emitted when a network reply receives a progress report.

The requestId argument reflects the unique ID identifying the original request which the progress report relates to.

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, bytesTotal will be -1.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread's signal in order to receive notifications about requests created in any thread.

Since
QGIS 3.6

◆ excludeList()

QStringList QgsNetworkAccessManager::excludeList ( ) const

Returns the proxy exclude list.

This list consists of the beginning of URL strings which will not use the fallback proxy.

See also
noProxyList()
fallbackProxy()
setFallbackProxyAndExcludes()

Definition at line 252 of file qgsnetworkaccessmanager.cpp.

◆ fallbackProxy()

const QNetworkProxy & QgsNetworkAccessManager::fallbackProxy ( ) const

Returns the fallback proxy used by the manager.

The fallback proxy is used for URLs which no other proxy factory returned proxies for.

See also
proxyFactories()
setFallbackProxyAndExcludes()

Definition at line 262 of file qgsnetworkaccessmanager.cpp.

◆ finished

void QgsNetworkAccessManager::finished ( QgsNetworkReplyContent  reply)
signal

Emitted whenever a pending network reply is finished.

The reply parameter will contain a QgsNetworkReplyContent object, containing all the useful information relating to the reply, including headers and reply content.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread's signal in order to receive notifications about requests created in any thread.

See also
requestAboutToBeCreated( QgsNetworkRequestParameters )
requestTimedOut( QgsNetworkRequestParameters )
Since
QGIS 3.6

◆ insertProxyFactory()

void QgsNetworkAccessManager::insertProxyFactory ( QNetworkProxyFactory *  factory)

Inserts a factory into the proxy factories list.

Ownership of factory is transferred to the manager.

See also
removeProxyFactory()
proxyFactories()

Definition at line 237 of file qgsnetworkaccessmanager.cpp.

◆ instance()

QgsNetworkAccessManager * QgsNetworkAccessManager::instance ( Qt::ConnectionType  connectionType = Qt::BlockingQueuedConnection)
static

Returns a pointer to the active QgsNetworkAccessManager for the current thread.

With the connectionType parameter it is possible to setup the default connection type that is used to handle signals that might require user interaction and therefore need to be handled on the main thread. See in-depth discussion below.

Parameters
connectionTypeIn most cases the default of using a Qt::BlockingQueuedConnection is ok, to make a background thread wait for the main thread to answer such a request is fine and anything else is dangerous. However, in case the request was started on the main thread, one should execute a local event loop in a helper thread and freeze the main thread for the duration of the download. In this case, if an authentication request is sent from the background thread network access manager, the background thread should be blocked, the main thread be woken up, processEvents() executed once, the main thread frozen again and the background thread continued.

Definition at line 201 of file qgsnetworkaccessmanager.cpp.

◆ noProxyList()

QStringList QgsNetworkAccessManager::noProxyList ( ) const

Returns the no proxy list.

This list consists of the beginning of URL strings which will not use any proxy at all

See also
excludeList()
fallbackProxy()
setFallbackProxyAndExcludes()

Definition at line 257 of file qgsnetworkaccessmanager.cpp.

◆ preprocessRequest()

void QgsNetworkAccessManager::preprocessRequest ( QNetworkRequest *  req) const

Preprocesses request.

Parameters
reqthe request to preprocess
Since
QGIS 3.22

Definition at line 834 of file qgsnetworkaccessmanager.cpp.

◆ proxyFactories()

const QList< QNetworkProxyFactory * > QgsNetworkAccessManager::proxyFactories ( ) const

Returns a list of proxy factories used by the manager.

See also
insertProxyFactory()
proxyFactories()

Definition at line 247 of file qgsnetworkaccessmanager.cpp.

◆ removeProxyFactory()

void QgsNetworkAccessManager::removeProxyFactory ( QNetworkProxyFactory *  factory)

Removes a factory from the proxy factories list.

See also
insertProxyFactory()
proxyFactories()

Definition at line 242 of file qgsnetworkaccessmanager.cpp.

◆ removeRequestPreprocessor()

bool QgsNetworkAccessManager::removeRequestPreprocessor ( const QString &  id)
static

Removes the custom pre-processor function with matching id.

The id must correspond to a pre-processor previously added via a call to setRequestPreprocessor().

Returns true if processor existed and was removed.

See also
setRequestPreprocessor()
Since
QGIS 3.22

Definition at line 824 of file qgsnetworkaccessmanager.cpp.

◆ requestAboutToBeCreated [1/2]

void QgsNetworkAccessManager::requestAboutToBeCreated ( QgsNetworkRequestParameters  request)
signal

Emitted when a network request is about to be created.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread's signal in order to receive notifications about requests created in any thread.

See also
finished( QgsNetworkReplyContent )
requestTimedOut( QgsNetworkRequestParameters )
Since
QGIS 3.6

◆ requestAboutToBeCreated [2/2]

Q_DECL_DEPRECATED void QgsNetworkAccessManager::requestAboutToBeCreated ( QNetworkAccessManager::Operation  ,
const QNetworkRequest &  ,
QIODevice *   
)
signal

◆ requestAuthCloseBrowser()

void QgsNetworkAccessManager::requestAuthCloseBrowser ( ) const

Forwards an external browser login closure request to the authentication handler.

Note
If called by a background thread, the request will be forwarded to the network manager on the main thread.
Since
QGIS 3.20

Definition at line 563 of file qgsnetworkaccessmanager.cpp.

◆ requestAuthDetailsAdded

void QgsNetworkAccessManager::requestAuthDetailsAdded ( int  requestId,
const QString &  realm,
const QString &  user,
const QString &  password 
)
signal

Emitted when network authentication details have been added to a request.

The requestId argument reflects the unique ID identifying the original request which the authentication relates to.

This signal is always sent from the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread's signal in order to receive notifications about authentication requests from any thread.

This signal is for debugging and logging purposes only, and should not be used to respond to the requests. See QgsNetworkAuthenticationHandler for details on how to handle authentication requests.

See also
requestRequiresAuth()
Since
QGIS 3.6

◆ requestAuthOpenBrowser()

void QgsNetworkAccessManager::requestAuthOpenBrowser ( const QUrl &  url) const

Forwards an external browser login url opening request to the authentication handler.

Note
If called by a background thread, the request will be forwarded to the network manager on the main thread.
Since
QGIS 3.20

Definition at line 552 of file qgsnetworkaccessmanager.cpp.

◆ requestCreated

Q_DECL_DEPRECATED void QgsNetworkAccessManager::requestCreated ( QNetworkReply *  )
signal

◆ requestEncounteredSslErrors

void QgsNetworkAccessManager::requestEncounteredSslErrors ( int  requestId,
const QList< QSslError > &  errors 
)
signal

Emitted when a network request encounters SSL errors.

The requestId argument reflects the unique ID identifying the original request which the SSL error relates to.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread's signal in order to receive notifications about SSL errors from any thread.

This signal is for debugging and logging purposes only, and cannot be used to respond to the errors. See QgsSslErrorHandler for details on how to handle SSL errors and potentially ignore them.

Since
QGIS 3.6

◆ requestRequiresAuth

void QgsNetworkAccessManager::requestRequiresAuth ( int  requestId,
const QString &  realm 
)
signal

Emitted when a network request prompts an authentication request.

The requestId argument reflects the unique ID identifying the original request which the authentication relates to.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread's signal in order to receive notifications about authentication requests from any thread.

This signal is for debugging and logging purposes only, and cannot be used to respond to the requests. See QgsNetworkAuthenticationHandler for details on how to handle authentication requests.

See also
requestAuthDetailsAdded()
Since
QGIS 3.6

◆ requestTimedOut [1/2]

void QgsNetworkAccessManager::requestTimedOut ( QgsNetworkRequestParameters  request)
signal

Emitted when a network request has timed out.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread's signal in order to receive notifications about requests created in any thread.

See also
requestAboutToBeCreated( QgsNetworkRequestParameters )
finished( QgsNetworkReplyContent )
Since
QGIS 3.6

◆ requestTimedOut [2/2]

void QgsNetworkAccessManager::requestTimedOut ( QNetworkReply *  )
signal

◆ setAuthHandler()

void QgsNetworkAccessManager::setAuthHandler ( std::unique_ptr< QgsNetworkAuthenticationHandler handler)

Sets the application network authentication handler, which is used to respond to network authentication prompts during network requests.

Ownership of handler is transferred to the main thread QgsNetworkAccessManager instance.

This method must ONLY be called on the main thread QgsNetworkAccessManager. It is not necessary to set handlers for background threads – the main thread QgsNetworkAuthenticationHandler will automatically be used in a thread-safe manner for any authentication requests encountered on background threads.

The default QgsNetworkAuthenticationHandler responds to request only by logging the request, but does not provide any username or password resolution.

Note
Not available in Python bindings.
Since
QGIS 3.6

Definition at line 231 of file qgsnetworkaccessmanager.cpp.

◆ setCacheDisabled()

void QgsNetworkAccessManager::setCacheDisabled ( bool  disabled)
inline

Sets whether all network caching should be disabled.

If disabled is true then all caching will be disabled, causing all requests to be retrieved from the network regardless of the request's attributes.

See also
cacheDisabled()
Note
Not available in Python bindings.
Since
QGIS 3.18

Definition at line 450 of file qgsnetworkaccessmanager.h.

◆ setFallbackProxyAndExcludes()

void QgsNetworkAccessManager::setFallbackProxyAndExcludes ( const QNetworkProxy &  proxy,
const QStringList &  excludes,
const QStringList &  noProxyURLs 
)

Sets the fallback proxy and URLs which shouldn't use it.

The fallback proxy is used for URLs which no other proxy factory returned proxies for. The excludes list specifies the beginning of URL strings which will not use this fallback proxy. The noProxyURLs list specifies the beginning of URL strings which will not use any proxy at all

See also
fallbackProxy()
excludeList()
noProxyList()

Definition at line 267 of file qgsnetworkaccessmanager.cpp.

◆ setRequestPreprocessor()

QString QgsNetworkAccessManager::setRequestPreprocessor ( const std::function< void(QNetworkRequest *request)> &  processor)
static

Sets a request pre-processor function, which allows manipulation of a network request before it is processed.

The processor function takes the QNetworkRequest as its argument, and can mutate the request if necessary.

Returns
An auto-generated string uniquely identifying the preprocessor, which can later be used to remove the preprocessor (via a call to removeRequestPreprocessor()).
See also
removeRequestPreprocessor()
Since
QGIS 3.22

Definition at line 817 of file qgsnetworkaccessmanager.cpp.

◆ setSslErrorHandler()

void QgsNetworkAccessManager::setSslErrorHandler ( std::unique_ptr< QgsSslErrorHandler handler)

Sets the application SSL error handler, which is used to respond to SSL errors encountered during network requests.

Ownership of handler is transferred to the main thread QgsNetworkAccessManager instance.

This method must ONLY be called on the main thread QgsNetworkAccessManager. It is not necessary to set handlers for background threads – the main thread QgsSslErrorHandler will automatically be used in a thread-safe manner for any SSL errors encountered on background threads.

The default QgsSslErrorHandler responds to SSL errors only by logging the errors, and uses the default Qt response, which is to abort the request.

Note
Not available in Python bindings.
Since
QGIS 3.6

Definition at line 225 of file qgsnetworkaccessmanager.cpp.

◆ setTimeout()

void QgsNetworkAccessManager::setTimeout ( int  time)
static

Sets the maximum timeout time for network requests, in milliseconds.

If set to 0, no timeout is set.

See also
timeout()
Since
QGIS 3.6

Definition at line 796 of file qgsnetworkaccessmanager.cpp.

◆ setupDefaultProxyAndCache()

void QgsNetworkAccessManager::setupDefaultProxyAndCache ( Qt::ConnectionType  connectionType = Qt::BlockingQueuedConnection)

Setup the QgsNetworkAccessManager (NAM) according to the user's settings.

The connectionType sets up the default connection type that is used to handle signals that might require user interaction and therefore need to be handled on the main thread. See in-depth discussion in the documentation for the constructor of this class.

Definition at line 629 of file qgsnetworkaccessmanager.cpp.

◆ timeout()

int QgsNetworkAccessManager::timeout ( )
static

Returns the network timeout length, in milliseconds.

See also
setTimeout()
Since
QGIS 3.6

Definition at line 791 of file qgsnetworkaccessmanager.cpp.

◆ useSystemProxy()

bool QgsNetworkAccessManager::useSystemProxy ( ) const
inline

Returns whether the system proxy should be used.

Definition at line 456 of file qgsnetworkaccessmanager.h.

Member Data Documentation

◆ settingsNetworkTimeout

const QgsSettingsEntryInteger QgsNetworkAccessManager::settingsNetworkTimeout = QgsSettingsEntryInteger( QStringLiteral( "/qgis/networkAndProxy/networkTimeout" ), QgsSettings::NoSection, 60000, QObject::tr( "Network timeout" ) )
inlinestatic

Settings entry network timeout.

Definition at line 611 of file qgsnetworkaccessmanager.h.


The documentation for this class was generated from the following files: