QNetworkProxy 类
QNetworkProxy 类提供网络层代理功能。更多...
| 头文件 | #include <QNetworkProxy> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake | QT += network |
- 所有成员列表，包括继承成员
- QNetworkProxy 是 Network Programming API 的一部分，并且属于 Implicitly Shared Classes。
注意： 此类中所有函数都是可重入的。
公共类型
| flags | 能力 |
| 枚举 | 能力 { 通道能力，监听能力，UDP 通道能力，缓存能力，主机名查找能力，…，Sctp 监听能力 } |
| 枚举 | 代理类型 { 无代理，默认代理，Socks5 代理，Http 代理，Http 缓存代理，Ftp 缓存代理 } |
公共函数
| 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 | 类型() const |
| QString | 用户() const |
| bool | operator!=(const QNetworkProxy &；《i》 other）const |
| QNetworkProxy &； | operator=(const QNetworkProxy &；《i》 other） |
| bool | operator==(const QNetworkProxy &；《i》 other）const |
静态公共成员
| QNetworkProxy | applicationProxy() |
| void | setApplicationProxy(const QNetworkProxy &；《i》 networkProxy） |
详细说明
QNetworkProxy 为 Qt 网络类提供配置网络层代理支持的方法。目前支持的类包括 QAbstractSocket、QTcpSocket、QUdpSocket、QTcpServer 和 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() 使用的地址等效于 QHostAddress::LocalHost 或 QHostAddress::LocalHostIPv6，则不使用网络代理。
每种类型的代理支持都与某些限制相关联。在选择要使用的代理类型之前，请仔细阅读 ProxyType 文档。
注意：目前连接的套接字上的更改不会生效。如果您需要更改连接的套接字，则应重新连接它。
SOCKS5
Qt 4 及以后的 SOCKS5 支持基于 RFC 1928 和 RFC 1929。支持的认证方法是无认证和用户名/密码认证。支持 IPv4 和 IPv6。如果启用 QNetworkProxy::HostNameLookupCapability，则域名将通过 SOCKS5 服务器解析，否则将本地解析并将 IP 地址发送到服务器。使用 SOCKS5 与 QUdpSocket 和 QTcpServer 一起使用时，有一些需要注意的事项：
在使用 QUdpSocket 时，调用 bind() 可能会因为超时而失败。如果传递给 bind() 的端口号不是 0，则不能保证使用的是指定的端口号。使用 localPort() 和 localAddress() 获取实际使用的地址和端口号。因为通过代理的 UDP 通过两个 UDP 连接进行，因此数据包丢失的可能性更大。
使用 QTcpServer，对 listen() 方法的调用可能会因超时错误而失败。如果向 listen() 方法传入的不是 0 的端口号，则不能保证使用的是指定的端口。请使用 serverPort() 和 serverAddress() 来获取实际用于监听连接的地址和端口。SOCKS5 只支持每个 listen() 调用接受一个连接，并且每个调用可能使用不同的 serverPort()。
另请参阅QAbstractSocket 和 QTcpServer。
成员类型文档
枚举 QNetworkProxy::Capability
标志 QNetworkProxy::Capabilities
这些标志指示给定的代理服务器支持的功能。
QNetworkProxy 在创建对象时默认设置不同的功能（有关默认值列表，请参阅 QNetworkProxy::ProxyType）。然而，可以使用 setCapabilities() 在对象创建后更改这些功能。
QNetworkProxy 支持的功能有
| 常量 | 值 | 描述 |
|---|---|---|
QNetworkProxy::TunnelingCapability | 0x0001 | 能够为远程主机打开透明、隧道化的 TCP 连接。代理服务器直接传送两边的数据，不进行缓存。 |
QNetworkProxy::ListeningCapability | 0x0002 | 能够在远程主机上创建监听套接字并等待来自远程主机的 TCP 连接。 |
QNetworkProxy::UdpTunnelingCapability | 0x0004 | 能够通过代理服务器中继来自和指向远程主机的 UDP 数据报。 |
QNetworkProxy::CachingCapability | 0x0008 | 能够缓存传输的内容。此功能特定于每个协议和代理类型。例如，HTTP 代理可以缓存使用 "GET" 命令传输的网页数据。 |
QNetworkProxy::HostNameLookupCapability | 0x0010 | 能够连接到远程主机名进行查询并连接到它，而不是要求应用程序只对 IP 地址执行名称查询并请求连接。 |
QNetworkProxy::SctpTunnelingCapability | 0x00020 | 能够为远程主机打开透明、隧道化的 SCTP 连接。 |
QNetworkProxy::SctpListeningCapability | 0x00040 | 能够在远程主机上创建监听套接字并等待来自远程主机的 SCTP 连接。 |
Capabilities 类型是 QFlags<Capability> 的 typedef。它存储了一个或操作 Capability 值。
枚举 QNetworkProxy::ProxyType
此枚举描述了 Qt 提供的网络代理类型。
Qt 理解两种代理类型：透明代理和缓存代理。第一组包括可以处理任何任意数据传输的代理，而第二组只能处理特定请求。缓存代理只适用于可以使用的特定类。
| 常量 | 值 | 描述 |
|---|---|---|
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、绑定到端口（入站连接）和认证。 | 隧道能力，监听能力，UDP隧道能力，域名解析能力 |
| HTTP | 使用“CONNECT”命令实现，仅支持出站TCP连接；支持认证。 | 隧道能力，缓存能力，域名解析能力 |
| 仅缓存HTTP | 使用正常的HTTP命令实现，仅在HTTP请求的上下文中非常有用（见QNetworkAccessManager） | 缓存能力，域名解析能力 |
| 缓存FTP | 使用FTP代理实现，仅在FTP请求的上下文中非常有用（见QNetworkAccessManager） | 缓存能力，域名解析能力 |
还请注意，不要将应用程序默认代理（setApplicationProxy（））设置为没有隧道能力功能的代理。如果这样做，QTcpSocket将不知道如何打开连接。
另请参阅setType（），type（），capabilities（）和setCapabilities（）。
成员函数文档
QNetworkProxy::QNetworkProxy()
使用默认代理类型DefaultProxy构造QNetworkProxy。
代理类型由applicationProxy决定，默认为NoProxy或者系统范围内的代理（如果已配置）。
另请参阅setTypesetApplicationProxy（）。
QNetworkProxy::QNetworkProxy(QNetworkProxy::ProxyType type, const QString &hostName = QString(), quint16 port = 0, const QString &user = Quran(), const QString &password = QString())
使用类型、主机名、端口、用户和密码构造QNetworkProxy。
代理类型的默认特性将自动设置。
另请参阅capabilities（）。
QNetworkProxy::QNetworkProxy(const QNetworkProxy &other)
构建其它的一个副本。
[noexcept] QNetworkProxy::~QNetworkProxy()
销毁QNetworkProxy对象。
[static] QNetworkProxy QNetworkProxy::applicationProxy()
返回应用程序级别的网络代理。
如果QAbstractSocket或QTcpSocket具有QNetworkProxy::DefaultProxy类型，则该函数返回的QNetworkProxy将被使用。
另请参阅QNetworkProxyFactory、setApplicationProxy（）QAbstractSocket::proxy（）和QTcpServer::proxy（）。
QNetworkProxy::Capabilities QNetworkProxy::capabilities() const
返回此代理服务器的功能。
另请参阅setCapabilities（）和type（）。
bool QNetworkProxy::hasRawHeader(const QByteArray &headerName) const
如果未使用原始头headerName，则返回true。如果代理不是HttpProxy或HttpCachingProxy类型，则返回false。
另请参阅rawHeader（）和setRawHeader（）。
QVariant QNetworkProxy::header(QNetworkRequest::KnownHeaders header) const
如果未使用已知网络头header，则返回QVariant（）（即，一个无效的版本）。
另请参阅QNetworkRequest::KnownHeaders、rawHeader（）和setHeader（）。
QString QNetworkProxy::hostName() const
返回代理主机的主机名。
另请参阅setHostName（）、setPort（）和port（）。
bool QNetworkProxy::isCachingProxy() const
如果此代理支持QNetworkProxy::CachingCapability功能，则返回true。
在Qt 4.4中，此功能与代理类型相关联，但自Qt 4.5以来，可以通过调用setCapabilities（），从代理中删除缓存功能。
另请参阅capabilities（）、type（）和isTransparentProxy（）。
bool QNetworkProxy::isTransparentProxy() const
如果此代理支持通过网络连接进行透明隧道传输，则返回true。这与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
返回头 headerName 的原始形式。如果没有这样的头或代理类型不是HttpProxy或HttpCachingProxy，则返回一个空的QByteArray，这可能无法与没有内容的头区分开来（使用hasRawHeader()来确定头是否存在）。
可以使用setRawHeader()或setHeader()来设置原始头。
另请参阅 header()和setRawHeader()。
QList<QByteArray> QNetworkProxy::rawHeaderList() const
返回在此网络代理中设置的所有原始头的列表。列表是按照设置头的顺序排列的。
如果代理类型不是HttpProxy或HttpCachingProxy，则返回一个空的QList。
另请参阅 hasRawHeader()和rawHeader()。
[静态] void QNetworkProxy::setApplicationProxy(const QNetworkProxy &networkProxy)
设置应用程序级别网络代理为networkProxy。
如果QAbstractSocket或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)
将已知头header的值设置为value，覆盖之前设置的任何头。此操作还设置等效的原始HTTP头。
如果代理不是类型HttpProxy或HttpCachingProxy，则此设置无效。
另请参阅QNetworkRequest::KnownHeaders、setRawHeader()以及header()。
void QNetworkProxy::setHostName(const QString &hostName)
将代理主机的主机名设置为hostName。
void QNetworkProxy::setPassword(const QString &password)
将代理身份验证的密码设置为password。
void QNetworkProxy::setPort(quint16 port)
将代理主机端设置为port。
另请参阅hostName、setHostName和port。
void QNetworkProxy::setRawHeader(const QByteArray &headerName, const QByteArray &headerValue)
将头部headerName设置为值headerValue。如果headerName对应于已知头部（请参阅QNetworkRequest::KnownHeaders），则会解析原始格式，并将对应的"熟"头也设置为。
例如
request.setRawHeader(QByteArray("Last-Modified"), QByteArray("Sun, 06 Nov 1994 08:49:37 GMT"));
也将已知头部LastModifiedHeader设置为解析的日期的QDateTime对象。
注意：多次设置相同的头部会覆盖之前的设置。如果想完成多个具有相同名称的HTTP头，应该将两个值用逗号（",")分隔，并设置一个单一的原始头。
如果代理不是类型HttpProxy或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。
© 2024 The Qt Company Ltd. 文档贡献归各自所有者所有。提供的文档受GNU自由文档许可协议第1.3版的条款约束，由自由软件基金会发布。Qt和相应的标志是芬兰以及/或其他国家的The Qt Company Ltd.的商标。所有其他商标归各自所有者所有。
