CopperSpice API  1.8.2
QNetworkProxyFactory Class Referenceabstract

Provides the ability to select a proxy. More...

Inherited by QSystemConfigurationProxyFactory

Public Methods

 QNetworkProxyFactory ()
virtual ~QNetworkProxyFactory ()
virtual QList< QNetworkProxyqueryProxy (const QNetworkProxyQuery &query=QNetworkProxyQuery ()) = 0

Static Public Methods

static QList< QNetworkProxyproxyForQuery (const QNetworkProxyQuery &query)
static void setApplicationProxyFactory (QNetworkProxyFactory *factory)
static void setUseSystemConfiguration (bool enable)
static QList< QNetworkProxysystemProxyForQuery (const QNetworkProxyQuery &query=QNetworkProxyQuery ())

Detailed Description

The QNetworkProxyFactory class provides the ability to select a proxy. This class is an extension to QNetworkProxy which allows applications to have a more control over which proxy servers are used, depending on the socket requesting the proxy. With this class an application can apply different settings according to the protocol or destination hostname.

QNetworkProxyFactory can be set globally for the entire application in which case it will override any global proxies set with QNetworkProxy::setApplicationProxy(). In addition any sockets created with CopperSpice will query the factory to determine the proxy to be used.

A factory can also be set for classes which support multiple connections, such as QNetworkAccessManager. When this is done the factory will be queried for sockets created by that object.

System Proxies

You can configure a factory to use the system proxy's settings. Call the setUseSystemConfiguration() function with true to enable this behavior, or false to disable it. Similarly, you can use a factory to make queries directly to the system proxy by calling its systematization() function.

Depending on the configuration of the user's system, the use of system proxy features on certain platforms may be subject to limitations. The systemProxyForQuery() documentation contains a list of these limitations for those platforms that are affected.
See also
QNetworkProxy::setApplicationProxy(), QAbstractSocket::proxy(), QAbstractSocket::setProxy()

Constructor & Destructor Documentation

QNetworkProxyFactory::QNetworkProxyFactory ( )

Creates a QNetworkProxyFactory object.

Since QNetworkProxyFactory is an abstract class, you can not create objects of type QNetworkProxyFactory directly.

QNetworkProxyFactory::~QNetworkProxyFactory ( )

Destroys the QNetworkProxyFactory object.

Method Documentation

QList< QNetworkProxy > QNetworkProxyFactory::proxyForQuery ( const QNetworkProxyQuery query)

This function takes the query request, query, examines the details of the type of socket or request and returns a list of QNetworkProxy objects that indicate the proxy servers to be used, in order of preference.

QList< QNetworkProxy > QNetworkProxyFactory::queryProxy ( const QNetworkProxyQuery query = QNetworkProxyQuery())
pure virtual

This function takes the query request, query, examines the details of the type of socket or request and returns a list of QNetworkProxy objects that indicate the proxy servers to be used, in order of preference.

When reimplementing this class, take care to return at least one element.

If you can not determine a better proxy alternative, use QNetworkProxy::DefaultProxy, which tells the code querying for a proxy to use a higher alternative. For example, if this factory is set to a QNetworkAccessManager object, DefaultProxy will tell it to query the application-level proxy settings.

If this factory is set as the application proxy factory, DefaultProxy and NoProxy will have the same meaning.

void QNetworkProxyFactory::setApplicationProxyFactory ( QNetworkProxyFactory *  factory)

Sets the application-wide proxy factory to be factory. This function will take ownership of that object and will delete it when necessary.

The application-wide proxy is used as a last-resort when all other proxy selection requests returned QNetworkProxy::DefaultProxy. For example, QTcpSocket objects can have a proxy set with QTcpSocket::setProxy, but if none is set, the proxy factory class set with this function will be queried.

If you set a proxy factory with this function, any application level proxies set with QNetworkProxy::setApplicationProxy will be overridden.

See also
QNetworkProxy::setApplicationProxy(), QAbstractSocket::proxy(), QAbstractSocket::setProxy()
void QNetworkProxyFactory::setUseSystemConfiguration ( bool  enable)

Enables the use of the platform-specific proxy settings, and only those. See systemProxyForQuery() for more information.

Internally, this method (when called with enable set to true) sets an application-wide proxy factory. For this reason, this method is mutually exclusive with setApplicationProxyFactory(): calling setApplicationProxyFactory() overrides the use of the system-wide proxy, and calling setUseSystemConfiguration() overrides any application proxy or proxy factory that was previously set.

See the systemProxyForQuery() documentation for a list of limitations related to the use of system proxies.
QList< QNetworkProxy > QNetworkProxyFactory::systemProxyForQuery ( const QNetworkProxyQuery query = QNetworkProxyQuery())

This function takes the query request, query, examines the details of the type of socket or request and returns a list of QNetworkProxy objects that indicate the proxy servers to be used, in order of preference.

This function can be used to determine the platform-specific proxy settings. This function will use the libraries provided by the operating system to determine the proxy for a given connection, if such libraries exist. If they do not, this function will just return a QNetworkProxy of type QNetworkProxy::NoProxy.

On Windows, this function will use the WinHTTP DLL functions. Despite its name, Microsoft suggests using it for all applications that require network connections, not just HTTP. This will respect the proxy settings set on the registry with the proxycfg.exe tool. If those settings are not found, this function will attempt to obtain Internet Explorer's settings and use them.

On MacOS X this method will obtain the proxy settings using the SystemConfiguration framework from Apple. It will apply the FTP, HTTP and HTTPS proxy configurations for queries that contain the protocol tag "ftp", "http" and "https", respectively. If the SOCKS proxy is enabled in that configuration, this function will use the SOCKS server for all queries. If SOCKS is not enabled, it will use the HTTPS proxy for all TcpSocket and UrlRequest queries.

On other systems this method will pick up proxy settings from the "http_proxy" environment variable. This variable must be a URL using one of the following schemes: "http", "socks5" or "socks5h".


These are the limitations for the current version of this function.

  • On MacOS X this function will ignore the Proxy Auto Configuration settings, since it can not execute the associated ECMAScript code.
  • On Windows this function may take several seconds to execute depending on the configuration of the user's system.