CopperSpice API  1.7.2
QNetworkProxy Class Reference

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

Public Typedefs

using Capabilities = QFlags< Capability >
 

Public Types

enum  Capability
 
enum  ProxyType
 

Public Methods

 QNetworkProxy ()
 
 QNetworkProxy (const QNetworkProxy &other)
 
 QNetworkProxy (ProxyType type, const QString &hostName=QString (), quint16 port=0, const QString &user=QString (), const QString &password=QString ())
 
 ~QNetworkProxy ()
 
Capabilities capabilities () const
 
bool hasRawHeader (const QByteArray &headerName) const
 
QVariant header (QNetworkRequest::KnownHeaders header) const
 
QString hostName () const
 
bool isCachingProxy () const
 
bool isTransparentProxy () const
 
bool operator!= (const QNetworkProxy &other) const
 
QNetworkProxy & operator= (const QNetworkProxy &other)
 
QNetworkProxy & operator= (QNetworkProxy &&other)
 
bool operator== (const QNetworkProxy &other) const
 
QString password () const
 
quint16 port () const
 
QByteArray rawHeader (const QByteArray &headerName) const
 
QList< QByteArrayrawHeaderList () const
 
void setCapabilities (Capabilities capabilities)
 
void setHeader (QNetworkRequest::KnownHeaders header, const QVariant &value)
 
void setHostName (const QString &hostName)
 
void setPassword (const QString &password)
 
void setPort (quint16 port)
 
void setRawHeader (const QByteArray &headerName, const QByteArray &headerValue)
 
void setType (QNetworkProxy::ProxyType type)
 
void setUser (const QString &userName)
 
void swap (QNetworkProxy &other)
 
QNetworkProxy::ProxyType type () const
 
QString user () const
 

Static Public Methods

static QNetworkProxy applicationProxy ()
 
static void setApplicationProxy (const QNetworkProxy &proxy)
 

Detailed Description

The QNetworkProxy class provides a network layer proxy.

QNetworkProxy provides the method for configuring network layer proxy support to the 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.setType(QNetworkProxy::Socks5Proxy);
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 connectToHost(), bind() or 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 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 bind() may fail with a timeout error. If a port number other than 0 is passed to 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

Member Typedef Documentation

Member Enumeration Documentation

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:

ConstantValueDescription
QNetworkProxy::TunnelingCapability0x0001 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.
QNetworkProxy::ListeningCapability0x0002 Ability to create a listening socket and wait for an incoming TCP connection from a remote host.
QNetworkProxy::UdpTunnelingCapability0x0004 Ability to relay UDP datagrams via the proxy server to and from a remote host.
QNetworkProxy::CachingCapability0x0008 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.
QNetworkProxy::HostNameLookupCapability0x00010 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.

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

There are two types of proxies CopperSpice 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.

ConstantValueDescription
QNetworkProxy::NoProxy2No proxying is used
QNetworkProxy::DefaultProxy0Proxy is determined based on the application proxy set using setApplicationProxy()
QNetworkProxy::Socks5Proxy1Socks5 proxying is used
QNetworkProxy::HttpProxy3HTTP transparent proxying is used
QNetworkProxy::HttpCachingProxy4Proxying for HTTP requests only
QNetworkProxy::FtpCachingProxy5Proxying 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.

Proxy typeDescriptionDefault capabilities
SOCKS 5Generic proxy for any kind of connection. Supports TCP, UDP, binding to a port (incoming connections) and authentication.TunnelingCapability, ListeningCapability, UdpTunnelingCapability, HostNameLookupCapability
HTTPImplemented using the "CONNECT" command, supports only outgoing TCP connections; supports authentication.TunnelingCapability, CachingCapability, HostNameLookupCapability
Caching-only HTTPImplemented using normal HTTP commands, it is useful only in the context of HTTP requests (see QNetworkAccessManager)CachingCapability, HostNameLookupCapability
Caching FTPImplemented using an FTP proxy, it is useful only in the context of FTP requests (see QFtp, QNetworkAccessManager)CachingCapability, HostNameLookupCapability

You should not set the application default proxy (setApplicationProxy()) to a proxy that does not have the TunnelingCapability capability. If you do, QTcpSocket will not know how to open connections.

See also
setType(), type(), capabilities(), setCapabilities()

Constructor & Destructor Documentation

QNetworkProxy::QNetworkProxy ( )

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

See also
setType(), setApplicationProxy()
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()
QNetworkProxy::QNetworkProxy ( const QNetworkProxy &  other)

Constructs a copy of other.

QNetworkProxy::~QNetworkProxy ( )

Destroys the QNetworkProxy object.

Method Documentation

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()
Capabilities QNetworkProxy::capabilities ( ) const

Returns the capabilities of this proxy server.

See also
setCapabilities(), type()
bool QNetworkProxy::hasRawHeader ( const QByteArray headerName) const

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()
QVariant QNetworkProxy::header ( QNetworkRequest::KnownHeaders  header) const

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()
QString QNetworkProxy::hostName ( ) const

Returns the host name of the proxy host.

See also
setHostName(), setPort(), port()
bool QNetworkProxy::isCachingProxy ( ) const

Returns true if this proxy supports the QNetworkProxy::CachingCapability capability. It is possible to remove the capability of caching from a proxy by calling setCapabilities().

See also
capabilities(), type(), isTransparentProxy()
bool QNetworkProxy::isTransparentProxy ( ) const

Returns true if this proxy supports transparent tunneling of TCP connections. This matches the QNetworkProxy::TunnelingCapability capability.

It is possible to remove the capability of caching from a proxy by calling setCapabilities().

See also
capabilities(), type(), isCachingProxy()
bool QNetworkProxy::operator!= ( const QNetworkProxy &  other) const
inline

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

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

Copy assigns from other and returns a reference to this object.

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

Move assigns from other and returns a reference to this object.

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

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

QString QNetworkProxy::password ( ) const

Returns the password used for authentication.

See also
user(), setPassword(), setUser()
quint16 QNetworkProxy::port ( ) const

Returns the port of the proxy host.

See also
setHostName(), setPort(), hostName()
QByteArray QNetworkProxy::rawHeader ( const QByteArray headerName) const

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()
QList< QByteArray > QNetworkProxy::rawHeaderList ( ) const

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()
void QNetworkProxy::setApplicationProxy ( const QNetworkProxy &  proxy)
static

Sets the application level network proxying to proxy. If a QAbstractSocket or QTcpSocket has the QNetworkProxy::DefaultProxy type, then the QNetworkProxy set with this method is used.

If you want more flexibility in determining which the proxy, use the QNetworkProxyFactory class. Setting a default proxy value with this method will override the application proxy factory set with QNetworkProxyFactory::setApplicationProxyFactory.

See also
QNetworkProxyFactory, applicationProxy(), QAbstractSocket::setProxy(), QTcpServer::setProxy()
void QNetworkProxy::setCapabilities ( Capabilities  capabilities)

Sets the capabilities of this proxy to capabilities.

See also
setType(), capabilities()
void QNetworkProxy::setHeader ( QNetworkRequest::KnownHeaders  header,
const QVariant value 
)

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()
void QNetworkProxy::setHostName ( const QString hostName)

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

See also
hostName(), setPort(), port()
void QNetworkProxy::setPassword ( const QString password)

Sets the password for proxy authentication to be password.

See also
user(), setUser(), password()
void QNetworkProxy::setPort ( quint16  port)

Sets the port of the proxy host to be port.

See also
hostName(), setHostName(), port()
void QNetworkProxy::setRawHeader ( const QByteArray headerName,
const QByteArray headerValue 
)

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

As an example the following code will also set the known header LastModifiedHeader to be the QDateTime object of the parsed date.

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

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

Note
Setting the same header twice overrides the previous setting. To accomplish the behavior 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.
See also
QNetworkRequest::KnownHeaders, setHeader(), hasRawHeader(), rawHeader()
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()
void QNetworkProxy::setUser ( const QString userName)

Sets the user name for proxy authentication to be userName.

See also
user(), setPassword(), password()
void QNetworkProxy::swap ( QNetworkProxy &  other)
inline

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

QNetworkProxy::ProxyType QNetworkProxy::type ( ) const

Returns the proxy type for this instance.

See also
setType()
QString QNetworkProxy::user ( ) const

Returns the user name used for authentication.

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