Класс QWebSocket

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

Этот класс был представлен в Qt 5.3.

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

Общедоступные функции

Открытые слоты

Сигналы

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

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

Этот класс был разработан по образцу QAbstractSocket.

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

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

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

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

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

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

[signal] void QWebSocket::QWebSocket(const QString &origin = QString(), QWebSocketProtocol::Version version = QWebSocketProtocol::VersionLatest, QObject *parent = nullptr)

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

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

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

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

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

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

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

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

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

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

Любые данные в буфере записи сбрасываются перед закрытием сокета. closeCode — это QWebSocketProtocol::CloseCode, указывающий причину закрытия, а reason более подробно описывает причину закрытия. Все управляющие кадры, включая кадр Close, ограничены 125 байтами. Поскольку для closeCode используются два из них, максимальная длина reason составляет 123! Если reason превышает этот лимит, он будет усечён.

[signal] void QWebSocket::connected()

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

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

[signal] void QWebSocket::disconnected()

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

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

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

void QWebSocket::error(QAbstractSocket::SocketError error)

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

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

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

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

[slot] void QWebSocket::ignoreSslErrors()

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

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

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

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

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

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

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

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

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

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

[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 содержит необязательную полезную нагрузку, отправленную с запросом ping.

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

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

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

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

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

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

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

См. также QSslPreSharedKeyAuthenticator и QSslSocket::preSharedKeyAuthenticationRequired().

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

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

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

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

[signal] void QWebSocket::readChannelFinished()

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

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

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

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

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

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

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

[override virtual] QWebSocket::~QWebSocket()

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

void QWebSocket::abort()

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

qint64 QWebSocket::bytesToWrite() const

Возвращает количество байтов, ожидающих записи. Байты записываются при возвращении управления в цикл событий или при вызове flush().

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

См. также flush.

QWebSocketProtocol::CloseCode QWebSocket::closeCode() const

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

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

QString QWebSocket::closeReason() const

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

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

QAbstractSocket::SocketError QWebSocket::error() const

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

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

QString QWebSocket::errorString() const

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

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

bool QWebSocket::flush()

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

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

QString QWebSocket::origin() const

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

QAbstractSocket::PauseModes QWebSocket::pauseMode() const

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

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

QHostAddress QWebSocket::peerAddress() const

Возвращает адрес удалённого узла

QString QWebSocket::peerName() const

Возвращает peerName

quint16 QWebSocket::peerPort() const

Возвращает порт удалённого узла

QNetworkProxy QWebSocket::proxy() const

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

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

qint64 QWebSocket::readBufferSize() const

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

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

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 можно сбросить, передав 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().

QAbstractSocket::SocketState QWebSocket::state() const

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

QWebSocketProtocol::Version QWebSocket::version() const

Возвращает используемую версию сокета.