The QNetworkAccessManager class allows the application to send network requests and receive replies 更多...
| 头： | #include <QNetworkAccessManager> |
| Since: | Qt 4.4 |
| 继承： | QObject |
注意： 此类的所有函数 可重入 .
| enum | NetworkAccessibility { UnknownAccessibility, NotAccessible, Accessible } |
| enum | Operation { HeadOperation, GetOperation, PutOperation, PostOperation, DeleteOperation, CustomOperation } |
| QNetworkAccessManager (QObject * parent = 0) | |
| ~QNetworkAccessManager () | |
| QNetworkConfiguration | activeConfiguration () const |
| QAbstractNetworkCache * | cache () const |
| QNetworkConfiguration | configuration () const |
| QNetworkCookieJar * | cookieJar () const |
| QNetworkReply * | deleteResource (const QNetworkRequest & request ) |
| QNetworkReply * | get (const QNetworkRequest & request ) |
| QNetworkReply * | head (const QNetworkRequest & request ) |
| NetworkAccessibility | networkAccessible () const |
| QNetworkReply * | post (const QNetworkRequest & request , QIODevice * data ) |
| QNetworkReply * | post (const QNetworkRequest & request , const QByteArray & data ) |
| QNetworkReply * | post (const QNetworkRequest & request , QHttpMultiPart * multiPart ) |
| QNetworkProxy | proxy () const |
| QNetworkProxyFactory * | proxyFactory () const |
| QNetworkReply * | put (const QNetworkRequest & request , QIODevice * data ) |
| QNetworkReply * | put (const QNetworkRequest & request , QHttpMultiPart * multiPart ) |
| QNetworkReply * | put (const QNetworkRequest & request , const QByteArray & data ) |
| QNetworkReply * | sendCustomRequest (const QNetworkRequest & request , const QByteArray & verb , QIODevice * data = 0) |
| void | setCache (QAbstractNetworkCache * cache ) |
| void | setConfiguration (const QNetworkConfiguration & config ) |
| void | setCookieJar (QNetworkCookieJar * cookieJar ) |
| void | setNetworkAccessible (NetworkAccessibility accessible ) |
| void | setProxy (const QNetworkProxy & proxy ) |
| void | setProxyFactory (QNetworkProxyFactory * factory ) |
| void | authenticationRequired (QNetworkReply * reply , QAuthenticator * authenticator ) |
| void | finished (QNetworkReply * reply ) |
| void | networkAccessibleChanged (QNetworkAccessManager::NetworkAccessibility accessible ) |
| void | proxyAuthenticationRequired (const QNetworkProxy & proxy , QAuthenticator * authenticator ) |
| void | sslErrors (QNetworkReply * reply , const QList<QSslError> & errors ) |
| virtual QNetworkReply * | createRequest (Operation op , const QNetworkRequest & req , QIODevice * outgoingData = 0) |
The QNetworkAccessManager class allows the application to send network requests and receive replies
The Network Access API is constructed around one QNetworkAccessManager object, which holds the common configuration and settings for the requests it sends. It contains the proxy and cache configuration, as well as the signals related to such issues, and reply signals that can be used to monitor the progress of a network operation. One QNetworkAccessManager should be enough for the whole Qt application.
一旦 QNetworkAccessManager object has been created, the application can use it to send requests over the network. A group of standard functions are supplied that take a request and optional data, and each return a QNetworkReply 对象。返回对象用于获取响应相应请求，返回的任何数据。
完成简单下载网络断开，可以采用：
QNetworkAccessManager *manager = new QNetworkAccessManager(this); connect(manager, SIGNAL(finished(QNetworkReply*)), this, SLOT(replyFinished(QNetworkReply*))); manager->get(QNetworkRequest(QUrl("http://qt.nokia.com")));
QNetworkAccessManager
has an asynchronous API. When the
replyFinished
槽被调用时，它接受的参数是
QNetworkReply
对象，包含下载数据及元数据 (Header 头、等)。
注意： 在请求完成后，用户有责任删除 QNetworkReply 对象，在适当时。不要直接在槽内删除它，因为槽已连接到 finished ()。可以使用 deleteLater () 函数。
注意： QNetworkAccessManager queues the requests it receives. The number of requests executed in parallel is dependent on the protocol. Currently, for the HTTP protocol on desktop platforms, 6 requests are executed in parallel for one host/port combination.
假定管理器已存在，更多涉及范例可以是：
QNetworkRequest request; request.setUrl(QUrl("http://qt.nokia.com")); 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<QSslError>)), this, SLOT(slotSslErrors(QList<QSslError>)));
With the addition of the 承载管理 API to Qt 4.7 QNetworkAccessManager gained the ability to manage network connections. QNetworkAccessManager can start the network interface if the device is offline and terminates the interface if the current process is the last one to use the uplink. Note that some platform utilize grace periods from when the last application stops using a uplink until the system actually terminates the connectivity link. Roaming is equally transparent. Any queued/pending network requests are automatically transferred to new access point.
Clients wanting to utilize this feature should not require any changes. In fact it is likely that existing platform specific connection code can simply be removed from the application.
注意： The network and roaming support in QNetworkAccessManager is conditional upon the platform supporting connection management. The QNetworkConfigurationManager::NetworkSessionRequired can be used to detect whether QNetworkAccessManager utilizes this feature. Currently only Meego/Harmattan and Symbian platforms provide connection management support.
注意： This feature cannot be used in combination with the Bearer Management API as provided by QtMobility. Applications have to migrate to the Qt version of Bearer Management.
On Symbian, processes which use this class must have the
NetworkServices
platform security capability. If the client process lacks this capability, operations will result in a panic.
Platform security capabilities are added via the TARGET.CAPABILITY qmake variable.
另请参阅 QNetworkRequest , QNetworkReply ，和 QNetworkProxy .
Indicates whether the network is accessible via this network access manager.
| 常量 | 值 | 描述 |
|---|---|---|
QNetworkAccessManager::UnknownAccessibility
|
-1
|
网络的可访问性不能确定。 |
QNetworkAccessManager::NotAccessible
|
0
|
The network is not currently accessible, either because there is currently no network coverage or network access has been explicitly disabled by a call to setNetworkAccessible (). |
QNetworkAccessManager::Accessible
|
1
|
网络是可访问的。 |
另请参阅 networkAccessible .
指示此回复正在处理的操作。
| 常量 | 值 | 描述 |
|---|---|---|
QNetworkAccessManager::HeadOperation
|
1
|
检索 Header (头) 操作 (创建采用 head ()) |
QNetworkAccessManager::GetOperation
|
2
|
检索 Header (头) 并下载内容 (创建采用 get ()) |
QNetworkAccessManager::PutOperation
|
3
|
上传内容操作 (创建采用 put ()) |
QNetworkAccessManager::PostOperation
|
4
|
经由 HTTP POST 发送用于处理的 HTML 表单内容 (创建采用 post ()) |
QNetworkAccessManager::DeleteOperation
|
5
|
删除内容操作 (创建采用 deleteResource ()) |
QNetworkAccessManager::CustomOperation
|
6
|
自定义操作 (创建采用 sendCustomRequest ()) |
该枚举在 Qt 4.7 引入或被修改。
另请参阅 QNetworkReply::operation ().
This property holds whether the network is currently accessible via this network access manager.
If the network is not accessible the network access manager will not process any new network requests, all such requests will fail with an error. Requests with URLs with the file:// scheme will still be processed.
By default the value of this property reflects the physical state of the device. Applications may override it to disable all network requests via this network access manager by calling
networkAccessManager->setNetworkAccessible(QNetworkAccessManager::NotAccessible);
Network requests can be reenabled again by calling
networkAccessManager->setNetworkAccessible(QNetworkAccessManager::Accessible);
注意： Calling setNetworkAccessible() does not change the network state.
该特性在 Qt 4.7 引入。
访问函数：
| NetworkAccessibility | networkAccessible () const |
| void | setNetworkAccessible (NetworkAccessibility accessible ) |
通知程序信号：
| void | networkAccessibleChanged (QNetworkAccessManager::NetworkAccessibility accessible ) |
构造 QNetworkAccessManager object that is the center of the Network Access API and sets parent 作为父级对象。
销毁 QNetworkAccessManager 对象并释放任何资源。注意 QNetworkReply objects that are returned from this class have this object set as their parents, which means that they will be deleted along with it if you don't call QObject::setParent () on them.
Returns the current active network configuration.
If the network configuration returned by configuration () is of type QNetworkConfiguration::ServiceNetwork this function will return the current active child network configuration of that configuration. Otherwise returns the same network configuration as configuration ().
Use this function to return the actual network configuration currently in use by the network session.
该函数在 Qt 4.7 引入。
另请参阅 configuration ().
[signal]
void
QNetworkAccessManager::
authenticationRequired
(
QNetworkReply
*
reply
,
QAuthenticator
*
authenticator
)
此信号被发射每当最终服务器请求身份验证，在交付请求内容之前。连接到此信号的槽应为内容填充证书（可以确定通过审查 reply 对象) 在 authenticator 对象。
QNetworkAccessManager 会在内部缓存证书并发送相同值，若服务器再次要求身份验证，而不发射 authenticationRequired() 信号。若它拒绝证书，此信号会被再次发射。
注意： 使用 QueuedConnection 去连接到此信号是不可能的，因为连接会失败，若身份验证器没有采新信息被填充，当信号返回时。
另请参阅 proxyAuthenticationRequired ().
返回用于存储从网络获得数据的缓存。
该函数在 Qt 4.5 引入。
另请参阅 setCache ().
Returns the network configuration that will be used to create the network session which will be used when processing network requests.
该函数在 Qt 4.7 引入。
另请参阅 setConfiguration () 和 activeConfiguration ().
返回 QNetworkCookieJar 用于存储从网络获得的 Cookie 及即将被发送的 Cookie。
另请参阅 setCookieJar ().
[virtual protected]
QNetworkReply
* QNetworkAccessManager::
createRequest
(
Operation
op
, const
QNetworkRequest
&
req
,
QIODevice
*
outgoingData
= 0)
返回新的 QNetworkReply 对象以处理操作 op 和请求 req 。设备 outgoingData 始终为 0 对于 Get 和 Head 请求而言，但是值被传递给 post () 和 put () 在这些操作中 ( QByteArray 变体会传递 QBuffer 对象)。
默认实现调用 QNetworkCookieJar::cookiesForUrl () 当 Cookie Jar 设置采用 setCookieJar () 以获得要被发送给远程服务器的 Cookie。
返回的对象必须处于打开状态。
发送请求以删除资源标识通过 URL 的 request .
注意： 此特征目前只可用于 HTTP，履行 HTTP DELETE 请求。
该函数在 Qt 4.6 引入。
另请参阅 get (), post (), put ()，和 sendCustomRequest ().
[signal]
void
QNetworkAccessManager::
finished
(
QNetworkReply
*
reply
)
此信号被发射每当待决网络回复完成时。 reply 参数将包含指向刚刚完成的回复的指针。此信号被串联发射采用 QNetworkReply::finished () 信号。
见 QNetworkReply::finished () 了解对象将处于何种状态的有关信息。
注意： 不要删除 reply 对象在连接到此信号的槽中。使用 deleteLater ().
另请参阅 QNetworkReply::finished () 和 QNetworkReply::error ().
张贴请求以获取内容对于目标 request 并返回新的 QNetworkReply 对象并打开为读取发射的 readyRead() 信号，每当新数据到达时。
会下载内容及关联 Header (头)。
另请参阅 post (), put (), deleteResource ()，和 sendCustomRequest ().
张贴请求以获取网络头为 request 并返回新的 QNetworkReply 对象 (将包含这种 Header 头)。
函数以 HTTP 请求关联 HEAD 头命名。
把 HTTP POST (张贴) 请求发送给指定目的地通过 request 并返回新的 QNetworkReply 为读取而打开的对象，将包含由服务器所发送的回复。内容对于 data 设备将上传到服务器。
data 必须被打开以供读取且必须保持有效，直到 finished () 信号被发射为此回复。
注意： 发送除 HTTP HTTPS 协议的 POST (张贴) 请求是未定义的，且可能失败。
另请参阅 get (), put (), deleteResource ()，和 sendCustomRequest ().
这是重载函数。
发送内容为 data 字节数组到目的地指定通过 request .
这是重载函数。
发送内容为 multiPart 消息到目的地指定通过 request .
这可以被用于通过 HTTP 发送 MIME 多部分消息。
该函数在 Qt 4.8 引入。
另请参阅 QHttpMultiPart , QHttpPart ，和 put ().
返回 QNetworkProxy 请求发送使用此 QNetworkAccessManager 对象将使用。代理的默认值为 QNetworkProxy::DefaultProxy .
另请参阅 setProxy (), setProxyFactory ()，和 proxyAuthenticationRequired ().
[signal]
void
QNetworkAccessManager::
proxyAuthenticationRequired
(const
QNetworkProxy
&
proxy
,
QAuthenticator
*
authenticator
)
此信号被发射每当代理请求身份验证和 QNetworkAccessManager cannot find a valid, cached credential. The slot connected to this signal should fill in the credentials for the proxy proxy 在 authenticator 对象。
QNetworkAccessManager will cache the credentials internally. The next time the proxy requests authentication, QNetworkAccessManager will automatically send the same credential without emitting the proxyAuthenticationRequired signal again.
若代理拒绝证书， QNetworkAccessManager 会再次发射信号。
另请参阅 proxy (), setProxy ()，和 authenticationRequired ().
返回代理工厂，此 QNetworkAccessManager 对象被用于确定要被用于请求的代理。
注意：由此函数返回的指针的管理是通过 QNetworkAccessManager 且可以在任何时候被删除。
该函数在 Qt 4.5 引入。
另请参阅 setProxyFactory () 和 proxy ().
上传内容为 data 到目的地 request and returnes a new QNetworkReply 对象会被打开为回复。
data 必须被打开以供读取，当此函数被调用时；且必须保持有效直到 finished () 信号被发射为此回复。
返回对象是否有任何东西可供读取，取决于协议。对于 HTTP，服务器可能发送指示上传成功 (或不成功) 的小 HTML 页面。其它协议可能会在其回复中有内容。
注意： 对于 HTTP，此请求将发送 PUT 请求 (大多数服务器不允许)。表单上传机制，包括透过 HTML 表单上传文件的机制，使用 POST 机制。
另请参阅 get (), post (), deleteResource ()，和 sendCustomRequest ().
这是重载函数。
发送内容为 multiPart 消息到目的地指定通过 request .
这可以被用于通过 HTTP 发送 MIME 多部分消息。
该函数在 Qt 4.8 引入。
另请参阅 QHttpMultiPart , QHttpPart ，和 post ().
这是重载函数。
发送内容为 data 字节数组到目的地指定通过 request .
向服务器发送自定义请求标识通过 URL 的 request .
用户负责发送 verb 给根据 HTTP 规范有效的服务器。
This method provides means to send verbs other than the common ones provided via get () 或 post () etc., for instance sending an HTTP OPTIONS command.
若 data is not empty, the contents of the data device will be uploaded to the server; in that case, data must be open for reading and must remain valid until the finished () 信号被发射为此回复。
注意： 此特征目前只可用于 HTTP(S)。
该函数在 Qt 4.7 引入。
另请参阅 get (), post (), put ()，和 deleteResource ().
将管理器的网络缓存设为 cache 指定。缓存用于由管理器分派的所有请求。
Use this function to set the network cache object to a class that implements additional features, like saving the cookies to permanent storage.
注意： QNetworkAccessManager 拥有所有权对于 cache 对象。
QNetworkAccessManager by default does not have a set cache. Qt provides a simple disk cache, QNetworkDiskCache , which can be used.
该函数在 Qt 4.5 引入。
另请参阅 cache () 和 QNetworkRequest::CacheLoadControl .
Sets the network configuration that will be used when creating the network session to config .
The network configuration is used to create and open a network session before any request that requires network access is process. If no network configuration is explicitly set via this function the network configuration returned by QNetworkConfigurationManager::defaultConfiguration () will be used.
To restore the default network configuration set the network configuration to the value returned from QNetworkConfigurationManager::defaultConfiguration ().
QNetworkConfigurationManager manager; networkAccessManager->setConfiguration(manager.defaultConfiguration());
If an invalid network configuration is set, a network session will not be created. In this case network requests will be processed regardless, but may fail. For example:
networkAccessManager->setConfiguration(QNetworkConfiguration());
该函数在 Qt 4.7 引入。
另请参阅 configuration () 和 QNetworkSession .
将管理器的 Cookie Jar 设为 cookieJar 指定。Cookie Jar 用于由管理器分派的所有请求。
Use this function to set the cookie jar object to a class that implements additional features, like saving the cookies to permanent storage.
注意： QNetworkAccessManager 拥有所有权对于 cookieJar 对象。
若 cookieJar is in the same thread as this QNetworkAccessManager , it will set the parent of the cookieJar so that the cookie jar is deleted when this object is deleted as well. If you want to share cookie jars between different QNetworkAccessManager objects, you may want to set the cookie jar's parent to 0 after calling this function.
QNetworkAccessManager by default does not implement any cookie policy of its own: it accepts all cookies sent by the server, as long as they are well formed and meet the minimum security requirements (cookie domain matches the request's and cookie path matches the request's). In order to implement your own security policy, override the QNetworkCookieJar::cookiesForUrl () 和 QNetworkCookieJar::setCookiesFromUrl () virtual functions. Those functions are called by QNetworkAccessManager when it detects a new cookie.
另请参阅 cookieJar (), QNetworkCookieJar::cookiesForUrl ()，和 QNetworkCookieJar::setCookiesFromUrl ().
将用于未来请求的代理设为 proxy 。这不会影响已经发送的请求。 proxyAuthenticationRequired () 信号会被发射若代理请求身份验证。
A proxy set with this function will be used for all requests issued by QNetworkAccessManager . In some cases, it might be necessary to select different proxies depending on the type of request being sent or the destination host. If that's the case, you should consider using setProxyFactory ().
另请参阅 proxy () 和 proxyAuthenticationRequired ().
将此类的代理工厂设为 factory . A proxy factory is used to determine a more specific list of proxies to be used for a given request, instead of trying to use the same proxy value for all requests.
All queries sent by QNetworkAccessManager will have type QNetworkProxyQuery::UrlRequest .
例如，代理工厂可以应用以下规则：
The lifetime of the object factory will be managed by QNetworkAccessManager 。它会删除对象，当有必要时。
注意： 若指定代理的设置是采用 setProxy ()，工厂将不会被使用。
该函数在 Qt 4.5 引入。
另请参阅 proxyFactory (), setProxy ()，和 QNetworkProxyQuery .
[signal]
void
QNetworkAccessManager::
sslErrors
(
QNetworkReply
*
reply
, const
QList
<
QSslError
> &
errors
)
此信号被发射，若 SSL/TLS 会话在设置期间遇到错误 (包括证书验证错误)。 errors parameter contains the list of errors and reply 是 QNetworkReply that is encountering these errors.
为指示错误不致命，且连接应继续进行， 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). If the user decides to proceed after analyzing the remote certificate, the slot should call ignoreSslErrors().
另请参阅 QSslSocket::sslErrors (), QNetworkReply::sslErrors (), QNetworkReply::sslConfiguration ()，和 QNetworkReply::ignoreSslErrors ().