Класс QNetworkReply

Класс QNetworkReply содержит данные и заголовки для запроса, отправленного с помощью QNetworkAccessManager. Подробнее...

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

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

Примечание: Все функции в этом классе являются повторно входящими.

Типы публичного доступа

Функции публичного доступа

Переопределённые функции публичного доступа

Слот публичного доступа

Сигналы

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

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

Класс QNetworkReply содержит данные и метаданные, относящиеся к запросу, опубликованному с помощью QNetworkAccessManager. Как и QNetworkRequest, он содержит URL и заголовки (как в обработанном, так и в сыром виде), некоторую информацию о состоянии ответа и содержимое самого ответа.

QNetworkReply является последовательным устройством доступа QIODevice, что означает, что после чтения данных из объекта они больше не хранятся в устройстве. Поэтому ответственность за сохранение этих данных лежит на приложении, если это необходимо. Всякий раз, когда новые данные принимаются и обрабатываются из сети, посылается сигнал readyRead().

Сигнал downloadProgress() также посылается при получении данных, но количество байтов в нём может не соответствовать фактически полученным байтам, если над содержимым выполняются какие-либо преобразования (например, распаковка и удаление накладных расходов протокола).

Несмотря на то, что QNetworkReply — это устройство QIODevice, связанное с содержимым ответа, оно также посылает сигнал uploadProgress(), который указывает на прогресс загрузки для операций, имеющих такое содержимое.

Примечание: Не удаляйте объект в слоте, подключённом к сигналу error() или finished(). Используйте deleteLater().

См. также QNetworkRequest и QNetworkAccessManager.

Документация по типам членов

enum QNetworkReply::NetworkError

Указывает все возможные условия ошибок, обнаруженные во время обработки запроса.

Примечание: Когда протокол HTTP возвращает переадресацию, ошибка не будет сообщена. Вы можете проверить, есть ли переадресация, с помощью атрибута QNetworkRequest::RedirectionTargetAttribute.

См. также error().

typedef QNetworkReply::RawHeaderPair

RawHeaderPair — это QPair<QByteArray, QByteArray>, где первая QByteArray — имя заголовка, а вторая — значение заголовка.

Документация по функциям-членам

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

Создаёт объект QNetworkReply с родителем parent.

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

[pure virtual slot] void QNetworkReply::abort()

Немедленно прерывает операцию и закрывает любые ещё открытые сетевые соединения. Также прерываются загрузки, которые ещё выполняются.

Также будет послан сигнал finished().

См. также close() и finished().

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

Этот сигнал излучается, чтобы указать прогресс загрузки части этого сетевого запроса, если таковой имеется. Если к этому запросу не привязана загрузка, этот сигнал будет излучен один раз со значением 0 как для bytesReceived, так и для bytesTotal.

Параметр bytesReceived указывает количество полученных байтов, а bytesTotal — общее количество ожидаемых к загрузке байтов. Если количество байтов для загрузки неизвестно, bytesTotal будет равно -1.

Загрузка завершается, когда bytesReceived равно bytesTotal. В это время bytesTotal не будет равен -1.

Обратите внимание, что значения bytesReceived и bytesTotal могут отличаться от size(), общего количества байтов, полученных через read() или readAll(), или значения заголовка (ContentLengthHeader). Причина в том, что во время загрузки может быть дополнительная накладная протокола или данные могут быть сжаты.

См. также uploadProgress() и bytesAvailable().

[signal] void QNetworkReply::encrypted()

Этот сигнал излучается, когда сессия SSL/TLS успешно завершила начальный обмен. На этом этапе никакие пользовательские данные не были переданы. Сигнал можно использовать для выполнения дополнительных проверок цепочки сертификатов, например, для уведомления пользователей, когда сертификат веб-сайта изменился. Если ответ не соответствует ожидаемым критериям, необходимо прервать его, вызвав QNetworkReply::abort() из слота, подключенного к этому сигналу. Конфигурацию SSL, используемую в данный момент, можно проверить с помощью метода QNetworkReply::sslConfiguration().

Внутренне QNetworkAccessManager может открыть несколько подключений к серверу, чтобы позволить обработку запросов параллельно. Эти подключения могут быть повторно использованы, что означает, что сигнал encrypted() не будет излучен. Это означает, что вы гарантированно получите этот сигнал только для первого подключения к сайту за время существования QNetworkAccessManager.

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

См. также QSslSocket::encrypted() и QNetworkAccessManager::encrypted().

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

Этот сигнал излучается, когда ответ обнаруживает ошибку при обработке. Скорее всего, последует сигнал finished(), указывающий на завершение соединения.

Параметр code содержит код обнаруженной ошибки. Используйте errorString(), чтобы получить текстовое представление условия ошибки.

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

Примечание: Сигнал error перегружен в этом классе. Для подключения к этому сигналу с использованием синтаксиса указателя функции Qt предоставляет удобную вспомогательную функцию для получения указателя функции, как показано в этом примере:

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

См. также error() и errorString().

[signal] void QNetworkReply::finished()

Этот сигнал излучается, когда ответ завершил обработку. После излучения этого сигнала больше не будет обновлений данных или метаданных ответа.

Если не были вызваны close() или abort(), ответ по-прежнему будет открыт для чтения, так что данные могут быть получены вызовами read() или readAll(). В частности, если не было произведено никаких вызовов read() в результате readyRead(), вызов readAll() вернёт полное содержимое в QByteArray.

Этот сигнал излучается совместно с QNetworkAccessManager::finished(), где параметр reply этого сигнала — это данный объект.

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

Вы также можете использовать isFinished() для проверки, завершил ли QNetworkReply работу, даже прежде, чем вы получите сигнал finished().

См. также setFinished(), QNetworkAccessManager::finished() и isFinished().

[virtual slot] void QNetworkReply::ignoreSslErrors()

Если эта функция вызвана, ошибки SSL, связанные с сетевым соединением, будут проигнорированы, включая ошибки проверки сертификатов.

Предупреждение: Убедитесь, что пользователь всегда может проверить ошибки, сообщённые сигналом sslErrors(), и вызывайте этот метод только после подтверждения пользователем, что продолжение работы допустимо. При возникновении непредвиденных ошибок следует прервать ответ. Вызов этого метода без проверки фактических ошибок, скорее всего, создаст угрозу безопасности для вашего приложения. Используйте его с большой осторожностью!

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

Примечание: Если HTTP Strict Transport Security включён для QNetworkAccessManager, эта функция не имеет эффекта.

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

[signal] void QNetworkReply::metaDataChanged()

Этот сигнал излучается всякий раз, когда меняются метаданные в этом ответе. Метаданные — это любая информация, которая не является самим содержимым (данными), включая сетевые заголовки. В большинстве случаев метаданные будут полностью известны к тому моменту, когда будет получен первый байт данных. Однако возможно получать обновления заголовков или других метаданных во время обработки данных.

См. также header(), rawHeaderList(), rawHeader() и hasRawHeader().

[signal] void QNetworkReply::preSharedKeyAuthenticationRequired(QSslPreSharedKeyAuthenticator *authenticator)

Этот сигнал излучается, если обмен SSL/TLS согласовал криптографический пакет PSK и впоследствии требуется аутентификация PSK.

При использовании PSK клиент должен отправить серверу действительный идентификатор и действительный предварительно согласованный ключ, чтобы продолжить обмен SSL. Приложения могут предоставить эту информацию в слоте, подключённом к этому сигналу, заполнив переданный объект authenticator в соответствии со своими потребностями.

Примечание: Игнорирование этого сигнала или невозможность предоставить необходимые учетные данные приведет к провалу рукопожатия и, следовательно, к прерыванию соединения.

Примечание: Объект authenticator принадлежит ответу и не должен удаляться приложением.

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

См. также QSslPreSharedKeyAuthenticator.

[signal] void QNetworkReply::redirectAllowed()

Когда клиентский код, обрабатывающий сигнал redirected(), проверил новый URL, он излучает этот сигнал, чтобы разрешить переадресацию. Этот протокол применяется к сетевым запросам, политика переадресации которых установлена в QNetworkRequest::UserVerifiedRedirectPolicy

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

См. также QNetworkRequest::UserVerifiedRedirectPolicy, QNetworkAccessManager::setRedirectPolicy() и QNetworkRequest::RedirectPolicyAttribute.

[signal] void QNetworkReply::redirected(const QUrl &url)

Этот сигнал излучается, если в запросе был установлен атрибут QNetworkRequest::FollowRedirectsAttribute, и сервер ответил кодом состояния 3xx (в частности, 301, 302, 303, 305, 307 или 308) с действительным URL в заголовке location, что указывает на переадресацию HTTP. Параметр url содержит новый URL переадресации, возвращённый сервером в заголовке location.

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

См. также QNetworkRequest::FollowRedirectsAttribute.

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

[virtual] QNetworkReply::~QNetworkReply()

Удаляет этот ответ и освобождает все связанные с ним ресурсы. Если какие-либо сетевые подключения все еще открыты, они будут закрыты.

См. также abort() и close().

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

QNetworkReply::NetworkError QNetworkReply::error() const

Возвращает ошибку, которая была обнаружена во время обработки этого запроса. Если ошибка не была обнаружена, возвращает NoError.

См. также setError().

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

Возвращает true, если сырой заголовок с именем headerName был отправлен удаленным сервером.

См. также rawHeader().

QVariant QNetworkReply::header(QNetworkRequest::KnownHeaders header) const

Возвращает значение известного заголовка header, если этот заголовок был отправлен удаленным сервером. Если заголовок не был отправлен, возвращается недействительный QVariant.

См. также rawHeader(), setHeader() и QNetworkRequest::header().

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.

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

Примечание: Если для QNetworkAccessManager включена HTTP Strict Transport Security, эта функция не имеет эффекта.

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

См. также sslConfiguration(), sslErrors(), QSslSocket::ignoreSslErrors() и QNetworkAccessManager::setStrictTransportSecurityEnabled().

[virtual protected] void QNetworkReply::ignoreSslErrorsImplementation(const QList<QSslError> &errors)

Этот виртуальный метод предоставляется для возможности переопределения поведения ignoreSslErrors(). ignoreSslErrors() — это общедоступный оберточный метод для этого метода. errors содержит ошибки, которые пользователь хочет проигнорировать.

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

См. также ignoreSslErrors().

bool QNetworkReply::isFinished() const

Возвращает true, когда ответ завершился или был прерван.

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

См. также isRunning().

bool QNetworkReply::isRunning() const

Возвращает true, когда запрос всё ещё обрабатывается, и ответ ещё не завершился или не был прерван.

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

См. также isFinished().

QNetworkAccessManager *QNetworkReply::manager() const

Возвращает QNetworkAccessManager, который использовался для создания объекта QNetworkReply. Изначально это также родительский объект.

QNetworkAccessManager::Operation QNetworkReply::operation() const

Возвращает операцию, которая была отправлена для этого ответа.

См. также setOperation().

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

Возвращает исходное содержимое заголовка headerName, отправленное удалённым сервером. Если такого заголовка нет, возвращает пустой массив байтов, который может быть неотличим от пустого заголовка. Используйте hasRawHeader(), чтобы проверить, отправил ли сервер такое поле заголовка.

См. также setRawHeader(), hasRawHeader() и header().

QList<QByteArray> QNetworkReply::rawHeaderList() const

Возвращает список полей заголовков, отправленных удалённым сервером в порядке их отправки. Повторяющиеся заголовки объединяются и занимают место последнего дубликата.

const QList<QNetworkReply::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, атрибут будет сброшен.

См. также attribute() и QNetworkRequest::setAttribute().

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

Устанавливает состояние ошибки на errorCode. Читабельное сообщение устанавливается с помощью errorString.

Вызов setError() не испускает сигнал 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(), setRawHeader() и QNetworkRequest::setHeader().

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

Данная функция была введена в Qt 5.0.

См. также sslConfigurationImplementation() и setSslConfiguration().

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

Устанавливает URL, обрабатываемый, на url. Обычно URL соответствует URL запроса, который был отправлен, но по разным причинам он может отличаться (например, путь к файлу, преобразованный в абсолютный или канонический).

См. также url(), request() и QNetworkRequest::url().

QSslConfiguration QNetworkReply::sslConfiguration() const

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

Сертификат узла и его цепочка сертификатов будут известны к тому времени, когда будет отправлено событие sslErrors(), если оно будет отправлено.

См. также setSslConfiguration().

[virtual protected] void QNetworkReply::sslConfigurationImplementation(QSslConfiguration &configuration) const

Этот виртуальный метод предоставлен для возможности переопределения поведения метода sslConfiguration(). sslConfiguration() — это общедоступная обертка для этого метода. Конфигурация будет возвращена в configuration.

Данная функция была введена в Qt 5.0.

См. также setSslConfigurationImplementation() и sslConfiguration().

QUrl QNetworkReply::url() const

Возвращает URL загружаемого или отправляемого содержимого. Обратите внимание, что URL может отличаться от URL исходного запроса. Если в запросе был установлен атрибут QNetworkRequest::FollowRedirectsAttribute, то этот метод возвращает текущий URL, к которому обращается API сети, т.е. URL, который отправляется в сигнале QNetworkReply::redirected.

См. также request(), setUrl(), QNetworkRequest::url() и redirected().