QNetworkProxyFactory Class Reference

The QNetworkProxyFactory class provides fine-grained proxy selection. More...

#include <qnetworkproxy.h>

Inheritance diagram for QNetworkProxyFactory:

Public Functions
	QNetworkProxyFactory ()
	Creates a QNetworkProxyFactory object. More...
virtual QList< QNetworkProxy >	queryProxy (const QNetworkProxyQuery &query=QNetworkProxyQuery())=0
	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. More...
virtual	~QNetworkProxyFactory ()
	Destroys the QNetworkProxyFactory object. More...

Static Public Functions
static QList< QNetworkProxy >	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. More...
static void	setApplicationProxyFactory (QNetworkProxyFactory *factory)
	Sets the application-wide proxy factory to be factory. More...
static void	setUseSystemConfiguration (bool enable)
	Enables the use of the platform-specific proxy settings, and only those. More...
static QList< QNetworkProxy >	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. More...

Detailed Description

The QNetworkProxyFactory class provides fine-grained proxy selection.

Since

4.5

Attention

Module: QtNetwork

QNetworkProxyFactory is an extension to QNetworkProxy, allowing applications to have a more fine-grained control over which proxy servers are used, depending on the socket requesting the proxy. This allows an application to apply different settings, according to the protocol or destination hostname, for instance.

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

A factory can also be set in certain frameworks that support multiple connections, such as QNetworkAccessManager. When set on such object, the factory will be queried for sockets created by that framework only.

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 systemProxyForQuery() function.

Warning

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.

Definition at line 182 of file qnetworkproxy.h.

Constructors and Destructors

QNetworkProxyFactory()

QNetworkProxyFactory::QNetworkProxyFactory

(

)

Creates a QNetworkProxyFactory object.

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

Definition at line 1337 of file qnetworkproxy.cpp.

{
}

~QNetworkProxyFactory()

QNetworkProxyFactory::~QNetworkProxyFactory ( )

virtual

Destroys the QNetworkProxyFactory object.

Definition at line 1344 of file qnetworkproxy.cpp.

{
}

Functions

proxyForQuery()

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

static

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.

Definition at line 1492 of file qnetworkproxy.cpp.

Referenced by QNetworkAccessManagerPrivate::queryProxy(), QAbstractSocketPrivate::resolveProxy(), and QTcpServerPrivate::resolveProxy().

{
    if (!globalNetworkProxy())
        return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);
    return globalNetworkProxy()->proxyForQuery(query);
}

queryProxy()

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

Implemented in Maemo::NetworkProxyFactory, and QSystemConfigurationProxyFactory.

Referenced by QGlobalNetworkProxy::proxyForQuery(), and QNetworkAccessManagerPrivate::queryProxy().

setApplicationProxyFactory()

void QNetworkProxyFactory::setApplicationProxyFactory ( QNetworkProxyFactory *  factory )

static

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()

Definition at line 1395 of file qnetworkproxy.cpp.

Referenced by Maemo::ProxyConf::clear(), and Maemo::ProxyConf::update().

{
    if (globalNetworkProxy())
        globalNetworkProxy()->setApplicationProxyFactory(factory);
}

setUseSystemConfiguration()

void QNetworkProxyFactory::setUseSystemConfiguration ( bool  enable )

static

Enables the use of the platform-specific proxy settings, and only those.

Since

4.6

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.

Note

See the systemProxyForQuery() documentation for a list of limitations related to the use of system proxies.

Definition at line 1368 of file qnetworkproxy.cpp.

{
    if (enable) {
        setApplicationProxyFactory(new QSystemConfigurationProxyFactory);
    } else {
        setApplicationProxyFactory(0);
    }
}

systemProxyForQuery()

QList< QNetworkProxy > QNetworkProxyFactory::systemProxyForQuery ( const QNetworkProxyQuery &  query = QNetworkProxyQuery() )

static

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 don't, 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 function 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 isn't enabled, it will use the HTTPS proxy for all TcpSocket and UrlRequest queries.

On BlackBerry, this function obtains proxy settings for the default configuration using system configuration. The type will be set based on protocol tag "http", "https", "ftp", respectively. By default, it assumes http type. Proxy username and password are also set during the query using system configuration.

On other systems, this function 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".

Limitations

These are the limitations for the current version of this function. Future versions of Qt may lift some of the limitations listed here.

• On MacOS X, this function will ignore the Proxy Auto Configuration settings, since it cannot execute the associated ECMAScript code.

• On Windows platforms, this function may take several seconds to execute depending on the configuration of the user's system.

  • On BlackBerry, only UrlRequest and TcpSocket queries are supported. SOCKS is not supported. The proxy credentials are only retrieved for the default configuration.

Some notes about the code:

** It is assumed that the system proxies are for url based requests ie. HTTP/HTTPS based.

Definition at line 63 of file qnetworkproxy_blackberry.cpp.

Referenced by QWindowsSystemProxy::init(), macQueryInternal(), and QSystemConfigurationProxyFactory::queryProxy().

{
    if (query.url().scheme() == QLatin1String("file")
            || query.url().scheme() == QLatin1String("qrc"))
        return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);

    if (query.queryType() != QNetworkProxyQuery::UrlRequest
            && query.queryType() != QNetworkProxyQuery::TcpSocket) {
        qWarning("Unsupported query type: %d", query.queryType());
        return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);
    }

    QUrl url;
    if (query.queryType() == QNetworkProxyQuery::UrlRequest) {
        url = query.url();
    } else if (query.queryType() == QNetworkProxyQuery::TcpSocket
               && !query.peerHostName().isEmpty()) {
        url.setHost(query.peerHostName());
        switch (query.peerPort()) {
        case 443:
            url.setScheme(QLatin1String("https"));
            break;
        case 21:
            url.setScheme(QLatin1String("ftp"));
            break;
        default:
            // for unknown ports, we just pretend we are dealing
            // with a HTTP URL, otherwise we will not get a proxy
            // from the netstatus API
            url.setScheme(QLatin1String("http"));
        }
    }

    if (!url.isValid()) {
        qWarning("Invalid URL: %s", qPrintable(url.toString()));
        return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);
    }

    netstatus_proxy_details_t details;
    memset(&details, 0, sizeof(netstatus_proxy_details_t));

#if BPS_VERSION >= 3001001

    QByteArray bUrl(url.toEncoded());
    QString sInterface(query.networkConfiguration().name());
    QByteArray bInterface;
    if (!sInterface.isEmpty()) {
        if (query.networkConfiguration().type() != QNetworkConfiguration::InternetAccessPoint) {
            qWarning("Unsupported configuration type: %d", query.networkConfiguration().type());
            return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);
        }
        bInterface = sInterface.toUtf8();
    }

    if (netstatus_get_proxy_details_for_url(bUrl.constData(), (bInterface.isEmpty() ? NULL : bInterface.constData()), &details) != BPS_SUCCESS) {
        qWarning("netstatus_get_proxy_details_for_url failed! errno: %d", errno);
        return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);
    }

#else

    if (netstatus_get_proxy_details(&details) != BPS_SUCCESS) {
        qWarning("netstatus_get_proxy_details failed! errno: %d", errno);
        return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);
    }

#endif

    if (details.http_proxy_host == NULL) { // No proxy
        netstatus_free_proxy_details(&details);
        return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);
    }

    QNetworkProxy proxy;

    QString protocol = query.protocolTag();
    if (protocol.startsWith(QLatin1String("http"), Qt::CaseInsensitive)) { // http, https
        proxy.setType((QNetworkProxy::HttpProxy));
    } else if (protocol == QLatin1String("ftp")) {
        proxy.setType(QNetworkProxy::FtpCachingProxy);
    } else { // assume http proxy
        qDebug("Proxy type: %s assumed to be http proxy", qPrintable(protocol));
        proxy.setType((QNetworkProxy::HttpProxy));
    }

    // Set host
    // Note: ftp and https proxy type fields *are* obsolete.
    // The user interface allows only one host/port which gets duplicated
    // to all proxy type fields.
    proxy.setHostName(QString::fromUtf8(details.http_proxy_host));

    // Set port
    proxy.setPort(details.http_proxy_port);

    // Set username
    if (details.http_proxy_login_user)
        proxy.setUser(QString::fromUtf8(details.http_proxy_login_user));

    // Set password
    if (details.http_proxy_login_password)
        proxy.setPassword(QString::fromUtf8(details.http_proxy_login_password));

    netstatus_free_proxy_details(&details);

    return QList<QNetworkProxy>() << proxy;
}

---

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

• /src/network/kernel/qnetworkproxy.h
• /src/network/kernel/qnetworkproxy.cpp
• /src/network/kernel/qnetworkproxy_blackberry.cpp
• /src/network/kernel/qnetworkproxy_generic.cpp
• /src/network/kernel/qnetworkproxy_mac.cpp
• /src/network/kernel/qnetworkproxy_win.cpp