Contents

• Public Types
• Public Functions
• Static Public Members
• Detailed Description
• SOCKS5

Detailed Description

TheQNetworkProxy class provides a network layer proxy.

QNetworkProxy provides the method for configuring network layer proxy support to the Qt network classes. The currently supported classes areQAbstractSocket,QTcpSocket,QUdpSocket,QTcpServer,QNetworkAccessManager andQFtp. 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.

QNetworkProxy proxy;proxy.setType(QNetworkProxy::Socks5Proxy);proxy.setHostName("proxy.example.com");proxy.setPort(1080);proxy.setUser("username");proxy.setPassword("password");QNetworkProxy::setApplicationProxy(proxy);

An alternative to setting an application wide proxy is to specify the proxy for individual sockets usingQAbstractSocket::setProxy() andQTcpServer::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 inconnectToHost(),bind() orlisten() is equivalent toQHostAddress::LocalHost orQHostAddress::LocalHostIPv6.

Each type of proxy support has certain restrictions associated with it. You should read theProxyType 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 onRFC 1928 andRFC 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 theQNetworkProxy::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 withQUdpSocket andQTcpServer:

WithQUdpSocket, a call tobind() may fail with a timeout error. If a port number other than 0 is passed tobind(), it is not guaranteed that it is the specified port that will be used. UselocalPort() andlocalAddress() 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.

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

Member Type Documentation

enum QNetworkProxy::Capability
flags QNetworkProxy::Capabilities

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

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

The capabilities thatQNetworkProxy supports are:

This enum was introduced or modified in Qt 4.5.

The Capabilities type is a typedef forQFlags<Capability>. It stores an OR combination of Capability values.

enum QNetworkProxy::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.

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.

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

See alsosetType(),type(),capabilities(), andsetCapabilities().

Member Function Documentation

QNetworkProxy::QNetworkProxy()

Constructs aQNetworkProxy withDefaultProxy type; the proxy type is determined byapplicationProxy(), which defaults toNoProxy.

See alsosetType() andsetApplicationProxy().

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

Constructs aQNetworkProxy withtype,hostName,port,user andpassword.

The default capabilities for proxy typetype are set automatically.

See alsocapabilities().

QNetworkProxy::QNetworkProxy(constQNetworkProxy & other)

Constructs a copy ofother.

QNetworkProxy::~QNetworkProxy()

Destroys theQNetworkProxy object.

[static]QNetworkProxy QNetworkProxy::applicationProxy()

Returns the application level network proxying.

If aQAbstractSocket orQTcpSocket has theQNetworkProxy::DefaultProxy type, then theQNetworkProxy returned by this function is used.

See alsoQNetworkProxyFactory,setApplicationProxy(),QAbstractSocket::proxy(), andQTcpServer::proxy().

Capabilities QNetworkProxy::capabilities() const

Returns the capabilities of this proxy server.

This function was introduced in Qt 4.5.

See alsosetCapabilities() andtype().

QString QNetworkProxy::hostName() const

Returns the host name of the proxy host.

See alsosetHostName(),setPort(), andport().

bool QNetworkProxy::isCachingProxy() const

Returns true if this proxy supports theQNetworkProxy::CachingCapability 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 callingsetCapabilities().

This function was introduced in Qt 4.4.

See alsocapabilities(),type(), andisTransparentProxy().

bool QNetworkProxy::isTransparentProxy() const

Returns true if this proxy supports transparent tunneling of TCP connections. This matches theQNetworkProxy::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 callingsetCapabilities().

This function was introduced in Qt 4.4.

See alsocapabilities(),type(), andisCachingProxy().

QString QNetworkProxy::password() const

Returns the password used for authentication.

See alsouser(),setPassword(), andsetUser().

quint16 QNetworkProxy::port() const

Returns the port of the proxy host.

See alsosetHostName(),setPort(), andhostName().

[static]void QNetworkProxy::setApplicationProxy(constQNetworkProxy & networkProxy)

Sets the application level network proxying to benetworkProxy.

If aQAbstractSocket orQTcpSocket has theQNetworkProxy::DefaultProxy type, then theQNetworkProxy set with this function is used. If you want more flexibility in determining which the proxy, use theQNetworkProxyFactory class.

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

See alsoQNetworkProxyFactory,applicationProxy(),QAbstractSocket::setProxy(), andQTcpServer::setProxy().

void QNetworkProxy::setCapabilities(Capabilities capabilities)

Sets the capabilities of this proxy tocapabilities.

This function was introduced in Qt 4.5.

See alsosetType() andcapabilities().

void QNetworkProxy::setHostName(constQString & hostName)

Sets the host name of the proxy host to behostName.

See alsohostName(),setPort(), andport().

void QNetworkProxy::setPassword(constQString & password)

Sets the password for proxy authentication to bepassword.

See alsouser(),setUser(), andpassword().

void QNetworkProxy::setPort(quint16 port)

Sets the port of the proxy host to beport.

See alsohostName(),setHostName(), andport().

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

Sets the proxy type for this instance to betype.

Note that changing the type of a proxy does not change the set of capabilities thisQNetworkProxy object holds if any capabilities have been set withsetCapabilities().

See alsotype() andsetCapabilities().

void QNetworkProxy::setUser(constQString & user)

Sets the user name for proxy authentication to beuser.

See alsouser(),setPassword(), andpassword().

QNetworkProxy::ProxyType QNetworkProxy::type() const

Returns the proxy type for this instance.

See alsosetType().

QString QNetworkProxy::user() const

Returns the user name used for authentication.

See alsosetUser(),setPassword(), andpassword().

bool QNetworkProxy::operator!=(constQNetworkProxy & other) const

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

This function was introduced in Qt 4.4.

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

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

This function was introduced in Qt 4.2.

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

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

This function was introduced in Qt 4.4.