QNetworkAccessManager Class

QNetworkAccessManager *manager = new QNetworkAccessManager(this);
connect(manager, &QNetworkAccessManager::finished,
        this, &MyClass::replyFinished);

manager->get(QNetworkRequest(QUrl("http://qt-project.org")));

QNetworkRequest request;
request.setUrl(QUrl("http://qt-project.org"));
request.setRawHeader("User-Agent", "MyOwnBrowser 1.0");

QNetworkReply *reply = manager->get(request);
connect(reply, &QIODevice::readyRead, this, &MyClass::slotReadyRead);
connect(reply, &QNetworkReply::errorOccurred,
        this, &MyClass::slotError);
connect(reply, &QNetworkReply::sslErrors,
        this, &MyClass::slotSslErrors);

QNetworkRequest networkRequest(url);
networkRequest.setTcpKeepAliveIdleTimeBeforeProbes(20s);
networkRequest.setTcpKeepAliveIntervalBetweenProbes(2s);
networkRequest.setTcpKeepAliveProbeCount(5);

成员函数文档

[explicit] QNetworkAccessManager::QNetworkAccessManager(QObject *parent = nullptr)

创建一个 QNetworkAccessManager 对象，该对象是网络访问 API 的核心，并将parent 设置为父对象。

[virtual noexcept] QNetworkAccessManager::~QNetworkAccessManager()

销毁QNetworkAccessManager 对象并释放所有资源。请注意，该类返回的QNetworkReply 对象均将此对象设为其父对象，这意味着如果未对它们调用QObject::setParent()方法，它们将随此对象一同被删除。

void QNetworkAccessManager::addStrictTransportSecurityHosts(const QList<QHstsPolicy> &knownHosts)

将 HTTP Strict Transport Security 策略添加到 HSTS 缓存中。knownHosts 包含已知的、带有QHstsPolicy 信息的主机。

另请参阅 strictTransportSecurityHosts()、enableStrictTransportSecurityStore() 以及QHstsPolicy 。

[signal] void QNetworkAccessManager::authenticationRequired(QNetworkReply *reply, QAuthenticator *authenticator)

每当最终服务器在交付所请求的内容之前要求进行身份验证时，都会发出此信号。连接到此信号的槽应将内容的凭据（可通过检查reply 对象来确定）填入authenticator 对象中。

QNetworkAccessManager 系统会在内部缓存凭据，若服务器再次要求认证，将直接发送相同的值，而不会发出 authenticationRequired() 信号。如果服务器拒绝该凭据，则会再次发出此信号。

另请参阅 proxyAuthenticationRequired()、QAuthenticator::setUser() 和QAuthenticator::setPassword()。

bool QNetworkAccessManager::autoDeleteReplies() const

如果QNetworkAccessManager 当前配置为自动删除QNetworkReplies，则返回true；否则返回false。

另请参阅 setAutoDeleteReplies 和QNetworkRequest::AutoDeleteReplyOnFinishAttribute 。

QAbstractNetworkCache *QNetworkAccessManager::cache() const

返回用于存储从网络获取的数据的缓存。

另请参阅 setCache()。

void QNetworkAccessManager::clearAccessCache()

清空身份验证数据和网络连接的内部缓存。

此函数在执行自动化测试时非常有用。

另请参阅 clearConnectionCache()。

void QNetworkAccessManager::clearConnectionCache()

清空网络连接的内部缓存。与clearAccessCache()不同，此操作会保留身份验证数据。

另请参阅 clearAccessCache()。

void QNetworkAccessManager::connectToHost(const QString &hostName, quint16 port = 80)

向由hostName 指定的主机上的port 端口发起连接。该函数有助于在发送HTTP请求之前先与主机完成TCP握手，从而降低网络延迟。

另请参阅 connectToHostEncrypted()、get()、post()、put() 和deleteResource()。

void QNetworkAccessManager::connectToHostEncrypted(const QString &hostName, quint16 port = 443, const QSslConfiguration &sslConfiguration = QSslConfiguration::defaultConfiguration())

使用sslConfiguration 协议，向由hostName 指定的主机上的port 端口发起连接。该函数有助于在发出 HTTPS 请求之前先与主机完成 TCP 和 SSL 握手，从而降低网络延迟。

另请参阅 connectToHost()、get()、post()、put() 以及deleteResource()。

void QNetworkAccessManager::connectToHostEncrypted(const QString &hostName, quint16 port, const QSslConfiguration &sslConfiguration, const QString &peerName)

使用sslConfiguration （其中peerName 被设置为用于证书验证的主机名）通过 向由hostName 指定的主机发起连接，端口为port 。此函数有助于在发出 HTTPS 请求之前先与主机完成 TCP 和 SSL 握手，从而降低网络延迟。

另请参阅 connectToHost()、get()、post()、put() 以及deleteResource()。

QNetworkCookieJar *QNetworkAccessManager::cookieJar() const

返回用于存储从网络获取的 Cookie 以及即将发送的 Cookie 的 `QNetworkCookieJar ` 对象。

另请参阅 setCookieJar()。

[virtual protected] QNetworkReply *QNetworkAccessManager::createRequest(QNetworkAccessManager::Operation op, const QNetworkRequest &originalReq, QIODevice *outgoingData = nullptr)

返回一个新的QNetworkReply 对象，用于处理op 操作和originalReq 请求。对于Get和Head请求，设备outgoingData 始终为0，但在这些操作中，该参数是传递给post()和put()的方法参数（QByteArray 变体将传递一个QBuffer 对象）。

默认实现会调用QNetworkCookieJar::cookiesForUrl()方法，对通过setCookieJar()设置的Cookie存储器进行操作，以获取要发送给远程服务器的Cookie。

返回的对象必须处于打开状态。

QNetworkReply *QNetworkAccessManager::deleteResource(const QNetworkRequest &request)

向 URL 为request 的资源发送删除请求。

另请参阅 get()、post()、put() 以及sendCustomRequest()。

void QNetworkAccessManager::enableStrictTransportSecurityStore(bool enabled, const QString &storeDir = QString())

如果enabled 的值为true ，则内部HSTS缓存将使用持久化存储来读写HSTS策略。storeDir 定义了该存储的位置。默认位置由QStandardPaths::CacheLocation 定义。如果没有可写入的QStandartPaths::CacheLocation，且storeDir 为空字符串，则存储将位于程序的工作目录中。

拥有存储文件写入权限的攻击者可以删除特定域的 HSTS 条目，导致应用程序在后续请求中允许与这些域建立明文 HTTP 连接，从而可能引发 SSL 剥离攻击。依赖 HSTS 的应用程序应确保存储目录受到适当的文件系统权限保护。

另请参阅 isStrictTransportSecurityStoreEnabled()、setStrictTransportSecurityEnabled() 和QStandardPaths::standardLocations()。

[signal] void QNetworkAccessManager::encrypted(QNetworkReply *reply)

当 SSL/TLS 会话成功完成初始握手时，会发出此信号。此时，尚未传输任何用户数据。该信号可用于对证书链进行额外检查，例如在网站证书发生变更时通知用户。reply 参数指定了负责此操作的网络响应。如果响应不符合预期条件，则应由连接到此信号的插槽通过调用QNetworkReply::abort()来中止该响应。可使用QNetworkReply::sslConfiguration()方法检查当前使用的SSL配置。

在内部，QNetworkAccessManager 可能会向服务器建立多个连接，以便并行处理请求。这些连接可能会被重复使用，这意味着不会发出 encrypted() 信号。这意味着在QNetworkAccessManager 的生命周期内，您仅能保证在与该网站建立的第一个连接时收到此信号。

另请参阅 QSslSocket::encrypted() 和QNetworkReply::encrypted()。

[signal] void QNetworkAccessManager::finished(QNetworkReply *reply)

每当一个待处理的网络响应完成时，都会触发此信号。reply 参数将包含指向刚刚完成的响应的指针。此信号会与QNetworkReply::finished()信号同时触发。

有关对象将处于何种状态的信息，请参阅QNetworkReply::finished()。

另请参阅 QNetworkReply::finished() 和QNetworkReply::error()。

QNetworkReply *QNetworkAccessManager::get(const QNetworkRequest &request)

向目标request 发送请求以获取其内容，并返回一个以读取模式打开的新QNetworkReply 对象，该对象会在有新数据到达时触发readyRead()信号。

内容及相关标头都将被下载。

另请参阅 post()、put()、deleteResource() 和sendCustomRequest()。

[since 6.7] QNetworkReply *QNetworkAccessManager::get(const QNetworkRequest &request, QIODevice *data)

该函数在 Qt 6.7 中引入。

[since 6.7] QNetworkReply *QNetworkAccessManager::get(const QNetworkRequest &request, const QByteArray &data)

该函数在 Qt 6.7 中引入。

QNetworkReply *QNetworkAccessManager::head(const QNetworkRequest &request)

向request 发送请求以获取网络头信息，并返回一个新的QNetworkReply 对象，该对象将包含这些头信息。

该函数的名称源自其关联的 HTTP 请求（HEAD）。

bool QNetworkAccessManager::isStrictTransportSecurityEnabled() const

如果启用了 HTTP 严格传输安全 (HSTS)，则返回 true。默认情况下，HSTS 处于禁用状态。

另请参阅 setStrictTransportSecurityEnabled()。

bool QNetworkAccessManager::isStrictTransportSecurityStoreEnabled() const

如果 HSTS 缓存使用永久存储来加载和存储 HSTS 策略，则返回 true。

另请参阅 enableStrictTransportSecurityStore()。

QNetworkReply *QNetworkAccessManager::post(const QNetworkRequest &request, QIODevice *data)

向由request 指定的目标发送一个HTTP POST请求，并返回一个已打开且处于读取状态的新QNetworkReply 对象，该对象将包含服务器发送的响应。data 设备中的内容将上传至服务器。

data 该对象必须处于读取模式，并且必须保持有效，直到为此响应发出finished() 信号为止。

另请参阅 get()、put()、deleteResource() 和sendCustomRequest()。

QNetworkReply *QNetworkAccessManager::post(const QNetworkRequest &request, QHttpMultiPart *multiPart)

将multiPart 消息的内容发送至request 指定的目标地址。

这可用于通过 HTTP 发送 MIME 多部分消息。

另请参阅 QHttpMultiPart 、QHttpPart 和put()。

QNetworkReply *QNetworkAccessManager::post(const QNetworkRequest &request, const QByteArray &data)

将字节数组data 的内容发送到由request 指定的目标位置。

[since 6.8] QNetworkReply *QNetworkAccessManager::post(const QNetworkRequest &request, std::nullptr_t nptr)

发送由 `request ` 指定的 POST 请求（不带请求体），并返回一个新的 `QNetworkReply ` 对象。

该函数于 Qt 6.8 中引入。

[signal] void QNetworkAccessManager::preSharedKeyAuthenticationRequired(QNetworkReply *reply, QSslPreSharedKeyAuthenticator *authenticator)

如果 SSL/TLS 握手协商出一个 PSK 密码套件，则会发出此信号，因此随后需要进行 PSK 身份验证。reply 对象即为正在协商此类密码套件的QNetworkReply 。

使用 PSK 时，客户端必须向服务器发送有效的身份信息和有效的预共享密钥，以便 SSL 握手继续进行。应用程序可以通过连接到此信号的插槽提供这些信息，根据需要填充传入的authenticator 对象。

另请参阅 QSslPreSharedKeyAuthenticator 。

QNetworkProxy QNetworkAccessManager::proxy() const

返回使用此QNetworkAccessManager 对象发送的请求将使用的QNetworkProxy 。代理的默认值为QNetworkProxy::DefaultProxy 。

另请参阅 setProxy()、setProxyFactory() 和proxyAuthenticationRequired()。

[signal] void QNetworkAccessManager::proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)

每当代理请求身份验证，而QNetworkAccessManager 无法找到有效的缓存凭据时，都会发出此信号。连接到此信号的槽应将代理proxy 的凭据填入authenticator 对象中。

QNetworkAccessManager 将内部缓存这些凭据。下次代理请求身份验证时，QNetworkAccessManager 将自动发送相同的凭据，而不会再次发出 proxyAuthenticationRequired 信号。

如果代理拒绝这些凭据，QNetworkAccessManager 将再次发出该信号。

另请参阅 proxy()、setProxy() 和authenticationRequired()。

QNetworkProxyFactory *QNetworkAccessManager::proxyFactory() const

返回该QNetworkAccessManager 对象用于确定请求所用代理的代理生成器。

请注意，此函数返回的指针由QNetworkAccessManager 管理，并可能随时被删除。

另请参阅 setProxyFactory() 和proxy()。

QNetworkReply *QNetworkAccessManager::put(const QNetworkRequest &request, QIODevice *data)

将data 的内容上传至目标request ，并返回一个新的QNetworkReply 对象，该对象将保持打开状态以接收回复。

data 调用此函数时，该文件必须处于读取打开状态，并且必须保持有效，直到为此响应发出finished() 信号为止。

返回的对象中是否有内容可供读取取决于协议。对于 HTTP，服务器可能会发送一个简短的 HTML 页面，表明上传成功（或未成功）。其他协议的响应中通常会包含内容。

另请参阅 get()、post()、deleteResource() 以及sendCustomRequest()。

QNetworkReply *QNetworkAccessManager::put(const QNetworkRequest &request, QHttpMultiPart *multiPart)

将multiPart 消息的内容发送到由request 指定的目标。

这可用于通过 HTTP 发送 MIME 多部分消息。

另请参阅 QHttpMultiPart 、QHttpPart 和post()。

QNetworkReply *QNetworkAccessManager::put(const QNetworkRequest &request, const QByteArray &data)

将字节数组 `data ` 的内容发送到由 `request` 指定的目标。

[since 6.8] QNetworkReply *QNetworkAccessManager::put(const QNetworkRequest &request, std::nullptr_t nptr)

发送由 `request ` 指定的 PUT 请求（不包含请求体），并返回一个新的 `QNetworkReply ` 对象。

该函数在 Qt 6.8 中引入。

QNetworkRequest::RedirectPolicy QNetworkAccessManager::redirectPolicy() const

返回在创建新请求时使用的重定向策略。

另请参阅 setRedirectPolicy() 和QNetworkRequest::RedirectPolicy 。

QNetworkReply *QNetworkAccessManager::sendCustomRequest(const QNetworkRequest &request, const QByteArray &verb, QIODevice *data = nullptr)

向由 URLrequest 标识的服务器发送自定义请求。

用户有责任向服务器发送一个符合 HTTP 规范的verb 请求。

此方法提供了发送除get() 或post() 等提供的常用动词以外的其他动词的手段，例如发送 HTTP OPTIONS 命令。

如果 `data ` 不为空，则 `data ` 设备中的内容将上传到服务器；在这种情况下，数据必须处于可读状态，并且必须保持有效，直到为此响应发出 `finished()` 信号为止。

另请参阅 get()、post()、put() 和deleteResource()。

QNetworkReply *QNetworkAccessManager::sendCustomRequest(const QNetworkRequest &request, const QByteArray &verb, QHttpMultiPart *multiPart)

向由 URLrequest 标识的服务器发送自定义请求。

将multiPart 消息的内容发送至request 指定的目标。

这可用于为自定义动词发送 MIME 多部分消息。

另请参阅 QHttpMultiPart 、QHttpPart 和put()。

QNetworkReply *QNetworkAccessManager::sendCustomRequest(const QNetworkRequest &request, const QByteArray &verb, const QByteArray &data)

将字节数组data 的内容发送到由request 指定的目标位置。

void QNetworkAccessManager::setAutoDeleteReplies(bool shouldAutoDelete)

启用或禁用QNetworkReplies 的自动删除功能。

将shouldAutoDelete 设置为true，相当于将所有今后传递给此QNetworkAccessManager 实例的QNetworkRequests 的QNetworkRequest::AutoDeleteReplyOnFinishAttribute 属性设置为true，除非该属性已在QNetworkRequest 上被显式设置。

另请参阅 autoDeleteReplies 和QNetworkRequest::AutoDeleteReplyOnFinishAttribute 。

void QNetworkAccessManager::setCache(QAbstractNetworkCache *cache)

将管理器的网络缓存设置为指定的cache 。该缓存用于处理管理器分发的所有请求。

使用此函数可将网络缓存对象设置为实现额外功能的类，例如将 Cookie 保存到永久存储中。

QNetworkAccessManager 默认情况下，该管理器未设置缓存。Qt 提供了一个简单的磁盘缓存 `QNetworkDiskCache`，可供使用。

另请参阅 cache() 和QNetworkRequest::CacheLoadControl 。

void QNetworkAccessManager::setCookieJar(QNetworkCookieJar *cookieJar)

将管理器的 Cookie 存储器设置为指定的 `cookieJar `。该 Cookie 存储器将用于管理器分发的所有请求。

使用此函数可将 Cookie Jar 对象设置为实现额外功能的类，例如将 Cookie 保存到永久存储中。

如果cookieJar 与该QNetworkAccessManager 位于同一线程中，它将设置cookieJar 的父对象，以便在删除该对象时一并删除 Cookie Jar。如果您希望在不同的QNetworkAccessManager 对象之间共享 Cookie Jar，建议在调用此函数后将 Cookie Jar 的父对象设置为 0。

QNetworkAccessManager 默认情况下，该对象不实现任何自身的 Cookie 策略：只要 Cookie 格式正确且满足最低安全要求（Cookie 域与请求的域匹配，Cookie 路径与请求的路径匹配），它就会接受服务器发送的所有 Cookie。若要实现您自己的安全策略，请重写QNetworkCookieJar::cookiesForUrl() 和QNetworkCookieJar::setCookiesFromUrl() 这两个虚函数。 当QNetworkAccessManager 检测到新的 Cookie 时，会调用这些函数。

另请参阅 cookieJar()、QNetworkCookieJar::cookiesForUrl() 和QNetworkCookieJar::setCookiesFromUrl()。

void QNetworkAccessManager::setProxy(const QNetworkProxy &proxy)

将未来请求中使用的代理设置为proxy 。这不会影响已经发送的请求。如果代理要求身份验证，将触发proxyAuthenticationRequired() 信号。

通过此函数设置的代理将用于QNetworkAccessManager 发出的所有请求。在某些情况下，可能需要根据发送的请求类型或目标主机来选择不同的代理。如果遇到这种情况，应考虑使用setProxyFactory() 函数。

另请参阅 proxy() 和proxyAuthenticationRequired()。

void QNetworkAccessManager::setProxyFactory(QNetworkProxyFactory *factory)

将此类设置为使用代理工厂factory 。代理工厂用于确定针对给定请求应使用的更具体的代理列表，而不是尝试对所有请求都使用相同的代理值。

由QNetworkAccessManager 发送的所有查询都将具有类型QNetworkProxyQuery::UrlRequest 。

例如，一个代理工厂可以应用以下规则：

• 如果目标地址位于本地网络内（例如，主机名中不包含点，或者该IP地址属于组织的IP范围），则返回QNetworkProxy::NoProxy
• 如果请求是 FTP，则返回一个 FTP 代理
• 如果请求是 HTTP 或 HTTPS，则返回一个 HTTP 代理
• 否则，返回一个 SOCKSv5 代理服务器

对象 `factory ` 的生命周期将由 `QNetworkAccessManager` 管理。该方法将在必要时删除该对象。

另请参阅 proxyFactory()、setProxy() 和QNetworkProxyQuery 。

void QNetworkAccessManager::setRedirectPolicy(QNetworkRequest::RedirectPolicy policy)

将管理器的重定向策略设置为指定的policy 。该策略将影响管理器后续生成的所有请求。

使用此函数可在管理器级别启用或禁用 HTTP 重定向。

默认值为QNetworkRequest::NoLessSafeRedirectPolicy 。建议依赖手动重定向处理的客户端在代码中显式设置此策略。

另请参阅 redirectPolicy() 和QNetworkRequest::RedirectPolicy 。

void QNetworkAccessManager::setStrictTransportSecurityEnabled(bool enabled)

如果enabled 的值设置为true ，则QNetworkAccessManager 将遵循 HTTP 严格传输安全策略（HSTS，RFC6797）。在处理请求时，QNetworkAccessManager 会自动将“http”方案替换为“https”，并针对 HSTS 主机使用安全传输协议。如果该值被显式设置，则端口 80 将被替换为端口 443。

启用 HSTS 后，对于每个包含 HSTS 标头且通过安全传输接收的 HTTP 响应，QNetworkAccessManager 都会更新其 HSTS 缓存：要么将具有有效策略的主机添加到缓存中，要么将 HSTS 策略已过期或已禁用的主机从缓存中移除。

另请参阅 isStrictTransportSecurityEnabled()。

void QNetworkAccessManager::setTransferTimeout(int timeout)

将timeout 设置为传输超时时间（单位为毫秒）。

另请参阅 setTransferTimeout(std::chrono::milliseconds)、transferTimeout() 和transferTimeoutAsDuration()。

[since 6.7] void QNetworkAccessManager::setTransferTimeout(std::chrono::milliseconds duration = QNetworkRequest::DefaultTransferTimeout)

设置超时时间duration ，若未交换任何数据则中止传输。

如果在超时到期前未传输任何字节，则传输将被中止。零表示未设置计时器。如果未提供参数，超时时间为QNetworkRequest::DefaultTransferTimeout 。如果未调用此函数，则超时功能被禁用，且值为零。 针对已执行请求设置的、不为零的特定请求超时将覆盖此值。这意味着，如果 `QNetworkAccessManager ` 启用了超时，则需要将其禁用才能执行无超时的请求。

该函数于 Qt 6.7 中引入。

另请参阅 transferTimeoutAsDuration()。

[signal] void QNetworkAccessManager::sslErrors(QNetworkReply *reply, const QList<QSslError> &errors)

如果 SSL/TLS 会话在建立过程中遇到错误（包括证书验证错误），则会发出此信号。errors 参数包含错误列表，而reply 则是遇到这些错误的QNetworkReply 。

若需表明这些错误并非致命且连接应继续进行，则应从连接到此信号的槽中调用QNetworkReply::ignoreSslErrors() 函数。若未调用该函数，SSL 会话将在交换任何数据（包括 URL）之前被终止。

该信号可用于向用户显示错误消息，提示安全性可能受到威胁，并显示 SSL 设置（参见 sslConfiguration() 获取该设置）。如果用户在分析远程证书后决定继续操作，该槽应调用 ignoreSslErrors()。

另请参阅 QSslSocket::sslErrors()、QNetworkReply::sslErrors()、QNetworkReply::sslConfiguration() 以及QNetworkReply::ignoreSslErrors()。

QList<QHstsPolicy> QNetworkAccessManager::strictTransportSecurityHosts() const

返回 HTTP 严格传输安全 (HSTS) 策略的列表。如果 HSTS 缓存是通过“Strict-Transport-Security”响应头更新的，则该列表可能与最初通过addStrictTransportSecurityHosts() 设置的内容不同。

另请参阅 addStrictTransportSecurityHosts() 和QHstsPolicy 。

[virtual] QStringList QNetworkAccessManager::supportedSchemes() const

列出了访问管理器支持的所有 URL 方案。

请在QNetworkAccessManager 的子类中重写此方法，以提供您自己支持的方案。例如，当您的子类支持新协议时，就需要这样做。

int QNetworkAccessManager::transferTimeout() const

返回传输所用的超时时间，单位为毫秒。

另请参阅 setTransferTimeout()。

[since 6.7] std::chrono::milliseconds QNetworkAccessManager::transferTimeoutAsDuration() const

返回超时时长，如果在此期间未交换任何数据，则传输将被中止。

默认时长为零，这意味着不会使用超时机制。

该函数在 Qt 6.7 中引入。

另请参阅 setTransferTimeout(std::chrono::milliseconds)。