QNetworkProxyQuery Class Reference

The QNetworkProxyQuery class is used to query the proxy settings for a socket. More...

#include <qnetworkproxy.h>

Public Types
enum	QueryType { TcpSocket, UdpSocket, TcpServer = 100, UrlRequest }
	Describes the type of one QNetworkProxyQuery query. More...

Public Functions
int	localPort () const
	Returns the port number of the socket that will accept incoming packets from remote servers or -1 if the port is not known. More...
QNetworkConfiguration	networkConfiguration () const
	Returns the network configuration of the proxy query. More...
bool	operator!= (const QNetworkProxyQuery &other) const
	Returns true if this QNetworkProxyQuery object does not contain the same data as other. More...
QNetworkProxyQuery &	operator= (const QNetworkProxyQuery &other)
	Copies the contents of other. More...
bool	operator== (const QNetworkProxyQuery &other) const
	Returns true if this QNetworkProxyQuery object contains the same data as other. More...
QString	peerHostName () const
	Returns the host name or IP address being of the outgoing connection being requested, or an empty string if the remote hostname is not known. More...
int	peerPort () const
	Returns the port number for the outgoing request or -1 if the port number is not known. More...
QString	protocolTag () const
	Returns the protocol tag for this QNetworkProxyQuery object, or an empty QString in case the protocol tag is unknown. More...
	QNetworkProxyQuery ()
	Constructs a default QNetworkProxyQuery object. More...
	QNetworkProxyQuery (const QUrl &requestUrl, QueryType queryType=UrlRequest)
	Constructs a QNetworkProxyQuery with the URL requestUrl and sets the query type to queryType. More...
	QNetworkProxyQuery (const QString &hostname, int port, const QString &protocolTag=QString(), QueryType queryType=TcpSocket)
	Constructs a QNetworkProxyQuery of type queryType and sets the protocol tag to be protocolTag. More...
	QNetworkProxyQuery (quint16 bindPort, const QString &protocolTag=QString(), QueryType queryType=TcpServer)
	Constructs a QNetworkProxyQuery of type queryType and sets the protocol tag to be protocolTag. More...
	QNetworkProxyQuery (const QNetworkProxyQuery &other)
	Constructs a QNetworkProxyQuery object that is a copy of other. More...
	QNetworkProxyQuery (const QNetworkConfiguration &networkConfiguration, const QUrl &requestUrl, QueryType queryType=UrlRequest)
	Constructs a QNetworkProxyQuery with the URL requestUrl and sets the query type to queryType. More...
	QNetworkProxyQuery (const QNetworkConfiguration &networkConfiguration, const QString &hostname, int port, const QString &protocolTag=QString(), QueryType queryType=TcpSocket)
	Constructs a QNetworkProxyQuery of type queryType and sets the protocol tag to be protocolTag. More...
	QNetworkProxyQuery (const QNetworkConfiguration &networkConfiguration, quint16 bindPort, const QString &protocolTag=QString(), QueryType queryType=TcpServer)
	Constructs a QNetworkProxyQuery of type queryType and sets the protocol tag to be protocolTag. More...
QueryType	queryType () const
	Returns the query type. More...
void	setLocalPort (int port)
	Sets the port number that the socket wishes to use locally to accept incoming packets from remote servers to port. More...
void	setNetworkConfiguration (const QNetworkConfiguration &networkConfiguration)
	Sets the network configuration component of this QNetworkProxyQuery object to be networkConfiguration. More...
void	setPeerHostName (const QString &hostname)
	Sets the hostname of the outgoing connection being requested to hostname. More...
void	setPeerPort (int port)
	Sets the requested port number for the outgoing connection to be port. More...
void	setProtocolTag (const QString &protocolTag)
	Sets the protocol tag for this QNetworkProxyQuery object to be protocolTag. More...
void	setQueryType (QueryType type)
	Sets the query type of this object to be type. More...
void	setUrl (const QUrl &url)
	Sets the URL component of this QNetworkProxyQuery object to be url. More...
QUrl	url () const
	Returns the URL component of this QNetworkProxyQuery object in case of a query of type QNetworkProxyQuery::UrlRequest. More...
	~QNetworkProxyQuery ()
	Destroys this QNetworkProxyQuery object. More...

Properties
QSharedDataPointer< QNetworkProxyQueryPrivate >	d

Detailed Description

The QNetworkProxyQuery class is used to query the proxy settings for a socket.

Since

4.5

Attention

Module: QtNetwork

QNetworkProxyQuery holds the details of a socket being created or request being made. It is used by QNetworkProxy and QNetworkProxyFactory to allow applications to have a more fine-grained control over which proxy servers are used, depending on the details of the query. This allows an application to apply different settings, according to the protocol or destination hostname, for instance.

QNetworkProxyQuery supports the following criteria for selecting the proxy:

• the type of query
• the local port number to use
• the destination host name
• the destination port number
• the protocol name, such as "http" or "ftp"
• the URL being requested

The destination host name is the host in the connection in the case of outgoing connection sockets. It is the hostName parameter passed to QTcpSocket::connectToHost() or the host component of a URL requested with QNetworkRequest.

The destination port number is the requested port to connect to in the case of outgoing sockets, while the local port number is the port the socket wishes to use locally before attempting the external connection. In most cases, the local port number is used by listening sockets only (QTcpSocket) or by datagram sockets (QUdpSocket).

The protocol name is an arbitrary string that indicates the type of connection being attempted. For example, it can match the scheme of a URL, like "http", "https" and "ftp". In most cases, the proxy selection will not change depending on the protocol, but this information is provided in case a better choice can be made, like choosing an caching HTTP proxy for HTTP-based connections, but a more powerful SOCKSv5 proxy for all others.

The network configuration specifies which configuration to use, when bearer management is used. For example on a mobile phone the proxy settings are likely to be different for the cellular network vs WLAN.

Some of the criteria may not make sense in all of the types of query. The following table lists the criteria that are most commonly used, according to the type of query.

Query type	Description
TcpSocket	Normal sockets requesting a connection to a remote server, like QTcpSocket. The peer hostname and peer port match the values passed to QTcpSocket::connectToHost(). The local port is usually -1, indicating the socket has no preference in which port should be used. The URL component is not used.
UdpSocket	Datagram-based sockets, which can both send and receive. The local port, remote host or remote port fields can all be used or be left unused, depending on the characteristics of the socket. The URL component is not used.
TcpServer	Passive server sockets that listen on a port and await incoming connections from the network. Normally, only the local port is used, but the remote address could be used in specific circumstances, for example to indicate which remote host a connection is expected from. The URL component is not used.
UrlRequest	A more high-level request, such as those coming from QNetworkAccessManager. These requests will inevitably use an outgoing TCP socket, but the this query type is provided to indicate that more detailed information is present in the URL component. For ease of implementation, the URL's host and port are set as the destination address.

It should be noted that any of the criteria may be missing or unknown (an empty QString for the hostname or protocol name, -1 for the port numbers). If that happens, the functions executing the query should make their best guess or apply some implementation-defined default values.

See also

QNetworkProxy, QNetworkProxyFactory, QNetworkAccessManager, QAbstractSocket::setProxy()

Definition at line 60 of file qnetworkproxy.h.

Enumerations

QueryType

enum QNetworkProxyQuery::QueryType

Describes the type of one QNetworkProxyQuery query.

• TcpSocket a normal, outgoing TCP socket
• UdpSocket a datagram-based UDP socket, which could send to multiple destinations
• TcpServer a TCP server that listens for incoming connections from the network
• UrlRequest a more complex request which involves loading of a URL

See also

queryType(), setQueryType()

Enumerator
TcpSocket
UdpSocket
TcpServer
UrlRequest

Definition at line 63 of file qnetworkproxy.h.

                   {
        TcpSocket,
        UdpSocket,
        TcpServer = 100,
        UrlRequest
    };

Constructors and Destructors

QNetworkProxyQuery() [1/8]

QNetworkProxyQuery::QNetworkProxyQuery

(

)

Constructs a default QNetworkProxyQuery object.

By default, the query type will be QNetworkProxyQuery::TcpSocket.

Definition at line 907 of file qnetworkproxy.cpp.

{
}

QNetworkProxyQuery() [2/8]

QNetworkProxyQuery::QNetworkProxyQuery	(	const QUrl &	requestUrl,
		QueryType	queryType = UrlRequest
	)

Constructs a QNetworkProxyQuery with the URL requestUrl and sets the query type to queryType.

See also

protocolTag(), peerHostName(), peerPort()

Definition at line 917 of file qnetworkproxy.cpp.

{
    d->remote = requestUrl;
    d->type = queryType;
}

QNetworkProxyQuery() [3/8]

QNetworkProxyQuery::QNetworkProxyQuery	(	const QString &	hostname,
		int	port,
		const QString &	protocolTag = QString(),
		QueryType	queryType = TcpSocket
	)

Constructs a QNetworkProxyQuery of type queryType and sets the protocol tag to be protocolTag.

This constructor is suitable for QNetworkProxyQuery::TcpSocket queries, because it sets the peer hostname to hostname and the peer's port number to port.

Definition at line 930 of file qnetworkproxy.cpp.

{
    d->remote.setScheme(protocolTag);
    d->remote.setHost(hostname);
    d->remote.setPort(port);
    d->type = queryType;
}

QNetworkProxyQuery() [4/8]

QNetworkProxyQuery::QNetworkProxyQuery	(	quint16	bindPort,
		const QString &	protocolTag = QString(),
		QueryType	queryType = TcpServer
	)

Constructs a QNetworkProxyQuery of type queryType and sets the protocol tag to be protocolTag.

This constructor is suitable for QNetworkProxyQuery::TcpSocket queries because it sets the local port number to bindPort.

Note that bindPort is of type quint16 to indicate the exact port number that is requested. The value of -1 (unknown) is not allowed in this context.

See also

localPort()

Definition at line 952 of file qnetworkproxy.cpp.

{
    d->remote.setScheme(protocolTag);
    d->localPort = bindPort;
    d->type = queryType;
}

QNetworkProxyQuery() [5/8]

QNetworkProxyQuery::QNetworkProxyQuery

(

const QNetworkProxyQuery &

other

)

Constructs a QNetworkProxyQuery object that is a copy of other.

Definition at line 1040 of file qnetworkproxy.cpp.

    : d(other.d)
{
}

QNetworkProxyQuery() [6/8]

QNetworkProxyQuery::QNetworkProxyQuery	(	const QNetworkConfiguration &	networkConfiguration,
		const QUrl &	requestUrl,
		QueryType	queryType = UrlRequest
	)

Constructs a QNetworkProxyQuery with the URL requestUrl and sets the query type to queryType.

Since

4.8

The specified networkConfiguration is used to resolve the proxy settings.

See also

protocolTag(), peerHostName(), peerPort(), networkConfiguration()

Definition at line 973 of file qnetworkproxy.cpp.

{
    d->config = networkConfiguration;
    d->remote = requestUrl;
    d->type = queryType;
}

QNetworkProxyQuery() [7/8]

QNetworkProxyQuery::QNetworkProxyQuery	(	const QNetworkConfiguration &	networkConfiguration,
		const QString &	hostname,
		int	port,
		const QString &	protocolTag = QString(),
		QueryType	queryType = TcpSocket
	)

Constructs a QNetworkProxyQuery of type queryType and sets the protocol tag to be protocolTag.

Since

4.8

This constructor is suitable for QNetworkProxyQuery::TcpSocket queries, because it sets the peer hostname to hostname and the peer's port number to port. The specified networkConfiguration is used to resolve the proxy settings.

See also

networkConfiguration()

Definition at line 996 of file qnetworkproxy.cpp.

{
    d->config = networkConfiguration;
    d->remote.setScheme(protocolTag);
    d->remote.setHost(hostname);
    d->remote.setPort(port);
    d->type = queryType;
}

QNetworkProxyQuery() [8/8]

QNetworkProxyQuery::QNetworkProxyQuery	(	const QNetworkConfiguration &	networkConfiguration,
		quint16	bindPort,
		const QString &	protocolTag = QString(),
		QueryType	queryType = TcpServer
	)

Constructs a QNetworkProxyQuery of type queryType and sets the protocol tag to be protocolTag.

Since

4.8

This constructor is suitable for QNetworkProxyQuery::TcpSocket queries because it sets the local port number to bindPort. The specified networkConfiguration is used to resolve the proxy settings.

Note that bindPort is of type quint16 to indicate the exact port number that is requested. The value of -1 (unknown) is not allowed in this context.

See also

localPort(), networkConfiguration()

Definition at line 1026 of file qnetworkproxy.cpp.

{
    d->config = networkConfiguration;
    d->remote.setScheme(protocolTag);
    d->localPort = bindPort;
    d->type = queryType;
}

~QNetworkProxyQuery()

QNetworkProxyQuery::~QNetworkProxyQuery

(

)

Destroys this QNetworkProxyQuery object.

Definition at line 1048 of file qnetworkproxy.cpp.

{
    // QSharedDataPointer automatically deletes
}

Functions

localPort()

int QNetworkProxyQuery::localPort

(

)

const

Returns the port number of the socket that will accept incoming packets from remote servers or -1 if the port is not known.

See also

peerPort(), peerHostName(), setLocalPort()

Definition at line 1167 of file qnetworkproxy.cpp.

{
    return d ? d->localPort : -1;
}

networkConfiguration()

QNetworkConfiguration QNetworkProxyQuery::networkConfiguration

(

)

const

Returns the network configuration of the proxy query.

See also

setNetworkConfiguration()

Definition at line 1260 of file qnetworkproxy.cpp.

Referenced by setNetworkConfiguration(), and QNetworkProxyFactory::systemProxyForQuery().

{
    return d ? d->config : QNetworkConfiguration();
}

operator!=()

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

inline

Returns true if this QNetworkProxyQuery object does not contain the same data as other.

Definition at line 90 of file qnetworkproxy.h.

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

operator=()

QNetworkProxyQuery & QNetworkProxyQuery::operator=

(

const QNetworkProxyQuery &

other

)

Copies the contents of other.

Definition at line 1056 of file qnetworkproxy.cpp.

{
    d = other.d;
    return *this;
}

operator==()

bool QNetworkProxyQuery::operator==

(

const QNetworkProxyQuery &

other

)

const

Returns true if this QNetworkProxyQuery object contains the same data as other.

Definition at line 1066 of file qnetworkproxy.cpp.

{
    return d == other.d || (d && other.d && *d == *other.d);
}

peerHostName()

QString QNetworkProxyQuery::peerHostName

(

)

const

Returns the host name or IP address being of the outgoing connection being requested, or an empty string if the remote hostname is not known.

If the query type is QNetworkProxyQuery::UrlRequest, this function returns the host component of the URL being requested.

See also

peerPort(), localPort(), setPeerHostName()

Definition at line 1139 of file qnetworkproxy.cpp.

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

{
    return d ? d->remote.host() : QString();
}

peerPort()

int QNetworkProxyQuery::peerPort

(

)

const

Returns the port number for the outgoing request or -1 if the port number is not known.

If the query type is QNetworkProxyQuery::UrlRequest, this function returns the port number of the URL being requested. In general, frameworks will fill in the port number from their default values.

See also

peerHostName(), localPort(), setPeerPort()

Definition at line 1107 of file qnetworkproxy.cpp.

Referenced by QNetworkProxyFactory::systemProxyForQuery().

{
    return d ? d->remote.port() : -1;
}

protocolTag()

QString QNetworkProxyQuery::protocolTag

(

)

const

Returns the protocol tag for this QNetworkProxyQuery object, or an empty QString in case the protocol tag is unknown.

In the case of queries of type QNetworkProxyQuery::UrlRequest, this function returns the value of the scheme component of the URL.

See also

setProtocolTag(), url()

Definition at line 1205 of file qnetworkproxy.cpp.

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

{
    return d ? d->remote.scheme() : QString();
}

queryType()

QNetworkProxyQuery::QueryType QNetworkProxyQuery::queryType

(

)

const

Returns the query type.

Definition at line 1084 of file qnetworkproxy.cpp.

Referenced by filterProxyListByCapabilities(), QWindowsSystemProxy::init(), parseServerList(), and QNetworkProxyFactory::systemProxyForQuery().

{
    return d ? d->type : TcpSocket;
}

setLocalPort()

void QNetworkProxyQuery::setLocalPort

(

int

port

)

Sets the port number that the socket wishes to use locally to accept incoming packets from remote servers to port.

The local port is most often used with the QNetworkProxyQuery::TcpServer and QNetworkProxyQuery::UdpSocket query types.

Valid values are 0 to 65535 (with 0 indicating that any port number will be acceptable) or -1, which means the local port number is unknown or not applicable.

In some circumstances, for special protocols, it's the local port number can also be used with a query of type QNetworkProxyQuery::TcpSocket. When that happens, the socket is indicating it wishes to use the port number port when connecting to a remote host.

See also

localPort(), setPeerPort(), setPeerHostName()

Definition at line 1190 of file qnetworkproxy.cpp.

{
    d->localPort = port;
}

setNetworkConfiguration()

void QNetworkProxyQuery::setNetworkConfiguration

(

const QNetworkConfiguration &

networkConfiguration

)

Sets the network configuration component of this QNetworkProxyQuery object to be networkConfiguration.

Since

4.8

The network configuration can be used to return different proxy settings based on the network in use, for example WLAN vs cellular networks on a mobile phone.

In the case of "user choice" or "service network" configurations, you should first start the QNetworkSession and obtain the active configuration from its properties.

See also

networkConfiguration()

Definition at line 1282 of file qnetworkproxy.cpp.

{
    d->config = networkConfiguration;
}

setPeerHostName()

void QNetworkProxyQuery::setPeerHostName

(

const QString &

hostname

)

Sets the hostname of the outgoing connection being requested to hostname.

An empty hostname can be used to indicate that the remote host is unknown.

The peer host name can also be used to indicate the expected source address of an incoming connection in the case of QNetworkProxyQuery::UdpSocket or QNetworkProxyQuery::TcpServer query types.

See also

peerHostName(), setPeerPort(), setLocalPort()

Definition at line 1156 of file qnetworkproxy.cpp.

{
    d->remote.setHost(hostname);
}

setPeerPort()

void QNetworkProxyQuery::setPeerPort

(

int

port

)

Sets the requested port number for the outgoing connection to be port.

Valid values are 1 to 65535, or -1 to indicate that the remote port number is unknown.

The peer port number can also be used to indicate the expected port number of an incoming connection in the case of QNetworkProxyQuery::UdpSocket or QNetworkProxyQuery::TcpServer query types.

See also

peerPort(), setPeerHostName(), setLocalPort()

Definition at line 1124 of file qnetworkproxy.cpp.

{
    d->remote.setPort(port);
}

setProtocolTag()

void QNetworkProxyQuery::setProtocolTag

(

const QString &

protocolTag

)

Sets the protocol tag for this QNetworkProxyQuery object to be protocolTag.

The protocol tag is an arbitrary string that indicates which protocol is being talked over the socket, such as "http", "xmpp", "telnet", etc. The protocol tag is used by the backend to return a request that is more specific to the protocol in question: for example, a HTTP connection could be use a caching HTTP proxy server, while all other connections use a more powerful SOCKSv5 proxy server.

See also

protocolTag()

Definition at line 1224 of file qnetworkproxy.cpp.

{
    d->remote.setScheme(protocolTag);
}

setQueryType()

void QNetworkProxyQuery::setQueryType

(

QueryType

type

)

Sets the query type of this object to be type.

Definition at line 1092 of file qnetworkproxy.cpp.

{
    d->type = type;
}

setUrl()

void QNetworkProxyQuery::setUrl

(

const QUrl &

url

)

Sets the URL component of this QNetworkProxyQuery object to be url.

Setting the URL will also set the protocol tag, the remote host name and port number. This is done so as to facilitate the implementation of the code that determines the proxy server to be used.

See also

url(), peerHostName(), peerPort()

Definition at line 1249 of file qnetworkproxy.cpp.

{
    d->remote = url;
}

url()

QUrl QNetworkProxyQuery::url

(

)

const

Returns the URL component of this QNetworkProxyQuery object in case of a query of type QNetworkProxyQuery::UrlRequest.

See also

setUrl()

Definition at line 1235 of file qnetworkproxy.cpp.

Referenced by QWindowsSystemProxy::init(), macQueryInternal(), QGlobalNetworkProxy::proxyForQuery(), setUrl(), and QNetworkProxyFactory::systemProxyForQuery().

{
    return d ? d->remote : QUrl();
}

Properties

d

QSharedDataPointer<QNetworkProxyQueryPrivate> QNetworkProxyQuery::d

private

Definition at line 117 of file qnetworkproxy.h.

Referenced by localPort(), networkConfiguration(), operator=(), operator==(), peerHostName(), peerPort(), protocolTag(), queryType(), setLocalPort(), setNetworkConfiguration(), setPeerHostName(), setPeerPort(), setProtocolTag(), setQueryType(), setUrl(), and url().

---

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

• /src/network/kernel/qnetworkproxy.h
• /src/network/kernel/qnetworkproxy.cpp