Класс 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 по защищённому соединению.

Предупреждение: Для генерации масок эта реализация Веб-сокетов использует относительно безопасную функцию QRandomGenerator::global()->generate(). Более подробную информацию о важности хорошего маскирования можно найти в документе "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 = 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 указывает, является ли это последним фреймом полного сообщения.

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

См. также полученоТекстовыйФрейм().

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

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

См. также полученоТекстовоеСообщение().

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

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

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

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

[slot] 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() и отключено().

[signal] void QWebSocket::disconnected()

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

См. также close() и подключено().

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

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

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

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

connect(webSocket, QOverload<QAbstractSocket::SocketError>::of(&QWebSocket::error),
    [=](QAbstractSocket::SocketError 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 в ответ на предыдущий запрос пинга. elapsedTime содержит время задержки в миллисекундах, а payload содержит необязательные данные, которые были отправлены с запросом пинга.

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

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

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

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

[signal] void QWebSocket::readChannelFinished()

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

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

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

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

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

Примечание: Вы не можете использовать 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.

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

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

QSslConfiguration QWebSocket::sslConfiguration() const

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

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

QAbstractSocket::SocketState QWebSocket::state() const

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

QWebSocketProtocol::Version QWebSocket::version() const

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