Описание класса QNetworkAccessManager
[Модуль QtNetwork]

Класс QNetworkAccessManager позволяет приложению отправлять сетевые запросы и получать ответы.

#include <QNetworkAccessManager>

Этот класс не является частью Выпуска GUI Framework Qt.

Унаследован от QObject .

Замечание: Все функции в этом классе реентерабельны .

Этот класс был введён в Qt 4.4.

• Список всех членов, включая унаследованные

---

Открытые типы

enum	Operation { HeadOperation, GetOperation, PutOperation, PostOperation, DeleteOperation }

---

Открытые функции

	QNetworkAccessManager ( QObject * parent = 0 )
	~QNetworkAccessManager ()
QAbstractNetworkCache *	cache () const
QNetworkCookieJar *	cookieJar () const
QNetworkReply *	deleteResource ( const QNetworkRequest & request )
QNetworkReply *	get ( const QNetworkRequest & request )
QNetworkReply *	head ( const QNetworkRequest & request )
QNetworkReply *	post ( const QNetworkRequest & request, QIODevice * data )
QNetworkReply *	post ( const QNetworkRequest & request, const QByteArray & data )
QNetworkProxy	proxy () const
QNetworkProxyFactory *	proxyFactory () const
QNetworkReply *	put ( const QNetworkRequest & request, QIODevice * data )
QNetworkReply *	put ( const QNetworkRequest & request, const QByteArray & data )
void	setCache ( QAbstractNetworkCache * cache )
void	setCookieJar ( QNetworkCookieJar * cookieJar )
void	setProxy ( const QNetworkProxy & proxy )
void	setProxyFactory ( QNetworkProxyFactory * factory )

• 29 открытых функций, унаследованных от QObject

---

Сигналы

void	authenticationRequired ( QNetworkReply * reply, QAuthenticator * authenticator )
void	finished ( QNetworkReply * reply )
void	proxyAuthenticationRequired ( const QNetworkProxy & proxy, QAuthenticator * authenticator )
void	sslErrors ( QNetworkReply * reply, const QList<QSslError> & errors )

• 1 сигнал, унаследованный от QObject

---

Защищенные функции

virtual QNetworkReply *

createRequest ( Operation op, const QNetworkRequest & req, QIODevice * outgoingData = 0 )

• 7 защищенных функций, унаследованных от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 5 статических открытых членов, унаследованных от QObject

---

Подробное описание

Класс QNetworkAccessManager позволяет приложению отправлять сетевые запросы и получать ответы.

API сетевого доступа создано вокруг объекта QNetworkAccessManager, который содержит общую конфигурацию и настройки для посылаемых запросов. Он содержит прокси и кэш, а также сигналы, связанные с ними, и сигналы ответов, которые могут быть использованы для контроля за прогрессом сетевой операции. Одного объекта QNetworkAccessManager будет достаточно для всего приложения Qt.

После создания объекта QNetworkAccessManager, приложение может посылать запросы по сети. Поставляется группа стандартных функций, которые принимают запрос и необязательные данные, и каждая возвращает объект QNetworkReply . Возвращаемый объект используется для получения любых данных, возвращаемых в ответ на соответствующий запрос.

Простое скачивание из сети может быть выполнено следующим способом:

QNetworkAccessManager *manager = new QNetworkAccessManager(this);

connect(manager, SIGNAL(finished(QNetworkReply*)),

this, SLOT(replyFinished(QNetworkReply*)));

manager->get(QNetworkRequest(QUrl("http://qt.nokia.com")));

QNetworkAccessManager имеет асинхронный API. Когда слот replyFinished будет вызван, то принимаемый им параметр будет объект QNetworkReply , содержащий скачанные данные и метаданные (заголовки и т.д.).

Замечание: После завершения запроса, пользователь отвечает за удаление объекта QNetworkReply в должное время. Не удаляйте его непосредственно в слоте, соединенном с finished (). Вы можете использовать функцию deleteLater ().

Замечание: QNetworkAccessManager ставит в очередь запросы получателям. Количество запросов, выполняемых параллельно, зависит от протокола. В настоящее время для протокола HTTP на настольных платформах параллельно выполняются 6 запросов для одной комбинации узел/порт.

Более сложный пример, подразумевающий что диспетчер уже создан, будет следующий:

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

Требования платформы Symbian к безопасности

В Symbian процессы, использующие этот класс, должны иметь мандат безопасности платформы NetworkServices. Если клиентский процесс не имеет такой возможности, то операции приведут к панике.

Возможности безопасности платформы добавляются через переменную TARGET.CAPABILITY qmake.

Смотрите также QNetworkRequest , QNetworkReply и QNetworkProxy .

---

Описание типов-членов

enum QNetworkAccessManager::Operation

Указывает операцию, обрабатывающую этот ответ.

Константа	Значение	Описание
QNetworkAccessManager::HeadOperation	1	операция получения заголовков (создаётся с head ())
QNetworkAccessManager::GetOperation	2	получение заголовков и скачанного содержимого (создаётся с get ())
QNetworkAccessManager::PutOperation	3	операция отправления содержимого (создаётся с put ())
QNetworkAccessManager::PostOperation	4	отправка содержимого формы HTML для обработки через HTTP POST (создаётся с помощью post ())
QNetworkAccessManager::DeleteOperation	5	удаляет содержимое операции (созданное с помощью deleteResource ())

Смотрите также QNetworkReply::operation ().

---

Описание функций-членов

QNetworkAccessManager::QNetworkAccessManager ( QObject * parent = 0 )

Создаёт объект QNetworkAccessManager , который является центром API сетевого доступа и устанавливает parent в качестве родителя.

QNetworkAccessManager::~QNetworkAccessManager ()

Уничтожает объект QNetworkAccessManager и освобождает все ресурсы. Заметьте, что объекты QNetworkReply , возвращаемые из этого класса, являются его потомками, что означает что они будут они удалены вместе с ним если вы не вызовите для них QObject::setParent ().

void QNetworkAccessManager::authenticationRequired ( QNetworkReply * reply, QAuthenticator * authenticator )   [signal]

Этот сигнал вырабатывается в любое время, когда конечный сервер запросит аутентификацию перед доставкой запрошенного содержимого. Слот, соединённый с этим сигналом, должен заполнять аутентификационную информацию для содержимого (которые могут быть определены просмотром объекта reply) в объекте authenticator.

QNetworkAccessManager кэширует эту информацию и будет посылать те же данные если сервер запросит аутентификацию снова без вырабатывания сигнала authenticationRequired(). Если сервер отклонит эти данные, этот сигнал будет выработан снова.

Смотрите также proxyAuthenticationRequired ().

Q AbstractNetworkCache * QNetworkAccessManager::cache () const

Возвращает кэш, который использовался для сохранения данных, полученных из сети.

Эта функция была введена в Qt 4.5.

Смотрите также setCache ().

Q NetworkCookieJar * QNetworkAccessManager::cookieJar () const

Возвращает QNetworkCookieJar , который используется для хранения куков, полученных из сети, а также куков, которые готовы к отправке.

Смотрите также setCookieJar ().

Q NetworkReply * QNetworkAccessManager::createRequest ( Operation op, const QNetworkRequest & req, QIODevice * outgoingData = 0 )   [virtual protected]

Возвращает новый объект QNetworkReply для управления операцией op и запросом req. Устройство outgoingData всегда равно 0 для запросов Get и Head, а переданное значение в операции post () и put () (переменные QByteArray передадутся как объект QBuffer ).

Реализация по умолчанию вызывает QNetworkCookieJar::cookiesForUrl () для архива куки, установленного в setCookieJar (), чтобы получить куки, готовые к отправке на удалённый сервер.

Возвращаемый объект должен быть в открытом состоянии.

Q NetworkReply * QNetworkAccessManager::deleteResource ( const QNetworkRequest & request )

Посылает запрос на удаление ресурса, идентифицируемого по URL запроса request.

Замечание: Эта возможность в настоящее время доступна только для HTTP, выполняя запрос HTTP DELETE.

Эта функция была введена в Qt 4.6.

Смотрите также get (), post () и put ().

void QNetworkAccessManager::finished ( QNetworkReply * reply )   [signal]

Этот сигнал вырабатывается когда ожидаемый сетевой ответ завершается. Параметр reply будет содержать указатель на ответ, который только что завершился. Этот сигнал вырабатывается вместе с сигналом QNetworkReply::finished ().

Для получения подробной информации о статусе, в котором будет объект, смотрите QNetworkReply::finished ().

Замечание: Не удаляйте объект reply в слоте, соединенным с этим сигналом. Используйте deleteLater ().

Смотрите также QNetworkReply::finished () и QNetworkReply::error ().

Q NetworkReply * QNetworkAccessManager::get ( const QNetworkRequest & request )

Отправляет запрос для получения содержимого приёмника request и возвращает новый объект QNetworkReply , открытый для чтения, который испускает сигнал readyRead() когда были получены новые данные.

Будет скачано содержимое, а также связанные заголовки.

Смотрите также post (), put () и deleteResource ().

Q NetworkReply * QNetworkAccessManager::head ( const QNetworkRequest & request )

Отправляет запрос для получения сетевых заголовков для request и возвращает новый объект QNetworkReply , который будет содержать такие заголовки.

Функция получает своё имя после связанного запроса HTTP (HEAD).

Q NetworkReply * QNetworkAccessManager::post ( const QNetworkRequest & request, QIODevice * data )

Отправляет запрос HTTP POST получателю, указанному в request, и возвращает новый объект QNetworkReply , открытый для чтения, содержащий отправленный сервером ответ. Содержимое устройства data будет закачено на сервер.

data должны быть открыты для чтения и должны оставаться достоверными пока сигнал finished () испускается для этого ответа.

Замечание: Отправка запроса POST для протоколов за исключением HTTP и HTTPS не определено и скорее всего не закончится неудачей.

Смотрите также get (), put () и deleteResource ().

Q NetworkReply * QNetworkAccessManager::post ( const QNetworkRequest & request, const QByteArray & data )

Это перегруженная функция.

Посылает содержимое байтового массива data получателю, указанному в request.

Q NetworkProxy QNetworkAccessManager::proxy () const

Возвращает QNetworkProxy , который будут использовать посылаемые запросы, использующие объект QNetworkAccessManager . Значение по умолчанию для прокси равно QNetworkProxy::DefaultProxy .

Смотрите также setProxy (), setProxyFactory () и proxyAuthenticationRequired ().

void QNetworkAccessManager::proxyAuthenticationRequired ( const QNetworkProxy & proxy, QAuthenticator * authenticator )   [signal]

Этот сигнал вырабатывается когда прокси требует аутентификацию и QNetworkAccessManager не может найти годную кэшированную информацию. Слот, соединённый с этим сигналом, должен заполнять аутентификационную информацию для прокси proxy в объекте authenticator.

QNetworkAccessManager будет кэшировать эту информацию. В следующий раз, когда прокси запросит аутентификацию, QNetworkAccessManager будет автоматически посылать те же данные без повторного вырабатывания сигнала proxyAuthenticationRequired.

Если прокси отклонит эти данные, то QNetworkAccessManager выработает этот сигнал снова.

Смотрите также proxy (), setProxy () и authenticationRequired ().

Q NetworkProxyFactory * QNetworkAccessManager::proxyFactory () const

Возвращает фабрику-прокси, которую данный объект QNetworkAccessManager использует для установки прокси используемые для запросов.

Обратите внимание на то, что указатель, возвращённый этой функцией, управляется QNetworkAccessManager и может быть удалён в любое время.

Эта функция была введена в Qt 4.5.

Смотрите также setProxyFactory () и proxy ().

Q NetworkReply * QNetworkAccessManager::put ( const QNetworkRequest & request, QIODevice * data )

Закачивает содержимое data получателю request и возвращает новый объект QNetworkReply , который будет открыт для ответа.

data должно быть открыто для чтения при вызове этой функции и должно оставаться годным до вырабатывания сигнала finished () этого запроса.

Будет ли всё доступно для чтения из возвращённого объекта зависит от протокола. Для HTTP, сервер может послать маленькую страничку в HTML, указывая что загрузка была успешной (или нет). Другие протоколы вероятно будут содержать данные в своих ответах.

Замечание: Для HTTP, этот запрос отправит запрос PUT, что большинство серверов не разрешают. Механизмы загрузки форм, включая загружаемые через HTML формы файлы, использует механизм POST.

Смотрите также get () и post ().

Q NetworkReply * QNetworkAccessManager::put ( const QNetworkRequest & request, const QByteArray & data )

Это перегруженная функция.

Посылает содержимое байтового массива data получателю, указанному в request.

void QNetworkAccessManager::setCache ( QAbstractNetworkCache * cache )

Устанавливает сетевым кэшем менеджера указанный cache. Кэш используется для всех запросов, отправляемых менджером.

Используйте эту функцию для установки объекта сетевого кэша классу, который реализует дополнительные средства, подобные сохранению файлов-куков (cookies) для постоянного хранения.

Замечание: QNetworkAccessManager становится владельцем объекта cache.

По умолчанию у QNetworkAccessManager нет набора кэша. Qt предоставляет простой дисковый кэш, QNetworkDiskCache , который можно использовать.

Эта функция была введена в Qt 4.5.

Смотрите также cache () и QNetworkRequest::CacheLoadControl .

void QNetworkAccessManager::setCookieJar ( QNetworkCookieJar * cookieJar )

Устанавливает архив куков (cookie jar) менеджера, указанный в cookieJar. Архив куков используется всеми запросами, отправляемыми менеджером.

Используйте эту функцию для установки объекта архива куков классу, который реализует дополнительные средства, такие как сохранение куков в постоянном хранилище.

Замечание: QNetworkAccessManager становится владельцем объекта cookieJar.

QNetworkAccessManager установит переданному ему cookieJar родителя, поэтому этот архив куков удаляется, когда удаляется этот объект. Если вы хотите разделить архивы куков между разными объектами QNetworkAccessManager , вы можете захотеть установить родителя архива куков равным 0 после вызывания этой функции.

QNetworkAccessManager по умолчанию сам не реализует ни какую политику куков: он принимает все куки, посланные сервером, пока они правильно сформированы и отвечают минимальным требованиям безопасности (домен куки и путь совпадают домену и пути запроса). Чтобы реализовать вашу собственную политику безопасности, переопределите виртуальные функции QNetworkCookieJar::cookiesForUrl () и QNetworkCookieJar::setCookiesFromUrl (). Эти функции вызываются QNetworkAccessManager когда он определяет новую куку.

Смотрите также cookieJar (), QNetworkCookieJar::cookiesForUrl () и QNetworkCookieJar::setCookiesFromUrl ().

void QNetworkAccessManager::setProxy ( const QNetworkProxy & proxy )

Устанавливает прокси, которая будет использована в последующих запросах, равной proxy. Это не влияет на запросы, которые уже были отосланы. Сигнал proxyAuthenticationRequired () будет выработан если прокси требует аутентификацию.

Устанавливаемый с помощью этой функции прокси будет использоваться для всех запросов отправляемых QNetworkAccessManager 'ом. В некоторых случаях это может быть необходимо для выбора разных прокси, в зависимости от типа отправляемого запроса или узла получателя. Если это происходит, вы должны подумать об использовании setProxyFactory ().

Смотрите также proxy () и proxyAuthenticationRequired ().

void QNetworkAccessManager::setProxyFactory ( QNetworkProxyFactory * factory )

Устанавливает фабрику прокси для данного класса равной factory. Фабрика прокси используется для определения более специфичного списка прокси для использования с заданным запросом, вместо попыток использования одного и того же значения прокси для всех запросов.

Все запросы отправляются QNetworkAccessManager 'ом будет иметь тип QNetworkProxyQuery::UrlRequest .

Например, фабрика прокси может применять следующие правила:

• если адрес получателя находится в локальной сети (например, если имя узла не содержит точек или если его IP-адрес находится в диапазоне адресов организации), то возвращает QNetworkProxy::NoProxy
• если запрос FTP, возвращается FTP-прокси
• если запрос HTTP или HTTPS, тогда возвращается HTTP-прокси
• в остальных случаях возвращается SOCKSv5 прокси-сервер

Временем жизни объекта factory управляет QNetworkAccessManager . Он удалит объект когда будет необходимо.

Замечание: Если указанный прокси установлен с помощью setProxy (), то фабрика не будет использоваться.

Эта функция была введена в Qt 4.5.

Смотрите также proxyFactory (), setProxy () и QNetworkProxyQuery .

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

Этот сигнал вырабатывается если сессия SSL/TLS сталкивается с ошибкой в момент установки, включая ошибки проверки сертификатов. Параметр errors содержит список ошибок и reply это QNetworkReply , который столкнулся с этими ошибками.

Для указания того, что эти ошибки не фатальны и что соединение должно быть продолжено, функция QNetworkReply::ignoreSslErrors () должна быть вызвана из слота, соединённого с сигналом. Если она не будет вызвана, сессия SSL будет сброшена перед любым обменом данных (включая URL).

Этот сигнал может быть использован для отображения сообщения об ошибке пользователю, указывая что безопасность может быть скомпрометирована и отобразить настройки SSL (для её получения смотрите sslConfiguration()). Если пользователь решает продолжить после анализа сертификата удалённой стороны, слот должен вызвать ignoreSslErrors().

Смотрите также QSslSocket::sslErrors (), QNetworkReply::sslErrors (), QNetworkReply::sslConfiguration (), and QNetworkReply::ignoreSslErrors ().