Класс QWebSocket

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

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

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

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

Сигналы

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

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

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

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

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

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

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

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

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

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

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

[signal] void QWebSocket::aboutToClose()

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

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

[signal, since 6.2] void QWebSocket::alertReceived(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)

QWebSocket излучает этот сигнал, если от соседа получено сообщение об ошибке. level указывает, была ли ошибка критической или предупреждением. type — код, объясняющий, почему было отправлено сообщение об ошибке. Если доступно текстовое описание сообщения об ошибке, оно передаётся в description.

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

См. также alertSent(), QSsl::AlertLevel и QSsl::AlertType.

[signal, since 6.2] void QWebSocket::alertSent(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)

QWebSocket излучает этот сигнал, если сообщении об ошибке было отправлено соседу. level указывает, было ли это предупреждение или критическое сообщение. type содержит код сообщения об ошибке. Если доступно текстовое описание сообщения об ошибке, оно передаётся в description.

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

См. также alertReceived(), QSsl::AlertLevel и QSsl::AlertType.

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

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

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

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

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

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

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

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

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

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

[signal] void QWebSocket::disconnected()

Испускается при разъединении сокета.

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

[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){ /* ... */ });

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

[signal, since 6.2] void QWebSocket::handshakeInterruptedOnError(const QSslError &error)

QWebSocket испускает этот сигнал, если при проверке сертификата была обнаружена ошибка, и если в QSslConfiguration было включено раннее сообщение об ошибке. Приложение должно проанализировать error и решить, продолжать ли рукопожатие или прервать его и отправить сообщение об ошибке партнёру. Соединение сигнал-слот должно быть прямым.

Данная функция была введена в Qt 6.2.

См. также continueInterruptedHandshake(), sslErrors() и QSslConfiguration::setHandshakeMustInterruptOnError().

[slot] void QWebSocket::ignoreSslErrors()

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

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

[slot, since 5.6] 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.

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

[signal, since 6.2] void QWebSocket::peerVerifyError(const QSslError &error)

QWebSocket может испускать этот сигнал несколько раз во время SSL-рукопожатия, прежде чем будет установлено шифрование, чтобы указать, что произошла ошибка при установлении идентичности партнёра. Ошибка error обычно указывает, что QWebSocket не может надёжно идентифицировать партнёра.

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

Данная функция была введена в Qt 6.2.

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

[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, since 5.8] void QWebSocket::preSharedKeyAuthenticationRequired(QSslPreSharedKeyAuthenticator *authenticator)

Этот сигнал испускается, если SSL/TLS-рукопожатие согласуется с шифрованием PSK, и, следовательно, требуется аутентификация PSK.

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

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

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

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

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

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

[signal] void QWebSocket::readChannelFinished()

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

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

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

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

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

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

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

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(), эта функция немедленно закрывает сокет, отбрасывая все ожидающие данные в буфере записи.

[since 5.12] qint64 QWebSocket::bytesToWrite() const

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

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

См. также flush.

QWebSocketProtocol::CloseCode QWebSocket::closeCode() const

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

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

QString QWebSocket::closeReason() const

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

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

[since 6.2] void QWebSocket::continueInterruptedHandshake()

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

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

См. также handshakeInterruptedOnError() и QSslConfiguration::setHandshakeMustInterruptOnError().

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

[since 5.15] quint64 QWebSocket::maxAllowedIncomingFrameSize() const

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

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

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

[since 5.15] quint64 QWebSocket::maxAllowedIncomingMessageSize() const

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

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

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

[static, since 5.15] quint64 QWebSocket::maxIncomingFrameSize()

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

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

[static, since 5.15] quint64 QWebSocket::maxIncomingMessageSize()

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

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

[static, since 5.15] quint64 QWebSocket::maxOutgoingFrameSize()

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

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

QString QWebSocket::origin() const

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

[since 5.15] quint64 QWebSocket::outgoingFrameSize() const

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

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

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

QAbstractSocket::PauseModes QWebSocket::pauseMode() const

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

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

QHostAddress QWebSocket::peerAddress() const

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

QString QWebSocket::peerName() const

Возвращает имя удалённого узла.

quint16 QWebSocket::peerPort() const

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

QNetworkProxy QWebSocket::proxy() const

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

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

qint64 QWebSocket::readBufferSize() const

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

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

[since 5.6] 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)

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

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

qint64 QWebSocket::sendTextMessage(const QString &message)

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

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

void QWebSocket::setMaskGenerator(const QMaskGenerator *maskGenerator)

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

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

[since 5.15] void QWebSocket::setMaxAllowedIncomingFrameSize(quint64 maxAllowedIncomingFrameSize)

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

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

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

[since 5.15] void QWebSocket::setMaxAllowedIncomingMessageSize(quint64 maxAllowedIncomingMessageSize)

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

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

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

[since 5.15] 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

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