QNetworkReply Class

成员函数文档

[explicit protected] QNetworkReply::QNetworkReply(QObject *parent = nullptr)

创建一个 QNetworkReply 对象，其父级parent 。

您不能直接实例化 QNetworkReply 对象。请使用QNetworkAccessManager 函数来实现。

[virtual noexcept] QNetworkReply::~QNetworkReply()

处理该回复并释放与之相关的任何资源。如果任何网络连接仍处于打开状态，它们将被关闭。

另请参阅 abort() 和close()。

[pure virtual slot] void QNetworkReply::abort()

立即终止操作并关闭所有仍打开的网络连接。仍在进行中的上传也会中止。

同时还会发出finished() 信号。

另请参阅 close() 和finished()。

QVariant QNetworkReply::attribute(QNetworkRequest::Attribute code) const

返回与代码code 相关的属性。如果属性未设置，则返回无效的QVariant （类型：QMetaType::UnknownType ）。

QNetworkRequest::Attribute 中列出的默认值将应用于该函数返回的值。

另请参阅 setAttribute() 和QNetworkRequest::Attribute 。

[override virtual] void QNetworkReply::close()

重新实现：QIODevice::close().

关闭该设备的读取。未读数据会被丢弃，但网络资源不会丢弃，直到读完为止。特别是，如果正在进行上传，则会继续进行，直到完成为止。

当所有操作结束并释放网络资源时，将发出finished() 信号。

另请参阅 abort() 和finished()。

[signal] void QNetworkReply::downloadProgress(qint64 bytesReceived, qint64 bytesTotal)

如果有下载，该信号将用于指示网络请求中下载部分的进度。如果该请求没有下载相关内容，则会发出一次该信号，bytesReceived 和bytesTotal 的值均为 0。

bytesReceived 参数表示收到的字节数，而bytesTotal 表示预计下载的总字节数。如果不知道要下载的字节数，bytesTotal 将为-1。

当bytesReceived 等于bytesTotal 时，下载完成。此时，bytesTotal 将不会为-1。

请注意，bytesReceived 和bytesTotal 的值可能不同于size()、通过read() 或readAll() 获得的总字节数或标头（ContentLengthHeader）的值。原因可能是协议开销或数据在下载过程中被压缩。

另请参阅 uploadProgress() 和bytesAvailable()。

[signal] void QNetworkReply::encrypted()

当 SSL/TLS 会话成功完成初始握手时，就会发出该信号。此时，用户数据尚未传输。该信号可用于对证书链执行额外检查，例如在网站证书发生变化时通知用户。如果应答不符合预期标准，则应通过与该信号相连的插槽调用QNetworkReply::abort() 中止应答。使用QNetworkReply::sslConfiguration() 方法可以检查正在使用的 SSL 配置。

在内部，QNetworkAccessManager 可以打开多个服务器连接，以便并行处理请求。这些连接可能会被重复使用，这意味着不会发出 encrypted() 信号。这就意味着，只有在QNetworkAccessManager 的生命周期内首次连接到某个站点时，才能保证收到该信号。

另请参见 QSslSocket::encrypted() 和QNetworkAccessManager::encrypted()。

QNetworkReply::NetworkError QNetworkReply::error() const

返回处理该请求时发现的错误。如果没有发现错误，则返回NoError 。

另请参阅 setError() 。

[signal] void QNetworkReply::errorOccurred(QNetworkReply::NetworkError code)

当应答检测到处理过程中出现错误时，就会发出该信号。随后可能会发出finished() 信号，表示连接结束。

code 参数包含检测到的错误代码。调用errorString() 可获得错误条件的文本表示。

另请参阅 error() 和errorString()。

[signal] void QNetworkReply::finished()

该信号在回复处理完毕时发出。此信号发出后，将不再更新回复的数据或元数据。

除非调用了close() 或abort()，否则回复仍将开放供读取，因此可以通过调用read() 或readAll() 来检索数据。特别是，如果在调用readyRead() 后没有调用read() ，则调用readAll() 将在QByteArray 中获取全部内容。

该信号与QNetworkAccessManager::finished() 同时发出，其中该信号的回复参数就是该对象。

您也可以使用isFinished() 来检查QNetworkReply 是否已在收到 finished() 信号之前完成。

另请参阅 setFinished()、QNetworkAccessManager::finished() 和isFinished()。

bool QNetworkReply::hasRawHeader(QAnyStringView headerName) const

如果远程服务器发送了名称为headerName 的原始标头，则返回true

另请参阅 rawHeader().

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

如果远程服务器发送了已知标头header ，则返回该标头的值。如果未发送头，则返回无效的QVariant 。

另请参阅 rawHeader()、setHeader() 和QNetworkRequest::header()。

[since 6.8] QHttpHeaders QNetworkReply::headers() const

返回远程服务器发送的头信息。

此函数在 Qt 6.8 中引入。

另请参阅 setHeaders(),QNetworkRequest::setAttribute() 和QNetworkRequest::Attribute 。

[virtual slot] void QNetworkReply::ignoreSslErrors()

如果调用此函数，与网络连接相关的 SSL 错误（包括证书验证错误）将被忽略。

可以从连接到sslErrors() 信号的槽中调用此函数，该信号会显示发现了哪些错误。

另请参阅 sslConfiguration(),sslErrors() 和QSslSocket::ignoreSslErrors()。

void QNetworkReply::ignoreSslErrors(const QList<QSslError> &errors)

这是一个重载函数。

如果调用该函数，errors 中的 SSL 错误将被忽略。

QList<QSslCertificate> cert = QSslCertificate::fromPath("server-certificate.pem"_L1);
QSslError error(QSslError::SelfSignedCertificate, cert.at(0));
QList<QSslError> expectedSslErrors;
expectedSslErrors.append(error);

QNetworkReply *reply = manager.get(QNetworkRequest(QUrl("https://server.tld/index.html")));
reply->ignoreSslErrors(expectedSslErrors);
// here connect signals etc.

多次调用此函数将替换之前调用时传递的错误列表。您可以使用空列表调用此函数，清除要忽略的错误列表。

另请参阅 sslConfiguration()、sslErrors()、QSslSocket::ignoreSslErrors() 和QNetworkAccessManager::setStrictTransportSecurityEnabled()。

[virtual protected] void QNetworkReply::ignoreSslErrorsImplementation(const QList<QSslError> &errors)

提供此虚拟方法是为了覆盖ignoreSslErrors() 的行为。ignoreSslErrors(errors 包含用户希望忽略的错误。

另请参阅 ignoreSslErrors()。

bool QNetworkReply::isFinished() const

当回复结束或被中止时，返回true 。

另请参阅 isRunning().

bool QNetworkReply::isRunning() const

如果请求仍在处理中，而回复尚未完成或已中止，则返回true 。

另请参阅 isFinished()。

QNetworkAccessManager *QNetworkReply::manager() const

返回用于创建QNetworkReply 对象的QNetworkAccessManager 。最初，它也是父对象。

[signal] void QNetworkReply::metaDataChanged()

元数据是指任何不属于内容（数据）本身的信息，包括网络报头。在大多数情况下，元数据在接收到第一个字节的数据时就已完全知晓。不过，在处理数据的过程中，也有可能收到更新的标头或其他元数据。

另请参见 header()、rawHeaderList()、rawHeader() 和hasRawHeader()。

QNetworkAccessManager::Operation QNetworkReply::operation() const

返回为该回复发布的操作。

另请参阅 setOperation()。

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

如果 SSL/TLS 握手协商使用 PSK 密码套件，并因此需要 PSK 身份验证，则会发出该信号。

使用 PSK 时，客户端必须向服务器发送有效的身份信息和有效的预共享密钥，才能继续 SSL 握手。应用程序可以根据自己的需要，通过填写传递的authenticator 对象，在与该信号相连的插槽中提供这些信息。

另请参阅 QSslPreSharedKeyAuthenticator 。

QByteArray QNetworkReply::rawHeader(QAnyStringView headerName) const

返回远程服务器发送的headerName 头信息的原始内容。如果没有此类头信息，则返回一个空字节数组，该数组可能与空头信息无异。请使用hasRawHeader() 验证服务器是否发送了此类头信息。

另请参阅 setRawHeader()、hasRawHeader() 和header()。

QList<QByteArray> QNetworkReply::rawHeaderList() const

按发送顺序返回远程服务器发送的标头字段列表。重复的标头会合并在一起，取代后一个重复的标头。

const QList<QNetworkReply::RawHeaderPair> &QNetworkReply::rawHeaderPairs() const

返回原始标头对列表。

qint64 QNetworkReply::readBufferSize() const

返回读取缓冲区的大小（字节）。

另请参阅 setReadBufferSize().

[signal] void QNetworkReply::redirectAllowed()

当处理redirected() 信号的客户端代码验证了新的 URL 后，就会发出该信号以允许继续重定向。此协议适用于重定向策略设置为QNetworkRequest::UserVerifiedRedirectPolicy

另请参阅 QNetworkRequest::UserVerifiedRedirectPolicy 、QNetworkAccessManager::setRedirectPolicy() 和QNetworkRequest::RedirectPolicyAttribute 。

[signal] void QNetworkReply::redirected(const QUrl &url)

如果请求中未设置QNetworkRequest::ManualRedirectPolicy ，且服务器以 3xx 状态（特别是 301、302、303、305、307 或 308 状态代码）响应，并在 location 头信息中提供了一个有效的 url，表明发生了 HTTP 重定向，则会发出该信号。url 参数包含服务器在 location 头中返回的新重定向 url。

另请参阅 QNetworkRequest::RedirectPolicy 。

QNetworkRequest QNetworkReply::request() const

返回为该回复发布的请求。需要特别注意的是，请求的 URL 可能与回复的 URL 不同。

另请参阅 QNetworkRequest::url()、url() 和setRequest()。

[signal, since 6.3] void QNetworkReply::requestSent()

发送请求时，该信号会发出 1 次或多次。对于自定义进度或超时处理非常有用。

此函数在 Qt 6.3 中引入。

另请参阅 metaDataChanged() 和socketStartedConnecting()。

[protected] void QNetworkReply::setAttribute(QNetworkRequest::Attribute code, const QVariant &value)

将属性code 设置为value 。如果code 之前已设置，则会被覆盖。如果value 是一个无效的QVariant ，该属性将被取消设置。

另请参阅 attribute() 和QNetworkRequest::setAttribute()。

[protected] void QNetworkReply::setError(QNetworkReply::NetworkError errorCode, const QString &errorString)

将错误条件设置为errorCode 。人可读信息用errorString 设置。

调用 setError() 不会发出errorOccurred(QNetworkReply::NetworkError) 信号。

另请参阅 error() 和errorString()。

[protected] void QNetworkReply::setFinished(bool finished)

将回复设置为finished 。

设置后，回复数据不得更改。

另请参阅 finished() 和isFinished()。

[protected] void QNetworkReply::setHeader(QNetworkRequest::KnownHeaders header, const QVariant &value)

将已知标头header 设置为value 。同时还将设置头的相应原始形式。

另请参阅 header()、setRawHeader() 和QNetworkRequest::setHeader()。

[protected, since 6.8] void QNetworkReply::setHeaders(const QHttpHeaders &newHeaders)

将newHeaders 设置为网络回复中的标头，覆盖之前设置的任何标头。

如果某些标头与已知标头相对应，它们将被解析，相应的解析形式也将被设置。

此函数在 Qt 6.8 中引入。

另请参阅 headers() 和QNetworkRequest::KnownHeaders 。

[protected, since 6.8] void QNetworkReply::setHeaders(QHttpHeaders &&newHeaders)

这是一个重载函数。

该函数在 Qt 6.8 中引入。

[protected] void QNetworkReply::setOperation(QNetworkAccessManager::Operation operation)

将此对象的相关操作设置为operation 。operation() 将返回此值。

另请参阅 operation() 和setRequest()。

[protected] void QNetworkReply::setRawHeader(const QByteArray &headerName, const QByteArray &value)

将原始标头headerName 设置为value 。如果之前设置了headerName ，则会被覆盖。多个同名 HTTP 头信息在功能上等同于一个单独的头信息，头信息的值由逗号分隔。

如果headerName 与已知的头匹配，则将解析value 的值，并设置相应的解析形式。

另请参阅 rawHeader()、header()、setHeader() 和QNetworkRequest::setRawHeader()。

[virtual] void QNetworkReply::setReadBufferSize(qint64 size)

将读取缓冲区的大小设置为size 字节。在使用QIODevice::read() 读取数据之前，读取缓冲区将保存从网络下载的数据。将缓冲区大小设为 0 将使缓冲区的大小不受限制。

QNetworkReply 一旦缓冲区已满（即 () 返回 或更多），系统将尝试停止从网络读取数据，从而导致下载速度减慢。如果缓冲区的大小没有限制， 将尽可能快地从网络下载。bytesAvailable size QNetworkReply

与QAbstractSocket::setReadBufferSize() 不同，QNetworkReply 无法保证读取缓冲区大小的精确性。也就是说，bytesAvailable() 的返回值可能会超过size 。

另请参阅 readBufferSize()。

[protected] void QNetworkReply::setRequest(const QNetworkRequest &request)

将此对象的相关请求设置为request 。该值将由request() 返回。

另请参阅 request() 和setOperation()。

void QNetworkReply::setSslConfiguration(const QSslConfiguration &config)

如果可能，将与此请求相关的网络连接的 SSL 配置设置为config 的配置。

另请参阅 sslConfiguration() 。

[virtual protected] void QNetworkReply::setSslConfigurationImplementation(const QSslConfiguration &configuration)

提供此虚拟方法是为了重写setSslConfiguration() 的行为。setSslConfiguration() 是该方法的公共包装器。如果覆盖此方法，请使用configuration 设置 SSL 配置。

另请参阅 sslConfigurationImplementation() 和setSslConfiguration()。

[protected] void QNetworkReply::setUrl(const QUrl &url)

将正在处理的 URL 设置为url 。通常情况下，URL 会与已发布请求的 URL 一致，但由于各种原因，URL 也可能不同（例如，文件路径被设为绝对路径或规范路径）。

另请参阅 url()、request() 和QNetworkRequest::url()。

[protected, since 6.8] void QNetworkReply::setWellKnownHeader(QHttpHeaders::WellKnownHeader name, QByteArrayView value)

将name 设置为value 的值。如果name 之前已设置，则会被覆盖。

此函数在 Qt 6.8 中引入。

[signal, since 6.3] void QNetworkReply::socketStartedConnecting()

当套接字正在连接时，该信号会在发送请求前发出 0 次或更多次。对于自定义进度或超时处理非常有用。

此函数在 Qt 6.3 中引入。

另请参阅 metaDataChanged() 和requestSent()。

QSslConfiguration QNetworkReply::sslConfiguration() const

如果使用了 SSL，则返回与此回复相关的 SSL 配置和状态。它将包含远程服务器的证书、指向证书颁发机构的证书链以及正在使用的加密密码。

如果发送了sslErrors() ，那么在发送时就会知道对等方的证书及其证书链。

另请参阅 setSslConfiguration()。

[virtual protected] void QNetworkReply::sslConfigurationImplementation(QSslConfiguration &configuration) const

提供此虚拟方法是为了重写sslConfiguration() 的行为。sslConfiguration() 是该方法的公共包装器。配置将在configuration 中返回。

另请参阅 setSslConfigurationImplementation() 和sslConfiguration()。

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

如果 SSL/TLS 会话在设置过程中遇到错误（包括证书验证错误），就会发出该信号。errors 参数包含错误列表。

为表明错误不是致命的，连接应继续进行，应从连接到此信号的槽中调用ignoreSslErrors() 函数。如果不调用该函数，SSL 会话将在交换任何数据（包括 URL）之前被终止。

该信号可用于向用户显示错误信息，说明安全性可能受到影响，并显示 SSL 设置（请参阅sslConfiguration() 获取）。如果用户在分析远程证书后决定继续，槽应调用ignoreSslErrors() 。

另请参阅 QSslSocket::sslErrors()、QNetworkAccessManager::sslErrors()、sslConfiguration() 和ignoreSslErrors()。

[signal] void QNetworkReply::uploadProgress(qint64 bytesSent, qint64 bytesTotal)

如果网络请求中存在上传部分，则该信号用于指示上传部分的进度。如果该请求没有上传，则不会发出该信号。

bytesSent 参数表示已上传的字节数，而bytesTotal 表示待上传的总字节数。如果无法确定要上传的字节数，bytesTotal 将为-1。

当bytesSent 等于bytesTotal 时，上传结束。此时，bytesTotal 不会为-1。

另请参阅 downloadProgress() 。

QUrl QNetworkReply::url() const

返回下载或上传内容的 URL。请注意，该 URL 可能与原始请求的 URL 不同。如果在请求中启用了重定向，则此函数将返回网络 API 访问的当前 URL，即请求被重定向到的资源的 URL。

另请参见 request()、setUrl()、QNetworkRequest::url() 和redirected()。