Класс QWebSocket

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

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

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

• 32 общедоступных функций, унаследованных от QObject

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

• 1 открытый слот, унаследованный от QObject

Сигналы

• 2 сигнала унаследованы от 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, version протокола и 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 указывает, является ли это последний фрейм полного сообщения.

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

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

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

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

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

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

[signal] void QWebSocket::disconnected()

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

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

QAbstractSocket::SocketError QWebSocket::error() const

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

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

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

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.

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

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

QString QWebSocket::origin() const

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

QAbstractSocket::PauseModes QWebSocket::pauseMode() const

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

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

QHostAddress QWebSocket::peerAddress() const

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

QString QWebSocket::peerName() const

Возвращает peerName.

quint16 QWebSocket::peerPort() const

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

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

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

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

QNetworkProxy QWebSocket::proxy() const

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

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

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

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

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

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

qint64 QWebSocket::sendTextMessage(const QString &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().

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

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

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

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

QAbstractSocket::SocketState QWebSocket::state() const

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

void QWebSocket::stateChanged(QAbstractSocket::SocketState state)

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

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

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

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

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

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

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

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

void QWebSocket::textMessageReceived(const QString &message)

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

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

QWebSocketProtocol::Version QWebSocket::version() const

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