QNetworkProxy 类

QNetworkProxy 类提供网络层代理。 更多...

头：	#include <QNetworkProxy>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake:	QT += network

• 所有成员列表，包括继承成员
• QNetworkProxy is part of 网络编程 API and 隐式共享类 .

注意： 此类的所有函数 可重入 .

公共类型

flags	Capabilities
enum	Capability { TunnelingCapability, ListeningCapability, UdpTunnelingCapability, CachingCapability, HostNameLookupCapability, …, SctpListeningCapability }
enum	ProxyType { NoProxy, DefaultProxy, Socks5Proxy, HttpProxy, HttpCachingProxy, FtpCachingProxy }

公共函数

	QNetworkProxy ()
	QNetworkProxy (QNetworkProxy::ProxyType type , const QString & hostName = QString(), quint16 port = 0, const QString & user = QString(), const QString & password = QString())
	QNetworkProxy (const QNetworkProxy & other )
	~QNetworkProxy ()
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
QString	password () const
quint16	port () const
QByteArray	rawHeader (const QByteArray & headerName ) const
QList<QByteArray>	rawHeaderList () const
void	setCapabilities (QNetworkProxy::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 & user )
void	swap (QNetworkProxy & other )
QNetworkProxy::ProxyType	type () const
QString	user () const
bool	operator!= (const QNetworkProxy & other ) const
QNetworkProxy &	operator= (const QNetworkProxy & other )
bool	operator== (const QNetworkProxy & other ) const

静态公共成员

QNetworkProxy	applicationProxy ()
void	setApplicationProxy (const QNetworkProxy & networkProxy )

详细描述

QNetworkProxy 提供了为 Qt Network 类配置网络层代理支持的方法。目前，支持的类是 QAbstractSocket , QTcpSocket , QUdpSocket , QTcpServer and QNetworkAccessManager 。代理支持被设计成尽可能透明。这意味着已编写的现有启用网络的应用程序，应该使用以下代码自动支持网络代理。

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

设置应用程序范围代理的备选方案是为各个套接字指定代理，使用 QAbstractSocket::setProxy () 和 QTcpServer::setProxy ()。在此方式下，使用以下代码禁用特定套接字代理的使用是可能的：

serverSocket->setProxy(QNetworkProxy::NoProxy);
					

网络代理不会被使用，若地址用在 connectToHost (), bind () 或 listen () is equivalent to QHostAddress::LocalHost or QHostAddress::LocalHostIPv6 .

代理支持的各种类型都有与其关联的某些限定。应该阅读 ProxyType 文档编制，要小心谨慎在选择要使用的代理类型之前。

注意： 对目前已连接套接字所做的更改，不会生效。若需要更改已连接套接字，应重新连接它。

SOCKS5

从 Qt4 起 SOCKS5 的支持基于 RFC 1928 and RFC 1929 。支持的身份验证方法是无身份验证和用户名/密码身份验证。IPv4 和 IPv6 均支持。通过 SOCKS5 服务器解析域名若 QNetworkProxy::HostNameLookupCapability 被启用，否则，在本地解析它们并把 IP 地址发送给服务器。有几件事要记住当使用 SOCKS5 采用 QUdpSocket and QTcpServer :

采用 QUdpSocket 调用 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 () 和 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.

采用 QTcpServer 调用 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 () 和 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.

另请参阅 QAbstractSocket and QTcpServer .

成员类型文档编制

enum QNetworkProxy:: Capability
flags QNetworkProxy:: Capabilities

这些标志指示给定代理服务器支持的能力。

QNetworkProxy 默认设置不同能力，当创建对象时 (见 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:

常量	值	描述
QNetworkProxy::TunnelingCapability	0x0001	能打开到远程主机的透明、隧道化 TCP 连接。代理服务器将从一侧到另一侧逐字传输且不进行缓存。
QNetworkProxy::ListeningCapability	0x0002	能创建监听套接字并等待来自远程主机的 TCP 连接。
QNetworkProxy::UdpTunnelingCapability	0x0004	能中继 UDP 数据报凭借代理服务器和远程主机。
QNetworkProxy::CachingCapability	0x0008	能缓存传输内容。此能力特定于每种协议和代理类型。例如：HTTP 代理可以缓存采用 GET 命令传输的 Web 数据内容。
QNetworkProxy::HostNameLookupCapability	0x0010	能连接以履行查找远程主机名并连接到远程主机，而不是要求应用程序履行名称查找并只请求连接到 IP 地址。
QNetworkProxy::SctpTunnelingCapability	0x00020	能打开到远程主机的透明、隧道化 SCTP 连接。
QNetworkProxy::SctpListeningCapability	0x00040	能创建监听套接字并等待来自远程主机的传入 SCTP 连接。

Capabilities 类型是 typedef 对于 QFlags <Capability>。它存储 Capability 值的 OR 组合。

enum QNetworkProxy:: ProxyType

此枚举描述 Qt 提供的网络代理类型。

Qt 理解的 2 种代理类型：透明代理和缓存代理。第 1 组由可以处理任意数据传输的代理组成，而第 2 组只能处理特定请求。缓存代理只对可以使用它们的特定类有意义。

常量	值	描述
QNetworkProxy::NoProxy	2	不使用代理
QNetworkProxy::DefaultProxy	0	基于应用程序代理设置确定代理，使用 setApplicationProxy ()
QNetworkProxy::Socks5Proxy	1	Socks5 代理被使用
QNetworkProxy::HttpProxy	3	使用 HTTP 透明代理
QNetworkProxy::HttpCachingProxy	4	代理仅针对 HTTP 请求
QNetworkProxy::FtpCachingProxy	5	代理仅针对 FTP 请求

下表列出了不同的代理类型及其能力。由于每种代理类型有不同能力，在选取代理类型之前理解它们很重要。

代理类型	描述	默认能力
SOCKS 5	用于任何连接种类的通用代理。支持 TCP、UDP、绑定到端口 (传入连接) 及身份验证。	TunnelingCapability , ListeningCapability , UdpTunnelingCapability , HostNameLookupCapability
HTTP	使用 CONNECT 命令实现，仅支持传出 TCP 连接；支持身份验证。	TunnelingCapability , CachingCapability , HostNameLookupCapability
仅缓存 HTTP	使用正常 HTTP 命令实现，仅在 HTTP 请求上下文中有用 (见 QNetworkAccessManager )	CachingCapability , HostNameLookupCapability
缓存 FTP	使用 FTP 代理实现，仅在 FTP 请求上下文中有用 (见 QNetworkAccessManager )	CachingCapability , HostNameLookupCapability

另请注意：不应该设置应用程序默认代理 ( setApplicationProxy ()) 到代理没有 TunnelingCapability 能力。若做了， QTcpSocket 将不知道如何打开连接。

另请参阅 setType (), type (), capabilities ()，和 setCapabilities ().

成员函数文档编制

QNetworkProxy:: QNetworkProxy ()

构造 QNetworkProxy 采用 DefaultProxy 类型。

代理类型的确定通过 applicationProxy ()，默认为 NoProxy 或系统范围代理，若配置了的话。

另请参阅 setType () 和 setApplicationProxy ().

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

构造 QNetworkProxy 采用 type , hostName , port , user and password .

默认能力的代理类型 type 是自动设置的。

另请参阅 capabilities ().

QNetworkProxy:: QNetworkProxy (const QNetworkProxy & other )

构造副本为 other .

[noexcept] QNetworkProxy:: ~QNetworkProxy ()

销毁 QNetworkProxy 对象。

[static] QNetworkProxy QNetworkProxy:: applicationProxy ()

返回应用程序级别的网络代理。

若 QAbstractSocket or QTcpSocket 拥有 QNetworkProxy::DefaultProxy 类型，那么 QNetworkProxy 被返回通过使用此函数。

另请参阅 QNetworkProxyFactory , setApplicationProxy (), QAbstractSocket::proxy ()，和 QTcpServer::proxy ().

QNetworkProxy::Capabilities QNetworkProxy:: capabilities () const

返回此代理服务器的能力。

另请参阅 setCapabilities () 和 type ().

bool QNetworkProxy:: hasRawHeader (const QByteArray & headerName ) const

返回 true 若原生 Header (头) headerName 被此代理使用。返回 false 若代理不是类型 HttpProxy or HttpCachingProxy .

另请参阅 rawHeader () 和 setRawHeader ().

QVariant QNetworkProxy:: header ( QNetworkRequest::KnownHeaders header ) const

返回已知网络 Header (头) 的值为 header 若它被此代理所用。若不存在，返回 QVariant() (即：无效变体)。

另请参阅 QNetworkRequest::KnownHeaders , rawHeader ()，和 setHeader ().

QString QNetworkProxy:: hostName () const

返回代理主机的主机名。

另请参阅 setHostName (), setPort ()，和 port ().

bool QNetworkProxy:: isCachingProxy () const

返回 true 若此代理支持 QNetworkProxy::CachingCapability 能力。

在 Qt 4.4，能力被绑到代理类型，但从 Qt 4.5 起，移除代理缓存能力是可能的通过调用 setCapabilities ().

另请参阅 capabilities (), type ()，和 isTransparentProxy ().

bool QNetworkProxy:: isTransparentProxy () const

返回 true 若此代理支持透明隧道化的 TCP 连接。这匹配 QNetworkProxy::TunnelingCapability 能力。

在 Qt 4.4，能力被绑到代理类型，但从 Qt 4.5 起，移除代理缓存能力是可能的通过调用 setCapabilities ().

另请参阅 capabilities (), type ()，和 isCachingProxy ().

QString QNetworkProxy:: password () const

返回用于身份验证的口令。

另请参阅 user (), setPassword ()，和 setUser ().

quint16 QNetworkProxy:: port () const

返回代理主机的端口。

另请参阅 setHostName (), setPort ()，和 hostName ().

QByteArray QNetworkProxy:: rawHeader (const QByteArray & headerName ) const

返回 Header (头) 的原生形式为 headerName 。若不存在这种 Header (头) 或代理类型不是 HttpProxy or HttpCachingProxy ，空 QByteArray 被返回，可能难以区分存在但没有内容的 Header 头 (使用 hasRawHeader () 以确定 Header 头是否存在)。

可以设置原生 Header (头) 采用 setRawHeader () 或采用 setHeader ().

另请参阅 header () 和 setRawHeader ().

QList < QByteArray > QNetworkProxy:: rawHeaderList () const

返回在此网络代理中设置的所有原生 Header (头) 的列表。列表按 Header (头) 设置次序排列。

若代理不是类型 HttpProxy or HttpCachingProxy 空 QList 被返回。

另请参阅 hasRawHeader () 和 rawHeader ().

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

把应用程序级别的网络代理设为 networkProxy .

若 QAbstractSocket or QTcpSocket 拥有 QNetworkProxy::DefaultProxy 类型，那么 QNetworkProxy 采用此函数所用设置。若希望在确定使用哪种代理方面更具灵活性，使用 QNetworkProxyFactory 类。

通过此函数设置的默认代理值将覆盖应用程序代理工厂设置采用 QNetworkProxyFactory::setApplicationProxyFactory ，并禁用系统代理的使用。

另请参阅 QNetworkProxyFactory , applicationProxy (), QAbstractSocket::setProxy ()，和 QTcpServer::setProxy ().

void QNetworkProxy:: setCapabilities ( QNetworkProxy::Capabilities capabilities )

将此代理的能力设为 capabilities .

另请参阅 setType () 和 capabilities ().

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

Sets the value of the known header header 到 value ，覆盖任何先前设置的 Header (头)。此操作还设置等效原生 HTTP (头)。

若代理不是类型 HttpProxy or HttpCachingProxy 这没有效果。

另请参阅 QNetworkRequest::KnownHeaders , setRawHeader ()，和 header ().

void QNetworkProxy:: setHostName (const QString & hostName )

把代理主机的主机名设为 hostName .

另请参阅 hostName (), setPort ()，和 port ().

void QNetworkProxy:: setPassword (const QString & password )

把代理身份验证的口令设为 password .

另请参阅 user (), setUser ()，和 password ().

void QNetworkProxy:: setPort ( quint16 port )

把代理主机的端口设为 port .

另请参阅 hostName (), setHostName ()，和 port ().

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

设置 Header (头) headerName 到值 headerValue 。若 headerName 对应已知 Header (头部) (见 QNetworkRequest::KnownHeaders )，原生格式将被剖析，相应 cooked 头也将被设置。

例如：

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

还会把已知 LastModifiedHeader 头设为 QDateTime 剖析日期对象。

注意： 设置相同的头 2 次覆盖先前设置。要完成相同名称多个 HTTP 头的行为，应采用逗号 , 分隔它们并串联这 2 个值，然后设置一个原生 Header (头)。

若代理不是类型 HttpProxy or HttpCachingProxy 这没有效果。

另请参阅 QNetworkRequest::KnownHeaders , setHeader (), hasRawHeader ()，和 rawHeader ().

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

把此实例的代理类型设为 type .

注意：更改代理类型不会改变设置能力由此 QNetworkProxy 对象保持的，若有设置任何能力采用 setCapabilities ().

另请参阅 type () 和 setCapabilities ().

void QNetworkProxy:: setUser (const QString & user )

把代理身份验证的用户名设为 user .

另请参阅 user (), setPassword ()，和 password ().

[noexcept] void QNetworkProxy:: swap ( QNetworkProxy & other )

交换此网络代理实例采用 other 。此函数非常快且从不失败。

QNetworkProxy::ProxyType QNetworkProxy:: type () const

返回此实例的代理类型。

另请参阅 setType ().

QString QNetworkProxy:: user () const

返回用于身份验证的用户名。

另请参阅 setUser (), setPassword ()，和 password ().

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

比较此网络代理的值与 other 并返回 true 若它们不同。

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

赋值网络代理值 other 到此网络代理。

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

比较此网络代理的值与 other 并返回 true 若它们相等 (相同的代理类型、服务器及用户名 口令)

内容

• 公共类型

• 公共函数

• 静态公共成员

• 详细描述

• SOCKS5