Contents

• Public Types
• Public Functions
• Detailed Description

Detailed Description

TheQNetworkProxyQuery class is used to query the proxy settings for a socket

QNetworkProxyQuery holds the details of a socket being created or request being made. It is used byQNetworkProxy andQNetworkProxyFactory 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 thehostName parameter passed toQTcpSocket::connectToHost() or the host component of a URL requested withQNetworkRequest.

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.

It should be noted that any of the criteria may be missing or unknown (an emptyQString 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.

Member Type Documentation

enum QNetworkProxyQuery::QueryType

Describes the type of oneQNetworkProxyQuery query.

See alsoqueryType() andsetQueryType().

Member Function Documentation

QNetworkProxyQuery::QNetworkProxyQuery()

Constructs a defaultQNetworkProxyQuery object. By default, the query type will beQNetworkProxyQuery::TcpSocket.

QNetworkProxyQuery::QNetworkProxyQuery(constQUrl & requestUrl,QueryType queryType = UrlRequest)

Constructs aQNetworkProxyQuery with the URLrequestUrl and sets the query type toqueryType.

See alsoprotocolTag(),peerHostName(), andpeerPort().

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

Constructs aQNetworkProxyQuery of typequeryType and sets the protocol tag to beprotocolTag. This constructor is suitable forQNetworkProxyQuery::TcpSocket queries, because it sets the peer hostname tohostname and the peer's port number toport.

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

Constructs aQNetworkProxyQuery of typequeryType and sets the protocol tag to beprotocolTag. This constructor is suitable forQNetworkProxyQuery::TcpSocket queries because it sets the local port number tobindPort.

Note thatbindPort 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 alsolocalPort().

QNetworkProxyQuery::QNetworkProxyQuery(constQNetworkProxyQuery & other)

Constructs aQNetworkProxyQuery object that is a copy ofother.

QNetworkProxyQuery::QNetworkProxyQuery(constQNetworkConfiguration & networkConfiguration, constQUrl & requestUrl,QueryType queryType = UrlRequest)

Constructs aQNetworkProxyQuery with the URLrequestUrl and sets the query type toqueryType. The specifiednetworkConfiguration is used to resolve the proxy settings.

This function was introduced in Qt 4.8.

See alsoprotocolTag(),peerHostName(),peerPort(), andnetworkConfiguration().

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

Constructs aQNetworkProxyQuery of typequeryType and sets the protocol tag to beprotocolTag. This constructor is suitable forQNetworkProxyQuery::TcpSocket queries, because it sets the peer hostname tohostname and the peer's port number toport. The specifiednetworkConfiguration is used to resolve the proxy settings.

This function was introduced in Qt 4.8.

See alsonetworkConfiguration().

QNetworkProxyQuery::QNetworkProxyQuery(constQNetworkConfiguration & networkConfiguration,quint16 bindPort, constQString & protocolTag = QString(),QueryType queryType = TcpServer)

Constructs aQNetworkProxyQuery of typequeryType and sets the protocol tag to beprotocolTag. This constructor is suitable forQNetworkProxyQuery::TcpSocket queries because it sets the local port number tobindPort. The specifiednetworkConfiguration is used to resolve the proxy settings.

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

This function was introduced in Qt 4.8.

See alsolocalPort() andnetworkConfiguration().

QNetworkProxyQuery::~QNetworkProxyQuery()

Destroys thisQNetworkProxyQuery object.

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 alsopeerPort(),peerHostName(), andsetLocalPort().

QNetworkConfiguration QNetworkProxyQuery::networkConfiguration() const

Returns the network configuration of the proxy query.

See alsosetNetworkConfiguration().

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 isQNetworkProxyQuery::UrlRequest, this function returns the host component of the URL being requested.

See alsopeerPort(),localPort(), andsetPeerHostName().

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 isQNetworkProxyQuery::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 alsopeerHostName(),localPort(), andsetPeerPort().

QString QNetworkProxyQuery::protocolTag() const

Returns the protocol tag for thisQNetworkProxyQuery object, or an emptyQString in case the protocol tag is unknown.

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

See alsosetProtocolTag() andurl().

QueryType QNetworkProxyQuery::queryType() const

Returns the query type.

See alsosetQueryType().

void QNetworkProxyQuery::setLocalPort(int port)

Sets the port number that the socket wishes to use locally to accept incoming packets from remote servers toport. The local port is most often used with theQNetworkProxyQuery::TcpServer andQNetworkProxyQuery::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 typeQNetworkProxyQuery::TcpSocket. When that happens, the socket is indicating it wishes to use the port numberport when connecting to a remote host.

See alsolocalPort(),setPeerPort(), andsetPeerHostName().

void QNetworkProxyQuery::setNetworkConfiguration(constQNetworkConfiguration & networkConfiguration)

Sets the network configuration component of thisQNetworkProxyQuery object to benetworkConfiguration. 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 theQNetworkSession and obtain the active configuration from its properties.

This function was introduced in Qt 4.8.

See alsonetworkConfiguration().

void QNetworkProxyQuery::setPeerHostName(constQString & hostname)

Sets the hostname of the outgoing connection being requested tohostname. 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 ofQNetworkProxyQuery::UdpSocket orQNetworkProxyQuery::TcpServer query types.

See alsopeerHostName(),setPeerPort(), andsetLocalPort().

void QNetworkProxyQuery::setPeerPort(int port)

Sets the requested port number for the outgoing connection to beport. 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 ofQNetworkProxyQuery::UdpSocket orQNetworkProxyQuery::TcpServer query types.

See alsopeerPort(),setPeerHostName(), andsetLocalPort().

void QNetworkProxyQuery::setProtocolTag(constQString & protocolTag)

Sets the protocol tag for thisQNetworkProxyQuery object to beprotocolTag.

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

void QNetworkProxyQuery::setQueryType(QueryType type)

Sets the query type of this object to betype.

See alsoqueryType().

void QNetworkProxyQuery::setUrl(constQUrl & url)

Sets the URL component of thisQNetworkProxyQuery object to beurl. 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 alsourl(),peerHostName(), andpeerPort().

QUrl QNetworkProxyQuery::url() const

Returns the URL component of thisQNetworkProxyQuery object in case of a query of typeQNetworkProxyQuery::UrlRequest.

See alsosetUrl().

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

Returns true if thisQNetworkProxyQuery object does not contain the same data asother.

QNetworkProxyQuery & QNetworkProxyQuery::operator=(constQNetworkProxyQuery & other)

Copies the contents ofother.

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

Returns true if thisQNetworkProxyQuery object contains the same data asother.