QNetworkReply 类

The QNetworkReply class contains the data and headers for a request sent with QNetworkAccessManager 更多...

头: #include <QNetworkReply>
Since: Qt 4.4
继承: QIODevice

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

公共类型

enum NetworkError { NoError, ConnectionRefusedError, RemoteHostClosedError, HostNotFoundError, ..., ProtocolFailure }
typedef RawHeaderPair

公共函数

~QNetworkReply ()
virtual void abort () = 0
QVariant 属性 (QNetworkRequest::Attribute code ) const
NetworkError error () const
bool hasRawHeader (const QByteArray & headerName ) const
QVariant header (QNetworkRequest::KnownHeaders header ) const
void ignoreSslErrors (const QList<QSslError> & errors )
bool isFinished () const
bool isRunning () const
QNetworkAccessManager * manager () const
QNetworkAccessManager::Operation operation () const
QByteArray rawHeader (const QByteArray & headerName ) const
QList<QByteArray> rawHeaderList () const
const QList<RawHeaderPair> & rawHeaderPairs () const
qint64 readBufferSize () const
QNetworkRequest request () const
virtual void setReadBufferSize (qint64 size )
void setSslConfiguration (const QSslConfiguration & config )
QSslConfiguration sslConfiguration () const
QUrl url () const

重实现公共函数

virtual void close ()

公共槽

virtual void ignoreSslErrors ()

信号

void downloadProgress (qint64 bytesReceived , qint64 bytesTotal )
void error (QNetworkReply::NetworkError code )
void finished ()
void metaDataChanged ()
void sslErrors (const QList<QSslError> & errors )
void uploadProgress (qint64 bytesSent , qint64 bytesTotal )

保护函数

QNetworkReply (QObject * parent = 0)
void setAttribute (QNetworkRequest::Attribute code , const QVariant & value )
void setError (NetworkError errorCode , const QString & errorString )
void setFinished (bool finished )
void setHeader (QNetworkRequest::KnownHeaders header , const QVariant & value )
void setOperation (QNetworkAccessManager::Operation operation )
void setRawHeader (const QByteArray & headerName , const QByteArray & value )
void setRequest (const QNetworkRequest & request )
void setUrl (const QUrl & url )

额外继承成员

详细描述

The QNetworkReply class contains the data and headers for a request sent with QNetworkAccessManager

The QNetworkReply class contains the data and meta data related to a request posted with QNetworkAccessManager 。像 QNetworkRequest ,它包含 URL 和 Header (两者的剖析和原生表单),有关回复状态的一些信息及回复本身的内容。

QNetworkReply is a sequential-access QIODevice ,意味着一旦从对象读取数据,数据就不再由设备所保持。因此,应用程序有责任保持此数据,若需要的话。每当从网络接收和处理更多数据时, readyRead () 信号发射。

The downloadProgress () 信号也被发射当接收数据时,但其中包含的字节数可能不表示实际接收字节数,若有对内容做任何变换 (例如:解压缩和移除协议开销)。

Even though QNetworkReply QIODevice 连接到回复内容,它还发射 uploadProgress () 信号,指示有这种内容操作的上传进度。

注意: 不要在槽中删除对象,其已连接到 error () 或 finished () 信号。请使用 deleteLater ().

另请参阅 QNetworkRequest and QNetworkAccessManager .

成员类型文档编制

enum QNetworkReply:: NetworkError

指示在处理请求期间,发现的所有可能的错误条件。

常量 描述
QNetworkReply::NoError 0 没有错误条件。

注意: 当 HTTP 协议返回重定向时,不会报告错误。可以校验是否有重定向采用 QNetworkRequest::RedirectionTargetAttribute 属性。

常量 描述
QNetworkReply::ConnectionRefusedError 1 the remote server refused the connection (the server is not accepting requests)
QNetworkReply::RemoteHostClosedError 2 the remote server closed the connection prematurely, before the entire reply was received and processed
QNetworkReply::HostNotFoundError 3 the remote host name was not found (invalid hostname)
QNetworkReply::TimeoutError 4 the connection to the remote server timed out
QNetworkReply::OperationCanceledError 5 操作被取消经由调用 abort () 或 close () 在它完成之前。
QNetworkReply::SslHandshakeFailedError 6 the SSL/TLS handshake failed and the encrypted channel could not be established. The sslErrors () signal should have been emitted.
QNetworkReply::TemporaryNetworkFailureError 7 the connection was broken due to disconnection from the network, however the system has initiated roaming to another access point. The request should be resubmitted and will be processed as soon as the connection is re-established.
QNetworkReply::ProxyConnectionRefusedError 101 the connection to the proxy server was refused (the proxy server is not accepting requests)
QNetworkReply::ProxyConnectionClosedError 102 the proxy server closed the connection prematurely, before the entire reply was received and processed
QNetworkReply::ProxyNotFoundError 103 the proxy host name was not found (invalid proxy hostname)
QNetworkReply::ProxyTimeoutError 104 the connection to the proxy timed out or the proxy did not reply in time to the request sent
QNetworkReply::ProxyAuthenticationRequiredError 105 the proxy requires authentication in order to honour the request but did not accept any credentials offered (if any)
QNetworkReply::ContentAccessDenied 201 the access to the remote content was denied (similar to HTTP error 401)
QNetworkReply::ContentOperationNotPermittedError 202 the operation requested on the remote content is not permitted
QNetworkReply::ContentNotFoundError 203 the remote content was not found at the server (similar to HTTP error 404)
QNetworkReply::AuthenticationRequiredError 204 the remote server requires authentication to serve the content but the credentials provided were not accepted (if any)
QNetworkReply::ContentReSendError 205 the request needed to be sent again, but this failed for example because the upload data could not be read a second time.
QNetworkReply::ProtocolUnknownError 301 the Network Access API cannot honor the request because the protocol is not known
QNetworkReply::ProtocolInvalidOperationError 302 请求的操作对此协议无效
QNetworkReply::UnknownNetworkError 99 an unknown network-related error was detected
QNetworkReply::UnknownProxyError 199 an unknown proxy-related error was detected
QNetworkReply::UnknownContentError 299 an unknown error related to the remote content was detected
QNetworkReply::ProtocolFailure 399 a breakdown in protocol was detected (parsing error, invalid or unexpected responses, etc.)

另请参阅 error ().

typedef QNetworkReply:: RawHeaderPair

RawHeaderPair 是 QPair < QByteArray , QByteArray > 其中第一个 QByteArray 是 Header (头) 名,而第 2 个是头。

成员函数文档编制

[protected] QNetworkReply:: QNetworkReply ( QObject * parent = 0)

创建 QNetworkReply object with parent parent .

You cannot directly instantiate QNetworkReply objects. Use QNetworkAccessManager 函数以做到这点。

QNetworkReply:: ~QNetworkReply ()

处置此回复并释放与其关联的任何资源。若任何网络连接仍处于打开状态,它们将被关闭。

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

[pure virtual] void QNetworkReply:: abort ()

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

另请参阅 close ().

QVariant QNetworkReply:: 属性 ( QNetworkRequest::Attribute code ) const

返回属性关联代码 code 。若尚未设置属性,则返回无效 QVariant (type QVariant::Null).

可以期望的默认值列表于 QNetworkRequest::Attribute 以应用由此函数返回的值。

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

[虚拟] void QNetworkReply:: close ()

重实现自 QIODevice::close ().

关闭用于读取的此设备。未读取数据会被丢弃,但网络资源不会被丢弃直到它们完成为止。尤其,若正在进行任何上传,它将继续直到完成为止。

The finished () 信号被发射,当所有操作结束,且网络资源已释放。

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

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

此信号被发射,以指示此网络请求的下载部分的进度 (若有的话)。若没有与此请求关联的下载,此信号将发射 0 值一次对于 bytesReceived and bytesTotal .

The bytesReceived 参数指示接收字节数,而 bytesTotal 指示期望要下载的总字节数。若不知道要下载的字节数, bytesTotal 将是 -1。

下载完成当 bytesReceived 等于 bytesTotal 。在那时, bytesTotal 不会是 -1。

注意:值为 bytesReceived and bytesTotal 可能不同于 size (),总字节数的获取透过 read () 或 readAll (),header(ContentLengthHeader) 值。这样做的原因是可能有协议开销或数据压缩,在下载期间。

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

NetworkError QNetworkReply:: error () const

返回在此请求处理期间发现的错误。若未发现错误,返回 NoError .

另请参阅 setError ().

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

此信号被发射,当回复在进行中检测到错误时。 finished () 信号将可能跟随,指示连接已结束。

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

注意: 不要在槽中删除连接到此信号的对象。使用 deleteLater ().

注意: 信号 error 在此类中是重载。要使用函数指针句法连接到此信号,必须在静态铸造中指定信号类型,如此范例所示:

connect(networkReply, static_cast<void(QNetworkReply::*)(QNetworkReply::NetworkError)>(&QNetworkReply::error),
    [=](QNetworkReply::NetworkError code){ /* ... */ });
					

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

[signal] void QNetworkReply:: finished ()

此信号被发射,当回复处理完成时。在此信号被发射之后,回复数据 (或元数据) 将不再有更多更新。

除非 close () has been called, the reply will be still be opened for reading, so the data can be retrieved by calls to read () 或 readAll ()。尤其,若不调用 read () 生成结果源于 readyRead (),调用 readAll () 将检索全部内容按 QByteArray .

此信号串联发射采用 QNetworkAccessManager::finished () ,其中信号的回复参数是此对象。

注意: 不要在槽中删除连接到此信号的对象。使用 deleteLater ().

还可以使用 isFinished () 去校验,若 QNetworkReply 已完成,甚至在收到 finish() 信号之前。

另请参阅 setFinished (), QNetworkAccessManager::finished (),和 isFinished ().

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

Returns true if the raw header of name headerName 由远程服务器发送

另请参阅 rawHeader ().

返回值为已知头 header ,若 Header (头) 是由远程服务器发送的。若未发送头,则返回无效 QVariant .

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

[virtual slot] void QNetworkReply:: ignoreSslErrors ()

若此函数被调用,与网络连接相关的 SSL 错误将被忽略,包括证书验证错误。

警告: 确保始终让用户审查报告的错误通过 sslErrors () 信号,且仅调用此方法 (当用户确认后继续进行是 OK 的)。若存在意外错误,回复应被中止。不审查实际错误就调用此方法,很可能会给应用程序带来安全风险。小心使用!

可以调用此函数从槽连接到 sslErrors () 信号,指示发现了哪些错误。

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

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

这是重载函数。

若此函数被调用,SSL 错误给出于 errors 将被忽略。

注意: 由于大多数 SSL 错误关联证书,因此对于大多数证书而言,必须设置与此 SSL 错误相关的期望证书。例如,若想要向使用自签名证书的服务器发出请求,考虑以下片段:

QList<QSslCertificate> cert = QSslCertificate::fromPath(QLatin1String("server-certificate.pem"));
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.
					

多次调用此函数将替换先前调用传入错误列表。可以清零想要忽略的错误列表通过采用空列表调用此函数。

该函数在 Qt 4.6 引入。

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

bool QNetworkReply:: isFinished () const

Returns true when the reply has finished or was aborted.

该函数在 Qt 4.6 引入。

另请参阅 isRunning ().

bool QNetworkReply:: isRunning () const

Returns true when the request is still processing and the reply has not finished or was aborted yet.

该函数在 Qt 4.6 引入。

另请参阅 isFinished ().

QNetworkAccessManager * QNetworkReply:: manager () const

返回 QNetworkAccessManager 用于创建此 QNetworkReply 对象。最初,它还是父级对象。

[signal] void QNetworkReply:: metaDataChanged ()

此信号被发射,每当此回复的元数据改变时。元数据为不是 (数据) 内容本身的任何信息 (包括网络 Header 头)。在大多数情况下,元数据将完全已知,在收到第一数据字节时。不管怎样,接收 Header (头) 或其它元数据更新是可能的 (在数据处理期间)。

另请参阅 header (), rawHeaderList (), rawHeader (),和 hasRawHeader ().

QNetworkAccessManager::Operation QNetworkReply:: operation () const

返回此回复张贴的操作。

另请参阅 setOperation ().

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

返回原生内容的头 headerName 由远程服务器发送。若没有这种头,则返回空字节数组 (可能与空头难以区分)。使用 hasRawHeader () 去验证,若服务器发送这种头字段。

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

QList < QByteArray > QNetworkReply:: rawHeaderList () const

返回由远程服务器发送的 Header 字段列表,按发送顺序。重复 Header 被合并在一起并代替后者。

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

返回原生头对的列表。

qint64 QNetworkReply:: readBufferSize () const

返回读取缓冲的尺寸 (以字节为单位)。

另请参阅 setReadBufferSize ().

QNetworkRequest QNetworkReply:: request () const

返回用于此回复的张贴请求。特别注意,请求 URL 可能不同于回复 URL。

另请参阅 QNetworkRequest::url (), url (),和 setRequest ().

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

设置属性 code 到拥有值 value 。若 code 先前有设置,将覆写它。若 value 是无效 QVariant ,属性未设置。

另请参阅 属性 () 和 QNetworkRequest::setAttribute ().

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

将错误条件设为 errorCode 。设置人性化可读消息采用 errorString .

Calling setError() does not emit the error( QNetworkReply::NetworkError ) 信号。

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

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

把回复设为 finished .

在此设置之后,回复数据不得改变。

该函数在 Qt 4.8 引入。

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

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

设置已知头 header 到值 value 。还会设置 Header (头) 的相应原生形式。

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

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

把此对象的关联操作设置为 operation 。此值被返回通过 operation ().

Note: the operation should be set when this object is created and not changed again.

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

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

设置原生头 headerName 到值 value 。若 headerName 先前有设置,会被覆盖。相同名称的多个 HTTP 头在功能上相当于串联值的某一单头,以逗号分隔。

headerName 匹配已知 Header (头),值 value 将被剖析且还将设置相应剖析形式。

另请参阅 rawHeader (), header (), setHeader (),和 QNetworkRequest::setRawHeader ().

[虚拟] 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 ().

Note: the request should be set when this object is created and not changed again.

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

void QNetworkReply:: setSslConfiguration (const QSslConfiguration & config )

若可能的话,将此请求关联的网络连接的 SSL 配置设为 config .

另请参阅 sslConfiguration ().

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

将正在处理的 URL 设为 url 。通常,URL 匹配请求所张贴的 URL,但由于多种原因可能有所不同 (例如:将文件路径变为绝对路径或典型路径)。

另请参阅 url (), request (),和 QNetworkRequest::url ().

QSslConfiguration QNetworkReply:: sslConfiguration () const

返回此回复关联的 SSL 配置和状态,若有使用 SSL。它将包含远程服务器证书、通向证书颁发机构的证书链及在使用中的加密密码。

对等方的证书及其证书链将是已知的,当 sslErrors () 被发射时,若它被发射。

另请参阅 setSslConfiguration ().

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

此信号被发射,以指示此网络请求的上传部分的进度,若有的话。若没有上传关联此请求,则不会发射此信号。

The bytesSent 参数指示已上传的字节数,而 bytesTotal 指示要上传的总字节数。若无法确定要上传的字节数, bytesTotal 将是 -1。

上传完成当 bytesSent 等于 bytesTotal 。在那时, bytesTotal 不会是 -1。

另请参阅 downloadProgress ().

QUrl QNetworkReply:: url () const

Returns the URL of the content downloaded or uploaded. Note that the URL may be different from that of the original request.

另请参阅 request (), setUrl (),和 QNetworkRequest::url ().