QNetworkAccessManager Class
Header: #include
qmake: QT += network
Since: Qt 4.4
Inherits: QObject.
注意:这个类中所有的函数都是可重入的.
这个QNetworkAccessManager类允许应用程序发送网络请求并且接收应答.
这个Network API围绕着QNetworkAccessManager对象进行构造,保存着它将要发送的请求信息相关的常用的配置和设置信息.它还包含着代理和缓存配置,以及这类问题相关的信号,和可以被用来监视网络操作过程的应答信号.对于QT应用程序,一个QNetworkAccessManager应该就足够了.
一旦QNetworkAccessManager被创建好,应用程序就可以使用它再互联网上发送请求了.一组标准函数可以申请一个请求以及可选数据后被支持，每一次都返回一个QNetworkReply对象。返回对象被用来包含任何在通信请求的响应了的数据。
一个简单的下载网络可以像下面那样实现：
QNetworkAccessManager *manager = new QNetworkAccessManager(this);
connect(manager, SIGNAL(finished(QNetworkReply*)),
this, SLOT(replyFinished(QNetworkReply*)));
manager->get(QNetworkRequest(QUrl("http://qt-project.org")));
QNetworkAccessManager有一个异步的API。当replyFinished槽被呼叫了后，它带有的参数是QNetworkReply对象包含下载的数据以及元数据（meta-data）等等。
注意：在请求完成后，在合适的时间内删除这个QNetworkReply对象是用户的责任。不要在连接到finished()的槽上直接删除它。你可以使用这个deleteLater()函数。
注意：QNetworkAccessManager将它接收到的请求排成一个队列。请求被执行的序号决定于遵循的协议。当前，对于桌面平台的HTTP协议来说，对于一个主机/端口组合并行执行着6个请求。
一个更复杂的例子，假定manager是确定已经存在了，可以是：
QNetworkRequest request;
request.setUrl(QUrl("http://qt-project.org"));
request.setRawHeader("User-Agent", "MyOwnBrowser 1.0");
QNetworkReply *reply = manager->get(request);
connect(reply, SIGNAL(readyRead()), this, SLOT(slotReadyRead()));
connect(reply, SIGNAL(error(QNetworkReply::NetworkError)),
this, SLOT(slotError(QNetworkReply::NetworkError)));
connect(reply, SIGNAL(sslErrors(QList)),
this, SLOT(slotSslErrors(QList)));
Network and Roaming Support
网络和漫游支持
QT4.7 附加的载体管理API（ Bearer Management API ）增加了网络连接管理的能力。如果这个设备处于离线，QNetworkAccessManager可以启动网络接口；如果当前进程是最后一个去上行的话，则可以去终止网络接口。注意：当最后的应用程序停止去使用一个上行数据，直到系统确实终止了连接着的链接时，某些平台利用空闲时期。漫游同样是清晰的。任何排队了的网络请求自动转换到新的存取点。
客户端想要去利用这个特征，不应该请求任何改变。事实上，从一个存在的平台的指定连接上的应用程序中简单的移除连接是可能的。
注意：在 QNetworkAccessManager中对网络和漫游的支持是被空载在平台支持管理连接上（意思是首先依赖于硬件特性）。
这个QNetworkConfigurationManager::NetworkSessionRequired 可以被用来去检测是否 QNetworkAccessManager利用了这个特性。
具体参见QNetworkRequest, QNetworkReply, and QNetworkProxy.
Member Type Documentation
成员类型文档
enum QNetworkAccessManager::NetworkAccessibility
指示是否网络是可以通过网络存取管理器去存取操作。
| Constant | Value | Description |
|---|---|---|
QNetworkAccessManager::UnknownAccessibility |
-1 |
网络存取能力不确定 |
QNetworkAccessManager::NotAccessible |
0 |
网络当前是不可存取的，因为 当前没有网络覆盖或者网络存取已经被 setNetworkAccessible()明确声明了不可用。 |
QNetworkAccessManager::Accessible |
1 |
网络可以使用。 |
See also networkAccessible.
enum QNetworkAccessManager::Operation
指示应答过程的操作。
| Constant | Value | Description |
|---|---|---|
QNetworkAccessManager::HeadOperation |
1 |
取回头操作 (created with head()) |
QNetworkAccessManager::GetOperation |
2 |
取回头和下载内容 (created with get()) |
QNetworkAccessManager::PutOperation |
3 |
上传内容操作 (created with put()) |
QNetworkAccessManager::PostOperation |
4 |
通过HTTP POST过程去发送一个HTML格式的内容 (created with post()) |
QNetworkAccessManager::DeleteOperation |
5 |
删除内容操作(created with deleteResource()) |
QNetworkAccessManager::CustomOperation |
6 |
自定义操作 (created with sendCustomRequest()) |
This enum was introduced or modified in Qt 4.7.
See also QNetworkReply::operation().
Property Documentation
属性文档
networkAccessible : NetworkAccessibility
这个属性保存着通过网络存取管理器是否当前网络是可以进行存取的。
如果网络是不可以使用的，网络存取管理器将不会处理任何新的网络请求，所有的这类请求将失败并返回错误。带有URLS的文件请求的file://进程将一直持续着。
默认情况下属性值反映设备的物理状态。应用程序可以覆盖它，通过使用网络存取管理器使得所有网络请求不可用，靠呼叫下列语句：
networkAccessManager->setNetworkAccessible(QNetworkAccessManager::NotAccessible);Network requests can be reenabled again by calling
可以通过呼叫以下语句使得网络请求可以再次使用：
networkAccessManager->setNetworkAccessible(QNetworkAccessManager::Accessible);注意：呼叫setNetworkAccessible()不能改变网络状态。
This property was introduced in Qt 4.7.
存取函数（Access functions）:
| NetworkAccessibility | networkAccessible() const |
| void | setNetworkAccessible(NetworkAccessibility accessible) |
通知信号（Notifier signal）：
| void | networkAccessibleChanged(QNetworkAccessManager::NetworkAccessibility accessible) |
Member Function Documentation成员函数文档
QNetworkAccessManager::QNetworkAccessManager(QObject * parent = 0)
构造一个QNetworkAccessManager对象，作为网络存取API的核心，并且设置其父亲目标为父对象。(构造函数)
QNetworkAccessManager::~QNetworkAccessManager()
注意:从这个类返回的QNetworkReply对象拥有跟他爹一样的对象集,这意味着如果你没有通过它呼叫QObject::setParent() 的话,他们将自动删除这些东西.(析构函数嘛)
销毁QNetworkAccessManager对象，并且释放所有资源。注意：从这个类返回的 QNetworkReply对象
QNetworkConfiguration QNetworkAccessManager::activeConfiguration() const
返回当前活动的网络配置.
如果被configuration()返回的网络配置是QNetworkConfiguration::ServiceNetwork型,这个函数将返回当前活动的子网络配置信息.否则返回同configuration()一样的配置数据.
Use this function to return the actual network configuration currently in use by the network session.
使用这个函数去返回当前在使用的确切的网络回话对应的网络配置.
This function was introduced in Qt 4.7.
See also configuration().
void QNetworkAccessManager::authenticationRequired(QNetworkReply * reply, QAuthenticator * authenticator)
这个信号再当一个完成服务请求认证的时候,在交付请求内容之前,被发射出来. 连接到这个信号的槽应该填好在认证对象中的内容认证信息(可以被拒绝对象的检查所拒绝).
QNetworkAccessManager将缓存这个内部凭据,并且如果服务器再次请求认证的话,将发送相同的值,不发射authenticationRequired()信号.如果它拒绝了凭据,这个信号将再次被发送出来.
注意:要拥有不发送凭据的请求,你不必再次呼叫认证对象上的setUser()和setPassword().这将导致finished()信号被发射出来,带有error AuthenticationRequiredError的QNetworkReply对象.
as the connection will fail if the authenticator has not been filled in with new information when the signal returns.
注意:使用QueuedConnection去连接这个信号是不可能的,因为如果当信号返回时,认证器(authenticator)不填写好新的信息,连接将会失败.
具体见 proxyAuthenticationRequired(), QAuthenticator::setUser(), and QAuthenticator::setPassword().
QAbstractNetworkCache * QNetworkAccessManager::cache() const
返回从网络上包含的被使用的数据缓存.
This function was introduced in Qt 4.5.
具体见 setCache().
void QNetworkAccessManager::clearAccessCache()
这个函数再做自动测试中是很有用的.
This function was introduced in Qt 5.0.
QNetworkConfiguration QNetworkAccessManager::configuration() const
返回将被用来创建网络会话(将在网络请求过程中的使用)的网络配置信息.
This function was introduced in Qt 4.7.
See also setConfiguration() and activeConfiguration().
void QNetworkAccessManager::connectToHost(const QString & hostName, quint16 port = 80)
初始化了一个到给定主机名和端口号的主机的连接.在HTTP请求完成之前,这个函数在实现TCP到主机的握手是很有用的,导致一个很低的网络延迟.
注意:这个函数没有可能去报告错误.
This function was introduced in Qt 5.2.
具体见 connectToHostEncrypted(), get(), post(), put(), and deleteResource().
void QNetworkAccessManager::connectToHostEncrypted(const QString & hostName, quint16 port = 443, const QSslConfiguration & sslConfiguration = QSslConfiguration::defaultConfiguration())
初始化了一个到给定主机名和端口号的主机的连接,使用sslConfiguration.这个函数,对于在HTTP请求之前,实现TCP以及SSL到一个主机的握手,是很有用的,且有低的网络延迟.
注意:提前连接到一个SPDY(http://www.bing.com/knows/search?q=spdy&mkt=zh-cn)连接,可以在带有包含允许使用的协议列表的QSslConfiguration::NextProtocolSpdy3_0的sslConfiguration通过呼叫setAllowedNextProtocols()来实现.当使用SPDY时,每个主机一个简单的连接就是足够的.例如:每个主机多次呼叫方法将不会导致更快的网络传输.
注意:这个函数没有可能去报告错误.
This function was introduced in Qt 5.2.
具体见 connectToHost(), get(), post(), put(), and deleteResource().
QNetworkCookieJar * QNetworkAccessManager::cookieJar() const
Returns the QNetworkCookieJar that is used to store cookies obtained from the network as well as cookies that are about to be sent.
返回QNetworkCookieJar(被用来去存储来自网络的cookies),同被发送的cookies差不多的个东西.
具体见 setCookieJar().
QNetworkReply * QNetworkAccessManager::createRequest(Operation op, const QNetworkRequest & req, QIODevice * outgoingData = 0)
返回一个新的QNetworkReply对象去处理操作跟请求.这个设备对于Get和Head请求传出数据总是0,但是 是传送到post()和put()操作的值.(QByteArray变量将传送一个QBuffer对象)
The default implementation calls QNetworkCookieJar::cookiesForUrl() on the cookie jar set with setCookieJar() to obtain the cookies to be sent to the remote server.
返回对象一定是处在一个打开状态.
QNetworkReply * QNetworkAccessManager::deleteResource(const QNetworkRequest & request)
发送一个请求去删除由请求中的URL指定的资源.
注意:这些特征只对于HTTP协议是当前是可用的,执行一个HTTP DELETE 请求.
This function was introduced in Qt 4.6.
具体见 get(), post(), put(), and sendCustomRequest().
void QNetworkAccessManager::encrypted(QNetworkReply * reply) [signal]
当一个SSL/TLS会话成功的实现了初始化握手时,这个信号被发射出来.在这一点,没有用户数据被传输.这个信号可以被用来去执行在凭证链上的额外的检查,例如当网站凭证改变后,去通知用户.应答参数指定了哪一个网络答复是应该的职责.如果应答没有匹配到预期的标准,那么它应该通过一个槽连接到这个信号,呼叫QNetworkReply::abort().使用中的SSL配置可以使用QNetworkReply::sslConfiguration()方法被检查.
本质上QNetworkAccessManager可以打开多个连接到服务器上,为了允许它处理并行的请求.这些连接可以被拒绝,那样就意味着encrypted()信号将不会被发射.意思是你仅仅在QNetworkAccessManager的生命周期内确保接受第一次连接到站点的这个信号.
This function was introduced in Qt 5.1.
具体见 QSslSocket::encrypted() and QNetworkReply::encrypted().
void QNetworkAccessManager::finished(QNetworkReply * reply)
无论什么时候一个挂起的网络应答完成时,这个信号被发射.应答参数将包含一个到刚刚完成的应答的指针.这个信号随着QNetworkReply::finished()信号一起发射出来.
这个对象将要进入的状态后的信息,可以参考QNetworkReply::finished().
Note: Do not delete the reply object in the slot connected to this signal. Use deleteLater().
注意:在槽连接到这个信号的时候,不要删除应答对象.使用deleteLater().
具体见 QNetworkReply::finished() and QNetworkReply::error().
QNetworkReply * QNetworkAccessManager::get(const QNetworkRequest & request)
提交一个包含目标请求内容的请求.并且返回一个新的允许读的打开了的QNetworkReply对象,无论新数据什么时候到达都将发射readyRead()信号.
内容以及关联的头(headers)将被下载.
具体见 post(), put(), deleteResource(), and sendCustomRequest().
QNetworkReply * QNetworkAccessManager::head(const QNetworkRequest & request)
Posts a request to obtain the network headers for request and returns a new QNetworkReply object which will contain such headers.
提交一个包含请求报文网络头的请求,并且返回一个新的QNetworkReply对象,将包含headers头.
The function is named after the HTTP request associated (HEAD).
QNetworkReply * QNetworkAccessManager::post(const QNetworkRequest & request, QIODevice * data)
发送一个HTTP POST请求到请求中指定的目标.并且返回一个新的打开了的可读的QNetworkReply对象,将包含应答发送到服务器.数据设备的内容将上传到服务器.
数据必须得打开着并且可读,保留着有效性知道应答中finished()信号被发射出来.
注意:发送一个基于协议的提交请求,基于HTTP以及HTTPS是未定义的,并且可能失败.
具体见 get(), put(), deleteResource(), and sendCustomRequest().
QNetworkReply * QNetworkAccessManager::post(const QNetworkRequest & request, const QByteArray & data)
这是一个重载函数.
发送数据字节数组中的内容到请求指定的目标主机.
QNetworkReply * QNetworkAccessManager::post(const QNetworkRequest & request, QHttpMultiPart * multiPart)
这是一个重载函数.
发送multiPart信息内容到请求指定的目标主机.
这个可以被用来在HTTP上去发送MIME multiPart信息.
This function was introduced in Qt 4.8.
具体见 QHttpMultiPart, QHttpPart, and put().
QNetworkProxy QNetworkAccessManager::proxy() const
返回个QNetworkProxy对象,使用QNetworkAccessManager对象发送的请求将被使用.默认代理的值是QNetworkProxy::DefaultProxy.
具体见 setProxy(), setProxyFactory(), and proxyAuthenticationRequired().
void QNetworkAccessManager::proxyAuthenticationRequired(const QNetworkProxy & proxy, QAuthenticator * authenticator)
无论什么时候,一个代理请求认证,并且QNetworkAccessManager不能找到一个有效的,缓存的凭证时,这个信号将被发射出来.连接到这个信号的槽应该填充认证对象的代理凭证.
QNetworkAccessManager将缓存中间的凭证.下一次,代理请求认证,QNetworkAccessManager将自动发送相同的凭证,而不再发射代理认证请求信号.
如果代理拒绝了凭证,QNetworkAccessManager将再次发射这个信号.
具体见 proxy(), setProxy(), and authenticationRequired().
QNetworkProxyFactory * QNetworkAccessManager::proxyFactory() const
返回代理工厂,QNetworkAccessManager对象使用去终止曾经请求中使用了的代理.
注意:这个函数返回的指针是被QNetworkAccessManager管理着,并且可以在任何时候被删除.
This function was introduced in Qt 4.5.
具体见 setProxyFactory() and proxy().
QNetworkReply * QNetworkAccessManager::put(const QNetworkRequest & request, QIODevice * data)
上传数据中的内容到目标请求,并且返回一个新的将被打开并且准备回应的QNetworkReply对象.
数据必须是打开着可读的,当这个函数被呼叫,并且必须保持有效性知道finished()信号为了应答而被发射出来.
注意:对于HTTP,这个请求将发送一个大多数服务器不允许的PUT请求.形式上传机器,包括通过HTML表单上传文件,使用POST机械.
具体见 get(), post(), deleteResource(), and sendCustomRequest().
QNetworkReply * QNetworkAccessManager::put(const QNetworkRequest & request, QHttpMultiPart * multiPart)
这是一个重载函数.
发送多个部分的信息的内容到请求指定的目标主机上.
它可以被用来在HTTP上去发送MIME multipart信息.
This function was introduced in Qt 4.8.
See also QHttpMultiPart, QHttpPart, and post().
QNetworkReply * QNetworkAccessManager::put(const QNetworkRequest & request, const QByteArray & data)
这是一个重载函数.
发送数据字节数组的内容到请求指定的目标主机上.
QNetworkReply * QNetworkAccessManager::sendCustomRequest(const QNetworkRequest & request, const QByteArray & verb, QIODevice * data = 0)
发送自定义请求到请求URL指定的服务器上.
发送一个根据HTTP规定是有效的动词到服务器,是用户的职责.
这个方法提供了发送动词的方法,而不是常用的提供了的那些get(),post()等等.例如发送一个HTTP OPTIONS命令.
如果数据不是空的,数据设备的内容将被上传到服务器上;在那种情况下,数据必须是打开着的并且可读,必须保持有效性,知道finished()信号为了应答而发射出来.
注意:这个特征只对于当前的HTTP(S)有效.
This function was introduced in Qt 4.7.
See also get(), post(), put(), and deleteResource().
void QNetworkAccessManager::setCache(QAbstractNetworkCache * cache)
设置管理者的网络缓存作为指定缓存.这个指派的缓存将被所有请求公用.
用这个函数去设置网络缓存对象到一个类上,以实现额外的特征,像保存cookies为永久存储.
注意:QNetworkAccessManager拥有缓存对象的所有权.
默认的QNetworkAccessManager没有一个缓存集.Qt提供了一个简单的缓存,QNetworkDiskCache可以被使用.
This function was introduced in Qt 4.5.
具体见cache() and QNetworkRequest::CacheLoadControl.
void QNetworkAccessManager::setConfiguration(const QNetworkConfiguration & config)
设置将要被使用的网络配置信息,当创建一个网络会话时时.
在任何请求要求网络存取的过程之前,网络配置将被用来去创建并打开一个网络会话.如果通过这个函数没有得到明确的网络配置设置,被QNetworkConfigurationManager::defaultConfiguration()返回的网络配置将被使用.
将从QNetworkConfigurationManager::defaultConfiguration()设置并存储为默认的网络配置.
设置一个网络配置意味着QNetworkAccessManager实例将只被用到一个指定的地方.特别是,如果默认网络配置改变后(upon e.g. Wifi being available),如果渴望的话新的配置需要改为可用操作.
QNetworkConfigurationManager manager;
networkAccessManager->setConfiguration(manager.defaultConfiguration());
如果一个无效的网络配置被设置好,网络会话将不会被创建.这种情况下,网络请求将被忽视处理,但是也可能是失败.例如:
networkAccessManager->setConfiguration(QNetworkConfiguration());
This function was introduced in Qt 4.7.
具体见 configuration() and QNetworkSession.
void QNetworkAccessManager::setCookieJar(QNetworkCookieJar * cookieJar)
设置管理员的cookie jar为指定的cookieJar.这个cookie jar将被所有的有管理着指派的请求所使用.
使用这个函数去设置cookie jar对象为一个额外特征的实现,像 存储cookie为永久存储.
注意:QNetworkAccessManager拥有cookieJar对象的所有权.
如果cookieJar跟QNetworkAccessManager再同一个线程中时,它将设置cookieJar的父对象,以使当这个对象被删除时,cookie jar也被删除.如果你想要在不同的QNetworkAccessManager对象间去共享cookie Jars,你可以在呼叫这个函数之后,想要去设置cookie Jar的父对象为0.
QNetworkAccessManager默认情况下不会实现任何自己的cookie方法:它接受所有被服务器发送来的cookie,只要它们复合最小的安全要求(cookie域匹配请求并且cookie路径匹配请求的路径).为了实现你自己的安全方法,重写QNetworkCookieJar::cookiesForUrl()和QNetworkCookieJar::setCookiesFromUrl()虚函数.当它检测到新的cookie时,那些函数被QNetworkAccessManager呼叫.
具体见 cookieJar(), QNetworkCookieJar::cookiesForUrl(), and QNetworkCookieJar::setCookiesFromUrl().
void QNetworkAccessManager::setProxy(const QNetworkProxy & proxy)
设置未来被代理的请求的代理.这不会影响已经发送了的请求.如果代理请求认证是,proxyAuthenticationRequired()信号将被发射出来.
使用这个函数去设置的代理,将被所有QNetworkAccessManager遇到的请求所使用.在有些情况下,根据被发送到目的主机的请求,选择不同的代理可能是必须的.如果那样的话,你应该考虑使用setProxyFactory().
具体见 proxy() and proxyAuthenticationRequired().
void QNetworkAccessManager::setProxyFactory(QNetworkProxyFactory * factory)
为这个类设置代理工厂去代理(factory).一个代理工厂被用来去决定一个更多的指定被给定请求使用的代理列表,而不是让所有的请求尝试去使用相同的代理值.
所有被QNetworkAccessManager发送的查询将拥有QNetworkProxyQuery::UrlRequest类型.
例如,代理工厂可以应用下列的规则:
如果目标地址是本地网络(例如,如果主机名没有包含点dot,或者如果它是一个组织范围内的IP地址),则返回QNetworkProxy::NoProxy.
如果请求是FTP,返回一个FTP代理.
如果请求是HTTP或者HTTPS,然后会返回一个HTTP代理.
否则,返回一个SOCKSv5代理服务.
对象工厂的生命周期将被QNetworkAccessManager管理.当需要的时候它将删除这个对象.
注意:如果已经使用setProxy()设定了一个指定的代理,这个工厂(Factory)将不再被使用.
This function was introduced in Qt 4.5.
具体见 proxyFactory(), setProxy(), and QNetworkProxyQuery.
void QNetworkAccessManager::sslErrors(QNetworkReply * reply, const QList
在设置时如果SSL/TLS会话遇到错误时,这个信号被发射出来,包括证书验证错误.这个错误参数包含错误列表,响应是遇到这些错误的QNetworkReply对象.
去指示错误并不是致命的,并且连接应该继续进行,QNetworkReply::ignoreSslErrors()函数应该从连接着的槽到这个信号中被呼叫.如果它没有被呼叫,在任何数据交换之前,SSL会话将被遗弃(包括URL).
This signal can be used to display an error message to the user indicating that security may be compromised and display the SSL settings (see sslConfiguration() to obtain it)
这个信号可以被用来去显示一个错误信息, 在分析了远程证书后,如果用户决定继续进行的话,这个槽应该呼叫ignoreSslErrors()函数.
具体见 QSslSocket::sslErrors(), QNetworkReply::sslErrors(), QNetworkReply::sslConfiguration(), and QNetworkReply::ignoreSslErrors().
QStringList QNetworkAccessManager::supportedSchemes() const
列出所有被存取管理器支持的URL主题.
This function was introduced in Qt 5.2.
具体见 supportedSchemesImplementation().
QStringList QNetworkAccessManager::supportedSchemesImplementation() const [protected slot]
列出所有被存取管理器支持的设计(schemes).
你不应该直接呼叫这个函数,而是应该使用QNetworkAccessManager::supportedSchemes().
在一个QNetworkAccessManager子类中重新实现这个槽去提供你自己支持的主题schemes.当你的子类提供了对新协议的支持是很有必要的实例.
因为二进制兼容性限制,supportedSchemes()不是虚函数.supportedSchemes()方法(introduced in Qt 5.2)将动态检测并且呼叫对应的槽.
This function was introduced in Qt 5.2.
见 supportedSchemes().