QNetworkReply Class

成员函数文档

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

创建一个父类为parent 的QNetworkReply对象。

无法直接实例化 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() 获取的总字节数，或 header(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() 信号的槽中调用，该信号会指示发现了哪些错误。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        networkReply, qOverload<>(&QNetworkReply::ignoreSslErrors));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        networkReply, [receiver = networkReply]() { receiver->ignoreSslErrors(); });

另请参阅 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()。

[override virtual] bool QNetworkReply::isSequential() const

重新实现了：QIODevice::isSequential() const。

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

当请求被发送时，该信号会被触发一次或多次。这对于自定义进度条或超时处理非常有用。

该函数在 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()、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()。

[override virtual protected] qint64 QNetworkReply::writeData(const char *data, qint64 len)

重新实现了：QIODevice::writeData （const char *data, qint64 maxSize）。