Qt 4.8
Public Types | Public Functions | Static Public Functions | Properties | List of all members
QNetworkProxy Class Reference

The QNetworkProxy class provides a network layer proxy. More...

#include <qnetworkproxy.h>

Public Types

enum  Capability {
  TunnelingCapability = 0x0001, ListeningCapability = 0x0002, UdpTunnelingCapability = 0x0004, CachingCapability = 0x0008,
  HostNameLookupCapability = 0x0010
}
 These flags indicate the capabilities that a given proxy server supports. More...
 
enum  ProxyType {
  DefaultProxy, Socks5Proxy, NoProxy, HttpProxy,
  HttpCachingProxy, FtpCachingProxy
}
 This enum describes the types of network proxying provided in Qt. More...
 

Public Functions

Capabilities capabilities () const
 Returns the capabilities of this proxy server. More...
 
QString hostName () const
 Returns the host name of the proxy host. More...
 
bool isCachingProxy () const
 Returns true if this proxy supports the QNetworkProxy::CachingCapability capability. More...
 
bool isTransparentProxy () const
 Returns true if this proxy supports transparent tunneling of TCP connections. More...
 
bool operator!= (const QNetworkProxy &other) const
 Compares the value of this network proxy to other and returns true if they differ. More...
 
QNetworkProxyoperator= (const QNetworkProxy &other)
 Assigns the value of the network proxy other to this network proxy. More...
 
bool operator== (const QNetworkProxy &other) const
 
QString password () const
 Returns the password used for authentication. More...
 
quint16 port () const
 Returns the port of the proxy host. More...
 
 QNetworkProxy ()
 Constructs a QNetworkProxy with DefaultProxy type; the proxy type is determined by applicationProxy(), which defaults to NoProxy. More...
 
 QNetworkProxy (ProxyType type, const QString &hostName=QString(), quint16 port=0, const QString &user=QString(), const QString &password=QString())
 Constructs a QNetworkProxy with type, hostName, port, user and password. More...
 
 QNetworkProxy (const QNetworkProxy &other)
 Constructs a copy of other. More...
 
void setCapabilities (Capabilities capab)
 Sets the capabilities of this proxy to capabilities. More...
 
void setHostName (const QString &hostName)
 Sets the host name of the proxy host to be hostName. More...
 
void setPassword (const QString &password)
 Sets the password for proxy authentication to be password. More...
 
void setPort (quint16 port)
 Sets the port of the proxy host to be port. More...
 
void setType (QNetworkProxy::ProxyType type)
 Sets the proxy type for this instance to be type. More...
 
void setUser (const QString &userName)
 Sets the user name for proxy authentication to be user. More...
 
QNetworkProxy::ProxyType type () const
 Returns the proxy type for this instance. More...
 
QString user () const
 Returns the user name used for authentication. More...
 
 ~QNetworkProxy ()
 Destroys the QNetworkProxy object. More...
 

Static Public Functions

static QNetworkProxy applicationProxy ()
 Returns the application level network proxying. More...
 
static void setApplicationProxy (const QNetworkProxy &proxy)
 Sets the application level network proxying to be networkProxy. More...
 

Properties

QSharedDataPointer< QNetworkProxyPrivated
 

Detailed Description

The QNetworkProxy class provides a network layer proxy.

Since
4.1
Note
This class or function is reentrant.
Attention
Module: QtNetwork

QNetworkProxy provides the method for configuring network layer proxy support to the Qt network classes. The currently supported classes are QAbstractSocket, QTcpSocket, QUdpSocket, QTcpServer, QNetworkAccessManager and QFtp. The proxy support is designed to be as transparent as possible. This means that existing network-enabled applications that you have written should automatically support network proxy using the following code.

proxy.setHostName("proxy.example.com");
proxy.setPort(1080);
proxy.setUser("username");
proxy.setPassword("password");

An alternative to setting an application wide proxy is to specify the proxy for individual sockets using QAbstractSocket::setProxy() and QTcpServer::setProxy(). In this way, it is possible to disable the use of a proxy for specific sockets using the following code:

serverSocket->setProxy(QNetworkProxy::NoProxy);

Network proxy is not used if the address used in QAbstractSocket::connectToHost() , QUdpSocket::bind() or QTcpServer::listen() is equivalent to QHostAddress::LocalHost or QHostAddress::LocalHostIPv6.

Each type of proxy support has certain restrictions associated with it. You should read the ProxyType documentation carefully before selecting a proxy type to use.

Note
Changes made to currently connected sockets do not take effect. If you need to change a connected socket, you should reconnect it.

SOCKS5

The SOCKS5 support in Qt 4 is based on RFC 1928 and RFC 1929. The supported authentication methods are no authentication and username/password authentication. Both IPv4 and IPv6 are supported. Domain names are resolved through the SOCKS5 server if the QNetworkProxy::HostNameLookupCapability is enabled, otherwise they are resolved locally and the IP address is sent to the server. There are several things to remember when using SOCKS5 with QUdpSocket and QTcpServer:

With QUdpSocket, a call to QUdpSocket::bind(){bind()} may fail with a timeout error. If a port number other than 0 is passed to QUdpSocket::bind(){bind()}, it is not guaranteed that it is the specified port that will be used. Use localPort() and localAddress() to get the actual address and port number in use. Because proxied UDP goes through two UDP connections, it is more likely that packets will be dropped.

With QTcpServer a call to listen() may fail with a timeout error. If a port number other than 0 is passed to listen(), then it is not guaranteed that it is the specified port that will be used. Use serverPort() and serverAddress() to get the actual address and port used to listen for connections. SOCKS5 only supports one accepted connection per call to listen(), and each call is likely to result in a different serverPort() being used.

See also
QAbstractSocket, QTcpServer

Definition at line 123 of file qnetworkproxy.h.

Enumerations

◆ Capability

These flags indicate the capabilities that a given proxy server supports.

Since
4.5

QNetworkProxy sets different capabilities by default when the object is created (see QNetworkProxy::ProxyType for a list of the defaults). However, it is possible to change the capabitilies after the object has been created with setCapabilities().

The capabilities that QNetworkProxy supports are:

  • TunnelingCapability Ability to open transparent, tunneled TCP connections to a remote host. The proxy server relays the transmission verbatim from one side to the other and does no caching.
  • ListeningCapability Ability to create a listening socket and wait for an incoming TCP connection from a remote host.
  • UdpTunnelingCapability Ability to relay UDP datagrams via the proxy server to and from a remote host.
  • CachingCapability Ability to cache the contents of the transfer. This capability is specific to each protocol and proxy type. For example, HTTP proxies can cache the contents of web data transferred with "GET" commands.
  • HostNameLookupCapability Ability to connect to perform the lookup on a remote host name and connect to it, as opposed to requiring the application to perform the name lookup and request connection to IP addresses only.
Enumerator
TunnelingCapability 
ListeningCapability 
UdpTunnelingCapability 
CachingCapability 
HostNameLookupCapability 

Definition at line 135 of file qnetworkproxy.h.

◆ ProxyType

This enum describes the types of network proxying provided in Qt.

There are two types of proxies that Qt understands: transparent proxies and caching proxies. The first group consists of proxies that can handle any arbitrary data transfer, while the second can only handle specific requests. The caching proxies only make sense for the specific classes where they can be used.

  • NoProxy No proxying is used
  • DefaultProxy Proxy is determined based on the application proxy set using setApplicationProxy()
  • Socks5Proxy Socks5 proxying is used
  • HttpProxy HTTP transparent proxying is used (This value was introduced in 4.3.)
  • HttpCachingProxy Proxying for HTTP requests only (This value was introduced in 4.4.)
  • FtpCachingProxy Proxying for FTP requests only (This value was introduced in 4.4.)

The table below lists different proxy types and their capabilities. Since each proxy type has different capabilities, it is important to understand them before choosing a proxy type.

Proxy type Description

Default capabilities

SOCKS 5 Generic proxy for any kind of connection. Supports TCP, UDP, binding to a port (incoming connections) and authentication.

TunnelingCapability, ListeningCapability, UdpTunnelingCapability, HostNameLookupCapability

HTTP Implemented using the "CONNECT" command, supports only outgoing TCP connections; supports authentication.

TunnelingCapability, CachingCapability, HostNameLookupCapability

Caching-only HTTP Implemented using normal HTTP commands, it is useful only in the context of HTTP requests (see QNetworkAccessManager)

CachingCapability, HostNameLookupCapability

Caching FTP Implemented using an FTP proxy, it is useful only in the context of FTP requests (see QFtp, QNetworkAccessManager)

CachingCapability, HostNameLookupCapability

Also note that you shouldn't set the application default proxy (setApplicationProxy()) to a proxy that doesn't have the TunnelingCapability capability. If you do, QTcpSocket will not know how to open connections.

See also
setType(), type(), capabilities(), setCapabilities()
Enumerator
DefaultProxy 
Socks5Proxy 
NoProxy 
HttpProxy 
HttpCachingProxy 
FtpCachingProxy 

Definition at line 126 of file qnetworkproxy.h.

Constructors and Destructors

◆ QNetworkProxy() [1/3]

QNetworkProxy::QNetworkProxy ( )

Constructs a QNetworkProxy with DefaultProxy type; the proxy type is determined by applicationProxy(), which defaults to NoProxy.

See also
setType(), setApplicationProxy()

Definition at line 445 of file qnetworkproxy.cpp.

Referenced by applicationProxy().

446  : d(0)
447 {
448  // make sure we have QGlobalNetworkProxy singleton created, otherwise
449  // you don't have any socket engine handler created when directly setting
450  // a proxy to the socket
451  globalNetworkProxy();
452 }
QSharedDataPointer< QNetworkProxyPrivate > d

◆ QNetworkProxy() [2/3]

QNetworkProxy::QNetworkProxy ( ProxyType  type,
const QString hostName = QString(),
quint16  port = 0,
const QString user = QString(),
const QString password = QString() 
)

Constructs a QNetworkProxy with type, hostName, port, user and password.

The default capabilities for proxy type type are set automatically.

See also
capabilities()

Definition at line 462 of file qnetworkproxy.cpp.

464  : d(new QNetworkProxyPrivate(type, hostName, port, user, password))
465 {
466  // make sure we have QGlobalNetworkProxy singleton created, otherwise
467  // you don't have any socket engine handler created when directly setting
468  // a proxy to a socket
469  globalNetworkProxy();
470 }
QNetworkProxy::ProxyType type() const
Returns the proxy type for this instance.
QSharedDataPointer< QNetworkProxyPrivate > d
quint16 port() const
Returns the port of the proxy host.

◆ QNetworkProxy() [3/3]

QNetworkProxy::QNetworkProxy ( const QNetworkProxy other)

Constructs a copy of other.

Definition at line 475 of file qnetworkproxy.cpp.

476  : d(other.d)
477 {
478 }
QSharedDataPointer< QNetworkProxyPrivate > d

◆ ~QNetworkProxy()

QNetworkProxy::~QNetworkProxy ( )

Destroys the QNetworkProxy object.

Definition at line 483 of file qnetworkproxy.cpp.

484 {
485  // QSharedDataPointer takes care of deleting for us
486 }

Functions

◆ applicationProxy()

QNetworkProxy QNetworkProxy::applicationProxy ( )
static

Returns the application level network proxying.

If a QAbstractSocket or QTcpSocket has the QNetworkProxy::DefaultProxy type, then the QNetworkProxy returned by this function is used.

See also
QNetworkProxyFactory, setApplicationProxy(), QAbstractSocket::proxy(), QTcpServer::proxy()

Definition at line 736 of file qnetworkproxy.cpp.

Referenced by QHttpPrivate::_q_slotSendRequest(), applicationProxy(), QNativeSocketEnginePrivate::checkProxy(), and QNetworkAccessAuthenticationManager::fetchCachedProxyCredentials().

737 {
738  if (globalNetworkProxy())
739  return globalNetworkProxy()->applicationProxy();
740  return QNetworkProxy();
741 }
QNetworkProxy()
Constructs a QNetworkProxy with DefaultProxy type; the proxy type is determined by applicationProxy()...

◆ capabilities()

QNetworkProxy::Capabilities QNetworkProxy::capabilities ( ) const

Returns the capabilities of this proxy server.

Since
4.5
See also
setCapabilities(), type()

Definition at line 576 of file qnetworkproxy.cpp.

Referenced by filterProxyListByCapabilities(), isCachingProxy(), isTransparentProxy(), QNetworkAccessHttpBackend::postRequest(), QAbstractSocketPrivate::resolveProxy(), QTcpServerPrivate::resolveProxy(), and setCapabilities().

577 {
579 }
QSharedDataPointer< QNetworkProxyPrivate > d
static QNetworkProxy::Capabilities defaultCapabilitiesForType(QNetworkProxy::ProxyType type)
QNetworkProxy::Capabilities capabilities

◆ hostName()

QString QNetworkProxy::hostName ( ) const

Returns the host name of the proxy host.

See also
setHostName(), setPort(), port()

Definition at line 677 of file qnetworkproxy.cpp.

Referenced by QHttpPrivate::_q_slotSendRequest(), makeCacheKey(), QNetworkAccessFtpBackend::open(), proxyAuthenticationKey(), QSocks5SocketEnginePrivate::reauthenticate(), removeDuplicateProxies(), and setHostName().

678 {
679  return d ? d->hostName : QString();
680 }
QSharedDataPointer< QNetworkProxyPrivate > d
The QString class provides a Unicode character string.
Definition: qstring.h:83

◆ isCachingProxy()

bool QNetworkProxy::isCachingProxy ( ) const

Returns true if this proxy supports the QNetworkProxy::CachingCapability capability.

Since
4.4

In Qt 4.4, the capability was tied to the proxy type, but since Qt 4.5 it is possible to remove the capability of caching from a proxy by calling setCapabilities().

See also
capabilities(), type(), isTransparentProxy()

Definition at line 596 of file qnetworkproxy.cpp.

597 {
598  return capabilities() & CachingCapability;
599 }
Capabilities capabilities() const
Returns the capabilities of this proxy server.

◆ isTransparentProxy()

bool QNetworkProxy::isTransparentProxy ( ) const

Returns true if this proxy supports transparent tunneling of TCP connections.

Since
4.4

This matches the QNetworkProxy::TunnelingCapability capability.

In Qt 4.4, the capability was tied to the proxy type, but since Qt 4.5 it is possible to remove the capability of caching from a proxy by calling setCapabilities().

See also
capabilities(), type(), isCachingProxy()

Definition at line 617 of file qnetworkproxy.cpp.

Referenced by QNetworkAccessHttpBackend::postRequest().

618 {
620 }
Capabilities capabilities() const
Returns the capabilities of this proxy server.

◆ operator!=()

bool QNetworkProxy::operator!= ( const QNetworkProxy other) const
inline

Compares the value of this network proxy to other and returns true if they differ.

Since
4.4

\

Definition at line 151 of file qnetworkproxy.h.

152  { return !(*this == other); }

◆ operator=()

QNetworkProxy & QNetworkProxy::operator= ( const QNetworkProxy other)

Assigns the value of the network proxy other to this network proxy.

Since
4.2

Definition at line 518 of file qnetworkproxy.cpp.

519 {
520  d = other.d;
521  return *this;
522 }
QSharedDataPointer< QNetworkProxyPrivate > d

◆ operator==()

bool QNetworkProxy::operator== ( const QNetworkProxy other) const
Since
4.4

Compares the value of this network proxy to other and returns true if they are equal (same proxy type, server as well as username and password)

Definition at line 494 of file qnetworkproxy.cpp.

495 {
496  return d == other.d || (d && other.d && *d == *other.d);
497 }
QSharedDataPointer< QNetworkProxyPrivate > d

◆ password()

QString QNetworkProxy::password ( ) const

Returns the password used for authentication.

See also
user(), setPassword(), setUser()

Definition at line 657 of file qnetworkproxy.cpp.

Referenced by QNetworkAccessAuthenticationManager::fetchCachedProxyCredentials(), QSocks5SocketEnginePrivate::initialize(), QSocks5SocketEnginePrivate::reauthenticate(), setPassword(), QHttpSocketEngine::setProxy(), and QHttpSetProxyRequest::start().

658 {
659  return d ? d->password : QString();
660 }
QSharedDataPointer< QNetworkProxyPrivate > d
The QString class provides a Unicode character string.
Definition: qstring.h:83

◆ port()

quint16 QNetworkProxy::port ( ) const

Returns the port of the proxy host.

See also
setHostName(), setPort(), hostName()

Definition at line 697 of file qnetworkproxy.cpp.

Referenced by QHttpPrivate::_q_slotSendRequest(), makeCacheKey(), QNetworkAccessFtpBackend::open(), proxyAuthenticationKey(), QSocks5SocketEnginePrivate::reauthenticate(), removeDuplicateProxies(), and setPort().

698 {
699  return d ? d->port : 0;
700 }
QSharedDataPointer< QNetworkProxyPrivate > d

◆ setApplicationProxy()

void QNetworkProxy::setApplicationProxy ( const QNetworkProxy networkProxy)
static

Sets the application level network proxying to be networkProxy.

If a QAbstractSocket or QTcpSocket has the QNetworkProxy::DefaultProxy type, then the QNetworkProxy set with this function is used. If you want more flexibility in determining which the proxy, use the QNetworkProxyFactory class.

Setting a default proxy value with this function will override the application proxy factory set with QNetworkProxyFactory::setApplicationProxyFactory.

See also
QNetworkProxyFactory, applicationProxy(), QAbstractSocket::setProxy(), QTcpServer::setProxy()

Definition at line 716 of file qnetworkproxy.cpp.

717 {
718  if (globalNetworkProxy()) {
719  // don't accept setting the proxy to DefaultProxy
720  if (networkProxy.type() == DefaultProxy)
721  globalNetworkProxy()->setApplicationProxy(QNetworkProxy::NoProxy);
722  else
723  globalNetworkProxy()->setApplicationProxy(networkProxy);
724  }
725 }
QNetworkProxy::ProxyType type() const
Returns the proxy type for this instance.

◆ setCapabilities()

void QNetworkProxy::setCapabilities ( Capabilities  capabilities)

Sets the capabilities of this proxy to capabilities.

Since
4.5
See also
setType(), capabilities()

Definition at line 560 of file qnetworkproxy.cpp.

561 {
563  d->capabilitiesSet = true;
564 }
QSharedDataPointer< QNetworkProxyPrivate > d
Capabilities capabilities() const
Returns the capabilities of this proxy server.
QNetworkProxy::Capabilities capabilities

◆ setHostName()

void QNetworkProxy::setHostName ( const QString hostName)

Sets the host name of the proxy host to be hostName.

See also
hostName(), setPort(), port()

Definition at line 667 of file qnetworkproxy.cpp.

Referenced by Maemo::ProxyConfPrivate::flush(), and QNetworkProxyFactory::systemProxyForQuery().

668 {
669  d->hostName = hostName;
670 }
QSharedDataPointer< QNetworkProxyPrivate > d
QString hostName() const
Returns the host name of the proxy host.

◆ setPassword()

void QNetworkProxy::setPassword ( const QString password)

Sets the password for proxy authentication to be password.

See also
user(), setUser(), password()

Definition at line 647 of file qnetworkproxy.cpp.

Referenced by QSocks5SocketEnginePrivate::reauthenticate(), and QNetworkProxyFactory::systemProxyForQuery().

648 {
649  d->password = password;
650 }
QSharedDataPointer< QNetworkProxyPrivate > d
QString password() const
Returns the password used for authentication.

◆ setPort()

void QNetworkProxy::setPort ( quint16  port)

Sets the port of the proxy host to be port.

See also
hostName(), setHostName(), port()

Definition at line 687 of file qnetworkproxy.cpp.

Referenced by Maemo::ProxyConfPrivate::flush(), and QNetworkProxyFactory::systemProxyForQuery().

688 {
689  d->port = port;
690 }
QSharedDataPointer< QNetworkProxyPrivate > d
quint16 port() const
Returns the port of the proxy host.

◆ setType()

void QNetworkProxy::setType ( QNetworkProxy::ProxyType  type)

Sets the proxy type for this instance to be type.

Note that changing the type of a proxy does not change the set of capabilities this QNetworkProxy object holds if any capabilities have been set with setCapabilities().

See also
type(), setCapabilities()

Definition at line 533 of file qnetworkproxy.cpp.

Referenced by QHttpPrivate::_q_slotSendRequest(), Maemo::ProxyConfPrivate::flush(), and QNetworkProxyFactory::systemProxyForQuery().

534 {
535  d->type = type;
536  if (!d->capabilitiesSet)
538 }
QNetworkProxy::ProxyType type() const
Returns the proxy type for this instance.
QSharedDataPointer< QNetworkProxyPrivate > d
static QNetworkProxy::Capabilities defaultCapabilitiesForType(QNetworkProxy::ProxyType type)
QNetworkProxy::ProxyType type
QNetworkProxy::Capabilities capabilities

◆ setUser()

void QNetworkProxy::setUser ( const QString user)

Sets the user name for proxy authentication to be user.

See also
user(), setPassword(), password()

Definition at line 627 of file qnetworkproxy.cpp.

Referenced by QNetworkAccessAuthenticationManager::cacheProxyCredentials(), QSocks5SocketEnginePrivate::reauthenticate(), and QNetworkProxyFactory::systemProxyForQuery().

628 {
629  d->user = user;
630 }
QSharedDataPointer< QNetworkProxyPrivate > d
QString user() const
Returns the user name used for authentication.

◆ type()

QNetworkProxy::ProxyType QNetworkProxy::type ( ) const

◆ user()

QString QNetworkProxy::user ( ) const

Returns the user name used for authentication.

See also
setUser(), setPassword(), password()

Definition at line 637 of file qnetworkproxy.cpp.

Referenced by QNetworkAccessAuthenticationManager::cacheProxyCredentials(), QSocks5SocketEnginePrivate::initialize(), makeCacheKey(), proxyAuthenticationKey(), QSocks5SocketEnginePrivate::reauthenticate(), QHttpSocketEngine::setProxy(), setUser(), and QHttpSetProxyRequest::start().

638 {
639  return d ? d->user : QString();
640 }
QSharedDataPointer< QNetworkProxyPrivate > d
The QString class provides a Unicode character string.
Definition: qstring.h:83

Properties

◆ d

QSharedDataPointer<QNetworkProxyPrivate> QNetworkProxy::d
private

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