QNetworkProxy Class Reference

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

#include <qnetworkproxy.h>

Collaboration diagram for QNetworkProxy:

Public Types
enum	ProxyType {   DefaultProxy , Socks5Proxy , NoProxy , HttpProxy ,   HttpCachingProxy , FtpCachingProxy }
	This enum describes the types of network proxying provided in Qt. More...
enum	Capability {   TunnelingCapability = 0x0001 , ListeningCapability = 0x0002 , UdpTunnelingCapability = 0x0004 , CachingCapability = 0x0008 ,   HostNameLookupCapability = 0x0010 , SctpTunnelingCapability = 0x00020 , SctpListeningCapability = 0x00040 }

Public Member Functions
	QNetworkProxy ()
	Constructs a QNetworkProxy with DefaultProxy type.
	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.
	QNetworkProxy (const QNetworkProxy &other)
	Constructs a copy of other.
QNetworkProxy &	operator= (QNetworkProxy &&other) noexcept
QNetworkProxy &	operator= (const QNetworkProxy &other)
	~QNetworkProxy ()
	Destroys the QNetworkProxy object.
void	swap (QNetworkProxy &other) noexcept
bool	operator== (const QNetworkProxy &other) const
bool	operator!= (const QNetworkProxy &other) const
void	setType (QNetworkProxy::ProxyType type)
	Sets the proxy type for this instance to be type.
QNetworkProxy::ProxyType	type () const
	Returns the proxy type for this instance.
void	setCapabilities (Capabilities capab)
Capabilities	capabilities () const
bool	isCachingProxy () const
bool	isTransparentProxy () const
void	setUser (const QString &userName)
	Sets the user name for proxy authentication to be user.
QString	user () const
	Returns the user name used for authentication.
void	setPassword (const QString &password)
	Sets the password for proxy authentication to be password.
QString	password () const
	Returns the password used for authentication.
void	setHostName (const QString &hostName)
	Sets the host name of the proxy host to be hostName.
QString	hostName () const
	Returns the host name of the proxy host.
void	setPort (quint16 port)
	Sets the port of the proxy host to be port.
quint16	port () const
	Returns the port of the proxy host.
QVariant	header (QNetworkRequest::KnownHeaders header) const
void	setHeader (QNetworkRequest::KnownHeaders header, const QVariant &value)
bool	hasRawHeader (const QByteArray &headerName) const
QList< QByteArray >	rawHeaderList () const
QByteArray	rawHeader (const QByteArray &headerName) const
void	setRawHeader (const QByteArray &headerName, const QByteArray &value)

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

Detailed Description

The QNetworkProxy class provides a network layer proxy.

Since

4.1

\reentrant

\inmodule 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 and QNetworkAccessManager. 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 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 \l {QAbstractSocket::connectToHost()}{connectToHost()}, \l {QUdpSocket::bind()}{bind()} or \l {QTcpServer::listen()}{listen()} is equivalent to QHostAddress::LocalHost or QHostAddress::LocalHostIPv6.

Each type of proxy support has certain restrictions associated with it. You should read the \l{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.

Definition at line 78 of file qnetworkproxy.h.

Member Enumeration Documentation

Capability

enum QNetworkProxy::Capability

Since

4.5

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

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 capabilities after the object has been created with setCapabilities().

The capabilities that QNetworkProxy supports are:

\value 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.

\value ListeningCapability Ability to create a listening socket and wait for an incoming TCP connection from a remote host.

\value UdpTunnelingCapability Ability to relay UDP datagrams via the proxy server to and from a remote host.

\value 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.

\value 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.

\value SctpTunnelingCapability Ability to open transparent, tunneled SCTP connections to a remote host.

\value SctpListeningCapability Ability to create a listening socket and wait for an incoming SCTP connection from a remote host.

Enumerator
TunnelingCapability
ListeningCapability
UdpTunnelingCapability
CachingCapability
HostNameLookupCapability
SctpTunnelingCapability
SctpListeningCapability

Definition at line 90 of file qnetworkproxy.h.

ProxyType

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.

\value NoProxy No proxying is used \value DefaultProxy Proxy is determined based on the application proxy set using setApplicationProxy() \value Socks5Proxy \l Socks5 proxying is used \value HttpProxy HTTP transparent proxying is used \value HttpCachingProxy Proxying for HTTP requests only \value FtpCachingProxy Proxying for FTP requests only

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.

\table \header

• Proxy type
• Description
• Default capabilities

\row

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

\row

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

\row

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

\row

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

\endtable

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 81 of file qnetworkproxy.h.

Constructor & Destructor Documentation

QNetworkProxy() [1/3]

QNetworkProxy::QNetworkProxy

(

)

Constructs a QNetworkProxy with DefaultProxy type.

The proxy type is determined by applicationProxy(), which defaults to NoProxy or a system-wide proxy if one is configured.

See also

setType(), setApplicationProxy()

Definition at line 465 of file qnetworkproxy.cpp.

Referenced by applicationProxy().

Here is the caller graph for this function:

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 482 of file qnetworkproxy.cpp.

QNetworkProxy() [3/3]

QNetworkProxy::QNetworkProxy

(

const QNetworkProxy &

other

)

Constructs a copy of other.

Definition at line 495 of file qnetworkproxy.cpp.

~QNetworkProxy()

QNetworkProxy::~QNetworkProxy

(

)

Destroys the QNetworkProxy object.

Definition at line 503 of file qnetworkproxy.cpp.

Member Function Documentation

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 747 of file qnetworkproxy.cpp.

References QNetworkProxy(), and applicationProxy().

Referenced by applicationProxy(), and QNetworkAccessAuthenticationManager::fetchCachedProxyCredentials().

Here is the call graph for this function:

Here is the caller graph for this function:

capabilities()

QNetworkProxy::Capabilities QNetworkProxy::capabilities

(

)

const

Since

4.5

Returns the capabilities of this proxy server.

See also

setCapabilities(), type()

Definition at line 592 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::capabilities, defaultCapabilitiesForType(), and DefaultProxy.

Referenced by QHttpNetworkConnectionPrivate::_q_hostLookupFinished(), filterProxyListByCapabilities(), isCachingProxy(), isTransparentProxy(), operator<<(), setCapabilities(), and QHttpNetworkConnectionPrivate::startHostInfoLookup().

Here is the call graph for this function:

Here is the caller graph for this function:

hasRawHeader()

bool QNetworkProxy::hasRawHeader

(

const QByteArray &

headerName

)

const

Since

5.0 Returns true if the raw header headerName is in use for this proxy. Returns false if the proxy is not of type HttpProxy or HttpCachingProxy.

See also

rawHeader(), setRawHeader()

Definition at line 794 of file qnetworkproxy.cpp.

References QList< T >::constEnd(), QNetworkHeadersPrivate::findRawHeader(), headerName(), QNetworkProxyPrivate::headers, HttpCachingProxy, HttpProxy, QNetworkHeadersPrivate::rawHeaders, and QNetworkProxyPrivate::type.

Here is the call graph for this function:

header()

QVariant QNetworkProxy::header

(

QNetworkRequest::KnownHeaders

header

)

const

Since

5.0 Returns the value of the known network header header if it is in use for this proxy. If it is not present, returns QVariant() (i.e., an invalid variant).

See also

QNetworkRequest::KnownHeaders, rawHeader(), setHeader()

Definition at line 762 of file qnetworkproxy.cpp.

References QNetworkHeadersPrivate::cookedHeaders, header(), QNetworkProxyPrivate::headers, HttpCachingProxy, HttpProxy, QNetworkProxyPrivate::type, and QHash< Key, T >::value().

Referenced by header(), and setHeader().

Here is the call graph for this function:

Here is the caller graph for this function:

hostName()

QString QNetworkProxy::hostName

(

)

const

Returns the host name of the proxy host.

See also

setHostName(), setPort(), port()

Definition at line 687 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::hostName.

Referenced by QHttpNetworkConnectionPrivate::createAuthorization(), makeCacheKey(), operator<<(), proxyAuthenticationKey(), QNetworkAccessManagerPrivate::proxyAuthenticationRequired(), QSocks5SocketEnginePrivate::reauthenticate(), removeDuplicateProxies(), setHostName(), and QHttpNetworkConnectionPrivate::startHostInfoLookup().

Here is the caller graph for this function:

isCachingProxy()

bool QNetworkProxy::isCachingProxy

(

)

const

Since

4.4

Returns true if this proxy supports the QNetworkProxy::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 calling setCapabilities().

See also

capabilities(), type(), isTransparentProxy()

Definition at line 609 of file qnetworkproxy.cpp.

References CachingCapability, and capabilities().

Here is the call graph for this function:

isTransparentProxy()

bool QNetworkProxy::isTransparentProxy

(

)

const

Since

4.4

Returns true if this proxy supports transparent tunneling of TCP connections. 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 627 of file qnetworkproxy.cpp.

References capabilities(), and TunnelingCapability.

Here is the call graph for this function:

operator!=()

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

inline

Definition at line 112 of file qnetworkproxy.h.

References other().

Here is the call graph for this function:

operator=() [1/2]

QNetworkProxy & QNetworkProxy::operator=

(

const QNetworkProxy &

other

)

\fn bool QNetworkProxy::operator!=(const QNetworkProxy &other) const
\since 4.4

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

\

Since

4.2

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

Definition at line 532 of file qnetworkproxy.cpp.

References other().

Here is the call graph for this function:

operator=() [2/2]

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

inlinenoexcept

Definition at line 105 of file qnetworkproxy.h.

References other(), and swap().

Here is the call graph for this function:

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 514 of file qnetworkproxy.cpp.

References other().

Here is the call graph for this function:

password()

QString QNetworkProxy::password

(

)

const

Returns the password used for authentication.

See also

user(), setPassword(), setUser()

Definition at line 667 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::password.

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

Here is the caller graph for this function:

port()

quint16 QNetworkProxy::port

(

)

const

Returns the port of the proxy host.

See also

setHostName(), setPort(), hostName()

Definition at line 707 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::port.

Referenced by makeCacheKey(), operator<<(), proxyAuthenticationKey(), QSocks5SocketEnginePrivate::reauthenticate(), removeDuplicateProxies(), and setPort().

Here is the caller graph for this function:

rawHeader()

QByteArray QNetworkProxy::rawHeader

(

const QByteArray &

headerName

)

const

Since

5.0 Returns the raw form of header headerName. If no such header is present or the proxy is not of type HttpProxy or HttpCachingProxy, an empty QByteArray is returned, which may be indistinguishable from a header that is present but has no content (use hasRawHeader() to find out if the header exists or not).

Raw headers can be set with setRawHeader() or with setHeader().

See also

header(), setRawHeader()

Definition at line 813 of file qnetworkproxy.cpp.

References QList< T >::constEnd(), QNetworkHeadersPrivate::findRawHeader(), headerName(), QNetworkProxyPrivate::headers, HttpCachingProxy, HttpProxy, it, QNetworkHeadersPrivate::rawHeaders, and QNetworkProxyPrivate::type.

Here is the call graph for this function:

rawHeaderList()

QList< QByteArray > QNetworkProxy::rawHeaderList

(

)

const

Since

5.0 Returns a list of all raw headers that are set in this network proxy. The list is in the order that the headers were set.

If the proxy is not of type HttpProxy or HttpCachingProxy an empty QList is returned.

See also

hasRawHeader(), rawHeader()

Definition at line 834 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::headers, HttpCachingProxy, HttpProxy, QNetworkHeadersPrivate::rawHeadersKeys(), and QNetworkProxyPrivate::type.

Here is the call graph for this function:

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 proxy is used, use the QNetworkProxyFactory class.

Setting a default proxy value with this function will override the application proxy factory set with QNetworkProxyFactory::setApplicationProxyFactory, and disable the use of a system proxy.

See also

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

Definition at line 727 of file qnetworkproxy.cpp.

References DefaultProxy, NoProxy, and type().

Here is the call graph for this function:

setCapabilities()

void QNetworkProxy::setCapabilities

(

Capabilities

capabilities

)

Since

4.5

Sets the capabilities of this proxy to capabilities.

See also

setType(), capabilities()

Definition at line 579 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::capabilities, capabilities(), and QNetworkProxyPrivate::capabilitiesSet.

Here is the call graph for this function:

setHeader()

void QNetworkProxy::setHeader	(	QNetworkRequest::KnownHeaders	header,
		const QVariant &	value
	)

Since

5.0 Sets the value of the known header header to be value, overriding any previously set headers. This operation also sets the equivalent raw HTTP header.

If the proxy is not of type HttpProxy or HttpCachingProxy this has no effect.

See also

QNetworkRequest::KnownHeaders, setRawHeader(), header()

Definition at line 780 of file qnetworkproxy.cpp.

References header(), QNetworkProxyPrivate::headers, HttpCachingProxy, HttpProxy, QNetworkHeadersPrivate::setCookedHeader(), and QNetworkProxyPrivate::type.

Here is the call graph for this function:

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 677 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::hostName, and hostName().

Here is the call graph for this function:

setPassword()

void QNetworkProxy::setPassword

(

const QString &

password

)

Sets the password for proxy authentication to be password.

See also

user(), setUser(), password()

Definition at line 657 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::password, and password().

Referenced by QSocks5SocketEnginePrivate::reauthenticate().

Here is the call graph for this function:

Here is the caller graph for this function:

setPort()

void QNetworkProxy::setPort

(

quint16

port

)

Sets the port of the proxy host to be port.

See also

hostName(), setHostName(), port()

Definition at line 697 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::port, and port().

Here is the call graph for this function:

setRawHeader()

void QNetworkProxy::setRawHeader	(	const QByteArray &	headerName,
		const QByteArray &	headerValue
	)

Since

5.0 Sets the header headerName to be of value headerValue. If headerName corresponds to a known header (see QNetworkRequest::KnownHeaders), the raw format will be parsed and the corresponding "cooked" header will be set as well.

For example:

request.setRawHeader(QByteArray("Last-Modified"), QByteArray("Sun, 06 Nov 1994 08:49:37 GMT"));

will also set the known header LastModifiedHeader to be the QDateTime object of the parsed date.

Note

Setting the same header twice overrides the previous setting. To accomplish the behaviour of multiple HTTP headers of the same name, you should concatenate the two values, separating them with a comma (",") and set one single raw header.

If the proxy is not of type HttpProxy or HttpCachingProxy this has no effect.

See also

QNetworkRequest::KnownHeaders, setHeader(), hasRawHeader(), rawHeader()

Definition at line 864 of file qnetworkproxy.cpp.

References headerName(), QNetworkProxyPrivate::headers, headerValue(), HttpCachingProxy, HttpProxy, QNetworkHeadersPrivate::setRawHeader(), and QNetworkProxyPrivate::type.

Referenced by QHttpNetworkConnectionChannel::ensureConnection().

Here is the call graph for this function:

Here is the caller graph for this function:

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 555 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::capabilities, QNetworkProxyPrivate::capabilitiesSet, defaultCapabilitiesForType(), QNetworkProxyPrivate::type, and type().

Here is the call graph for this function:

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 637 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::user, and user().

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

Here is the call graph for this function:

Here is the caller graph for this function:

swap()

void QNetworkProxy::swap ( QNetworkProxy &  other )

inlinenoexcept

Since

5.0

Swaps this network proxy instance with other. This function is very fast and never fails.

Definition at line 109 of file qnetworkproxy.h.

References d, and other().

Here is the call graph for this function:

type()

QNetworkProxy::ProxyType QNetworkProxy::type

(

)

const

Returns the proxy type for this instance.

See also

setType()

Definition at line 567 of file qnetworkproxy.cpp.

References DefaultProxy, and QNetworkProxyPrivate::type.

Referenced by QNativeSocketEnginePrivate::checkProxy(), QAbstractSocketEngine::createSocketEngine(), QHttpSocketEngineHandler::createSocketEngine(), QSocks5SocketEngineHandler::createSocketEngine(), QHttpNetworkConnectionChannel::ensureConnection(), QNetworkAccessAuthenticationManager::fetchCachedProxyCredentials(), QHttpNetworkConnectionChannel::init(), macQueryInternal(), makeCacheKey(), operator<<(), parseServerList(), QNetworkReplyHttpImplPrivate::postRequest(), QHttpNetworkConnectionPrivate::prepareRequest(), proxyAuthenticationKey(), QGlobalNetworkProxy::proxyForQuery(), QNetworkAccessManagerPrivate::queryProxy(), removeDuplicateProxies(), QTcpServerPrivate::resolveProxy(), QAbstractSocketPrivate::resolveProxy(), setApplicationProxy(), setType(), and QHttpThreadDelegate::startRequest().

Here is the caller graph for this function:

user()

QString QNetworkProxy::user

(

)

const

Returns the user name used for authentication.

See also

setUser(), setPassword(), password()

Definition at line 647 of file qnetworkproxy.cpp.

References QNetworkProxyPrivate::user.

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

Here is the caller graph for this function:

---

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

• qtbase/src/network/kernel/qnetworkproxy.h
• qtbase/src/network/doc/snippets/code/src_network_kernel_qnetworkproxy.cpp
• qtbase/src/network/kernel/qnetworkproxy.cpp