Класс 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.

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

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

Эта функция была введена в 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() не испускает сигнал об ошибке (QNetworkReply::NetworkError).

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

[protected] void QNetworkReply::setFinished(bool 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().