Класс QWebSocket

Реализует TCP-сокет, работающий по протоколу WebSocket. Подробнее...

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

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

• 31 открытая функция унаследована от QObject

Публичные слоты

• 1 public slot inherited from QObject

Сигналы

• 2 signals inherited from QObject

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

• 1 свойство унаследованное от QObject
• 11 статических публичных членов, унаследованных от QObject
• 9 защищённых функций, унаследованных от QObject

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

Реализует сокет TCP, который работает по протоколу WebSocket.

WebSockets — это веб-технология, предоставляющая двунаправленные каналы связи через одно соединение TCP. Протокол WebSocket был стандартизирован IETF как RFC 6455 в 2011 году. QWebSocket может использоваться как в клиентском, так и в серверном приложении.

Этот класс был разработан на основе QAbstractSocket.

QWebSocket в настоящее время не поддерживает расширения WebSocket и подпротоколы WebSocket.

QWebSocket поддерживает только версию 13 протокола WebSocket, как указано в RFC 6455.

Примечание: Некоторые прокси-серверы не понимают определённые HTTP-заголовки, используемые во время рукопожатия WebSocket. В этом случае небезопасные соединения WebSocket завершаются ошибкой. Лучший способ смягчить эту проблему — использовать WebSocket через защищённое соединение.

Предупреждение: Для генерации масок эта реализация WebSockets использует криптографически небезопасную функцию qrand(). Дополнительную информацию о важности хороших масок см. в документе "Talking to Yourself for Fun and Profit" by Lin-Shung Huang et al. Лучшая мера против атак, упомянутых в документе выше, — использовать QWebSocket через защищённое соединение (wss://). В общем случае всегда будьте осторожны, чтобы у скриптов третьих сторон не было доступа к QWebSocket в вашем приложении.

См. также QAbstractSocket, QTcpSocket и пример клиента QWebSocket.

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

QWebSocket::QWebSocket(const QString &origin = QString(), QWebSocketProtocol::Version version = QWebSocketProtocol::VersionLatest, QObject *parent = Q_NULLPTR)

Создаёт новый QWebSocket с заданным origin, версией протокола и parent.

origin клиента задаётся как указано в RFC 6454. (origin не требуется для клиентов, не являющихся веб-браузерами (см. RFC 6455)). origin не должен содержать символов новой строки, в противном случае соединение будет немедленно прервано на фазе рукопожатия.

Примечание: В настоящее время поддерживается только V13 (RFC 6455)

[virtual] QWebSocket::~QWebSocket()

Удаляет QWebSocket. Закрывает сокет, если он всё ещё открыт, и освобождает все используемые ресурсы.

void QWebSocket::abort()

Прерывает текущий сокет и сбрасывает его. В отличие от close(), эта функция немедленно закрывает сокет, удаляя все ожидающие данные в буфере записи.

[signal] void QWebSocket::aboutToClose()

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

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

[signal] void QWebSocket::binaryFrameReceived(const QByteArray &frame, bool isLastFrame)

Этот сигнал испускается всякий раз, когда принимается бинарная кадр. frame содержит данные, а isLastFrame указывает, является ли это последним кадром полного сообщения.

Этот сигнал можно использовать для обработки больших сообщений по кадрам, вместо ожидания полного сообщения.

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

[signal] void QWebSocket::binaryMessageReceived(const QByteArray &message)

Этот сигнал испускается всякий раз, когда принимается бинарное сообщение. message содержит принятые байты.

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

[signal] void QWebSocket::bytesWritten(qint64 bytes)

Этот сигнал испускается каждый раз, когда блок данных был записан в сокет. Аргумент bytes устанавливается в количество записанных байтов в этом блоке.

Примечание: Этот сигнал имеет одинаковое значение как для защищённых, так и для незащищённых WebSocket. В отличие от QSslSocket, bytesWritten() испускается только тогда, когда зашифрованные данные фактически записываются (см. QSslSocket::encryptedBytesWritten()).

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

[slot] void QWebSocket::close(QWebSocketProtocol::CloseCode closeCode = QWebSocketProtocol::CloseCodeNormal, const QString &reason = QString())

Вежливо закрывает сокет с заданным closeCode и reason.

Все данные в буфере записи сбрасываются перед закрытием сокета. closeCode — это QWebSocketProtocol::CloseCode, указывающий причину закрытия, а reason описывает причину закрытия более подробно.

QWebSocketProtocol::CloseCode QWebSocket::closeCode() const

Возвращает код, указывающий причину закрытия сокета.

См. также QWebSocketProtocol::CloseCode и closeReason().

QString QWebSocket::closeReason() const

Возвращает причину закрытия сокета.

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

[signal] void QWebSocket::connected()

Испускается, когда соединение успешно установлено. Соединение успешно установлено, когда сокет подключен и рукопожатие было успешным.

См. также open() и disconnected().

[signal] void QWebSocket::disconnected()

Испускается, когда сокет отключен.

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

QAbstractSocket::SocketError QWebSocket::error() const

Возвращает тип последней ошибки.

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

[signal] void QWebSocket::error(QAbstractSocket::SocketError error)

Этот сигнал испускается после возникновения ошибки. Параметр error описывает тип ошибки.

QAbstractSocket::SocketError — это не зарегистрированный метатип, поэтому для очередей соединений вам нужно будет зарегистрировать его с помощью Q_DECLARE_METATYPE() и qRegisterMetaType().

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

connect(webSocket, static_cast<void(QWebSocket::*)(QAbstractSocket::SocketError)>(&QWebSocket::error),
    [=](QAbstractSocket::SocketError error){ /* ... */ });

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

QString QWebSocket::errorString() const

Возвращает удобочитаемое описание последней ошибки.

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

bool QWebSocket::flush()

Эта функция записывает как можно больше данных из внутреннего буфера записи в сокет сети ниже, не блокируя. Если какие-либо данные были записаны, эта функция возвращает true; в противном случае возвращается false. Вызовите эту функцию, если вам нужно, чтобы QWebSocket начал отправлять данные буфера немедленно. Количество успешно записанных байтов зависит от операционной системы. В большинстве случаев вам не нужно вызывать эту функцию, поскольку QWebSocket начнёт отправлять данные автоматически, как только управление вернётся в цикл событий.

[slot] void QWebSocket::ignoreSslErrors()

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

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

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

void QWebSocket::ignoreSslErrors(const QList<QSslError> &errors)

Это перегруженный метод.

Этот метод сообщает QWebSocket, что необходимо игнорировать ошибки, перечисленные в errors.

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

QList<QSslCertificate> cert = QSslCertificate::fromPath(QLatin1String("server-certificate.pem"));
QSslError error(QSslError::SelfSignedCertificate, cert.at(0));
QList<QSslError> expectedSslErrors;
expectedSslErrors.append(error);

QWebSocket socket;
socket.ignoreSslErrors(expectedSslErrors);
socket.open(QUrl(QStringLiteral("wss://myserver.at.home")));

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

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

bool QWebSocket::isValid() const

Возвращает true, если сокет готов к чтению и записи; в противном случае возвращает false.

QHostAddress QWebSocket::localAddress() const

Возвращает локальный адрес

quint16 QWebSocket::localPort() const

Возвращает локальный порт

const QMaskGenerator *QWebSocket::maskGenerator() const

Возвращает генератор маски, который в настоящее время используется этим QWebSocket.

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

[slot] void QWebSocket::open(const QUrl &url)

Открывает соединение WebSocket с использованием заданного url.

Если url содержит символы новой строки (\r\n), то сигнал об ошибке будет испущен с QAbstractSocket::ConnectionRefusedError в качестве типа ошибки.

[slot] void QWebSocket::open(const QNetworkRequest &request)

Открывает соединение WebSocket с использованием заданного request.

url запроса будет использоваться для открытия соединения WebSocket. Заголовки, присутствующие в запросе, будут отправлены на сервер в запросе обновления, вместе с необходимыми заголовками для рукопожатия WebSocket.

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

QString QWebSocket::origin() const

Возвращает текущий origin.

QAbstractSocket::PauseModes QWebSocket::pauseMode() const

Возвращает режим паузы для данного сокета

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

QHostAddress QWebSocket::peerAddress() const

Возвращает адрес peer

QString QWebSocket::peerName() const

Возвращает peerName

quint16 QWebSocket::peerPort() const

Возвращает peer порт

[slot] void QWebSocket::ping(const QByteArray &payload = QByteArray())

Отправляет ping на сервер, чтобы указать, что соединение всё ещё активно. Дополнительную payload можно отправить вместе с сообщением ping.

Размер payload не может быть больше 125. Если он больше, payload обрезается до 125 байт.

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

[signal] void QWebSocket::pong(quint64 elapsedTime, const QByteArray &payload)

Издаётся, когда получено сообщение pong в ответ на предыдущий ping. elapsedTime содержит время в миллисекундах, а payload содержит необязательную payload, отправленную с сообщением ping.

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

QNetworkProxy QWebSocket::proxy() const

Возвращает текущий прокси

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

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

Этот сигнал может быть издан, когда используется proxy, требующий аутентификацию. Объект authenticator может быть заполнен необходимыми данными для аутентификации и продолжения подключения.

Примечание: Невозможно использовать QueuedConnection для подключения к этому сигналу, так как подключение завершится неудачей, если authenticator не заполнен новыми данными, когда сигнал возвращается.

См. также QAuthenticator и QNetworkProxy.

qint64 QWebSocket::readBufferSize() const

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

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

[signal] void QWebSocket::readChannelFinished()

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

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

QNetworkRequest QWebSocket::request() const

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

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

QUrl QWebSocket::requestUrl() const

Возвращает URL, к которому сокет подключен или будет подключен.

QString QWebSocket::resourceName() const

Возвращает имя ресурса, к которому в настоящее время осуществляется доступ.

void QWebSocket::resume()

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

См. также pauseMode() и setPauseMode().

qint64 QWebSocket::sendBinaryMessage(const QByteArray &data)

Отправляет данные data по сокету как двоичное сообщение и возвращает количество фактически отправленных байт.

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

qint64 QWebSocket::sendTextMessage(const QString &message)

Отправляет заданное message по сокету как текстовое сообщение и возвращает количество фактически отправленных байт.

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

void QWebSocket::setMaskGenerator(const QMaskGenerator *maskGenerator)

Устанавливает генератор для создания масок в maskGenerator. Генератор QWebSocket по умолчанию может быть сброшен путём передачи Q_NULLPTR. Генератор маски можно изменить в любое время, даже во время открытого соединения.

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

void QWebSocket::setPauseMode(QAbstractSocket::PauseModes pauseMode)

Управляет приостановкой при получении уведомления. Параметр pauseMode определяет условия, при которых сокет должен быть приостановлен.

В настоящее время поддерживается только уведомление sslErrors(). Если установлено PauseOnSslErrors, передача данных по сокету будет приостановлена и должна быть включена явно снова, вызвав resume(). По умолчанию этот параметр установлен в PauseNever. Этот параметр должен быть вызван до подключения к серверу, иначе это приведёт к неопределённому поведению.

См. также pauseMode() и resume().

void QWebSocket::setProxy(const QNetworkProxy &networkProxy)

Устанавливает прокси на networkProxy

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

void QWebSocket::setReadBufferSize(qint64 size)

Устанавливает размер внутреннего буфера чтения QWebSocket в size байт.

Если размер буфера ограничен определённым значением, QWebSocket не будет буферизировать более этого объёма данных. В исключительных случаях, размер буфера 0 означает, что буфер чтения не ограничен, и все входящие данные буферизуются. Это значение по умолчанию. Этот параметр полезен, если вы читаете данные только в определённые моменты времени (например, в приложении для потоковой передачи в реальном времени) или если вы хотите защитить свой сокет от получения слишком большого объёма данных, что может в конечном итоге привести к недостатку памяти в вашем приложении.

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

void QWebSocket::setSslConfiguration(const QSslConfiguration &sslConfiguration)

Устанавливает конфигурацию SSL сокета на содержимое sslConfiguration.

Эта функция устанавливает локальный сертификат, шифры, закрытый ключ и сертификаты CA на значения, хранящиеся в sslConfiguration. Невозможно установить поля, связанные со состоянием SSL.

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

QSslConfiguration QWebSocket::sslConfiguration() const

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

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

[signal] void QWebSocket::sslErrors(const QList<QSslError> &errors)

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

errors содержит одну или несколько ошибок, которые препятствуют QWebSocket в проверке идентичности партнёра.

Примечание: Вы не можете использовать Qt::QueuedConnection при подключении к этому сигналу, в противном случае вызов QWebSocket::ignoreSslErrors() не будет иметь никакого эффекта.

QAbstractSocket::SocketState QWebSocket::state() const

Возвращает текущее состояние сокета.

[signal] void QWebSocket::stateChanged(QAbstractSocket::SocketState state)

Этот сигнал излучается всякий раз, когда состояние QWebSocket изменяется. Параметр state — это новое состояние.

Примечание: QAbstractSocket::ConnectedState излучается после успешного завершения рукопожатия с сервером.

QAbstractSocket::SocketState — это не зарегистрированный метатип, поэтому для очередей соединений вам нужно зарегистрировать его с помощью Q_REGISTER_METATYPE() и qRegisterMetaType().

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

[signal] void QWebSocket::textFrameReceived(const QString &frame, bool isLastFrame)

Этот сигнал излучается всякий раз, когда принимается текстовая кадр. frame содержит данные, а isLastFrame указывает, является ли этот кадр последним в полном сообщении.

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

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

[signal] void QWebSocket::textMessageReceived(const QString &message)

Этот сигнал излучается всякий раз, когда принимается текстовое сообщение. message содержит принятое текстовое сообщение.

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

QWebSocketProtocol::Version QWebSocket::version() const

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