Класс QWebSocket

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

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

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

Публичные функции

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

Сигналы

Статические публичные члены

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

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

Этот класс был смоделирован по QAbstractSocket.

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

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

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

Предупреждение: Для генерации масок в этой реализации WebSockets используется достаточно безопасная функция 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, version протокола и 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())

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

Размер 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 принадлежит WebSocket и не должен удаляться приложением.

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

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

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

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

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

См. также 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().

quint64 QWebSocket::maxAllowedIncomingFrameSize() const

Возвращает максимальный разрешённый размер входящей веб-сокетной рамки.

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

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

quint64 QWebSocket::maxAllowedIncomingMessageSize() const

Возвращает максимальный разрешённый размер входящего веб-сокетного сообщения.

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

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

[static] quint64 QWebSocket::maxIncomingFrameSize()

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

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

[static] quint64 QWebSocket::maxIncomingMessageSize()

Возвращает максимальный поддерживаемый размер входящего веб-сокетного сообщения для данной реализации веб-сокета.

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

[static] quint64 QWebSocket::maxOutgoingFrameSize()

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

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

QString QWebSocket::origin() const

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

quint64 QWebSocket::outgoingFrameSize() const

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

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

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

QAbstractSocket::PauseModes QWebSocket::pauseMode() const

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

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

QHostAddress QWebSocket::peerAddress() const

Возвращает адрес узла-получателя

QString QWebSocket::peerName() const

Возвращает peerName

quint16 QWebSocket::peerPort() const

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

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::setMaxAllowedIncomingFrameSize(quint64 maxAllowedIncomingFrameSize)

Устанавливает максимальный разрешённый размер входящей веб-сокетной рамки в maxAllowedIncomingFrameSize. Если входящая рамка превышает этот предел, узел-отправитель отключается. Допустимый диапазон от 0 до maxIncomingFrameSize(), значение по умолчанию равно maxIncomingFrameSize(). Цель этой функции — предотвратить исчерпание виртуальной памяти.

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

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

void QWebSocket::setMaxAllowedIncomingMessageSize(quint64 maxAllowedIncomingMessageSize)

Устанавливает максимальный разрешённый размер входящего веб-сокетного сообщения в maxAllowedIncomingMessageSize. Если входящее сообщение превышает этот предел, узел-отправитель отключается. Допустимый диапазон от 0 до maxIncomingMessageSize(), значение по умолчанию равно maxIncomingMessageSize(). Цель этой функции — предотвратить исчерпание виртуальной памяти.

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

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

void QWebSocket::setOutgoingFrameSize(quint64 outgoingFrameSize)

Устанавливает максимальный размер исходящей веб-сокетной рамки в outgoingFrameSize. Допустимый диапазон от 0 до maxOutgoingFrameSize(), значение по умолчанию 512 КБ. Цель этой функции — адаптация к максимальному разрешённому размеру рамки получателя.

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

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

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

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