QWebSocket Class

Implements a TCP socket that talks the WebSocket protocol. More...

Header: #include <QWebSocket>
qmake: QT += websockets
Since: Qt 5.3
Inherits: QObject

Public Functions

QWebSocket(const QString &origin = QString(), QWebSocketProtocol::Version version = QWebSocketProtocol::VersionLatest, QObject *parent = nullptr)
virtual ~QWebSocket()
void abort()
QWebSocketProtocol::CloseCode closeCode() const
QString closeReason() const
QAbstractSocket::SocketError error() const
QString errorString() const
bool flush()
void ignoreSslErrors(const QList<QSslError> &errors)
bool isValid() const
QHostAddress localAddress() const
quint16 localPort() const
const QMaskGenerator *maskGenerator() const
QString origin() const
QAbstractSocket::PauseModes pauseMode() const
QHostAddress peerAddress() const
QString peerName() const
quint16 peerPort() const
QNetworkProxy proxy() const
qint64 readBufferSize() const
QNetworkRequest request() const
QUrl requestUrl() const
QString resourceName() const
void resume()
qint64 sendBinaryMessage(const QByteArray &data)
qint64 sendTextMessage(const QString &message)
void setMaskGenerator(const QMaskGenerator *maskGenerator)
void setPauseMode(QAbstractSocket::PauseModes pauseMode)
void setProxy(const QNetworkProxy &networkProxy)
void setReadBufferSize(qint64 size)
void setSslConfiguration(const QSslConfiguration &sslConfiguration)
QSslConfiguration sslConfiguration() const
QAbstractSocket::SocketState state() const
QWebSocketProtocol::Version version() const
  • 34 public functions inherited from QObject

Public Slots

void close(QWebSocketProtocol::CloseCode closeCode = QWebSocketProtocol::CloseCodeNormal, const QString &reason = QString())
void ignoreSslErrors()
void open(const QUrl &url)
void open(const QNetworkRequest &request)
void ping(const QByteArray &payload = QByteArray())
  • 1 public slot inherited from QObject

Signals

void aboutToClose()
void binaryFrameReceived(const QByteArray &frame, bool isLastFrame)
void binaryMessageReceived(const QByteArray &message)
void bytesWritten(qint64 bytes)
void connected()
void disconnected()
void error(QAbstractSocket::SocketError error)
void pong(quint64 elapsedTime, const QByteArray &payload)
void preSharedKeyAuthenticationRequired(QSslPreSharedKeyAuthenticator *authenticator)
void proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *pAuthenticator)
void readChannelFinished()
void sslErrors(const QList<QSslError> &errors)
void stateChanged(QAbstractSocket::SocketState state)
void textFrameReceived(const QString &frame, bool isLastFrame)
void textMessageReceived(const QString &message)

Additional Inherited Members

  • 1 property inherited from QObject
  • 1 public variable inherited from QObject
  • 10 static public members inherited from QObject
  • 9 protected functions inherited from QObject
  • 2 protected variables inherited from QObject

Detailed Description

Implements a TCP socket that talks the WebSocket protocol.

WebSockets is a web technology providing full-duplex communications channels over a single TCP connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011. QWebSocket can both be used in a client application and server application.

This class was modeled after QAbstractSocket.

QWebSocket currently does not support WebSocket Extensions and WebSocket Subprotocols.

QWebSocket only supports version 13 of the WebSocket protocol, as outlined in RFC 6455.

Note: Some proxies do not understand certain HTTP headers used during a WebSocket handshake. In that case, non-secure WebSocket connections fail. The best way to mitigate against this problem is to use WebSocket over a secure connection.

Warning: To generate masks, this implementation of WebSockets uses the reasonably secure QRandomGenerator::global()->generate() function. For more information about the importance of good masking, see "Talking to Yourself for Fun and Profit" by Lin-Shung Huang et al. The best measure against attacks mentioned in the document above, is to use QWebSocket over a secure connection (wss://). In general, always be careful to not have 3rd party script access to a QWebSocket in your application.

See also QAbstractSocket, QTcpSocket, and QWebSocket client example.

Member Function Documentation

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

Creates a new QWebSocket with the given origin, the version of the protocol to use and parent.

The origin of the client is as specified in RFC 6454. (The origin is not required for non-web browser clients (see RFC 6455)). The origin may not contain new line characters, otherwise the connection will be aborted immediately during the handshake phase.

Note: Currently only V13 (RFC 6455) is supported

[virtual] QWebSocket::~QWebSocket()

Destroys the QWebSocket. Closes the socket if it is still open, and releases any used resources.

void QWebSocket::abort()

Aborts the current socket and resets the socket. Unlike close(), this function immediately closes the socket, discarding any pending data in the write buffer.

[signal] void QWebSocket::aboutToClose()

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

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

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

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

Gracefully closes the socket with the given closeCode and reason.

Any data in the write buffer is flushed before the socket is closed. The closeCode is a QWebSocketProtocol::CloseCode indicating the reason to close, and reason describes the reason of the closure more in detail. All control frames, including the Close frame, are limited to 125 bytes. Since two of these are used for closeCode the maximum length of reason is 123! If reason exceeds this limit it will be truncated.

QWebSocketProtocol::CloseCode QWebSocket::closeCode() const

Returns the code indicating why the socket was closed.

See also QWebSocketProtocol::CloseCode and closeReason().

QString QWebSocket::closeReason() const

Returns the reason why the socket was closed.

See also closeCode().

[signal] void QWebSocket::connected()

[signal] void QWebSocket::disconnected()

QAbstractSocket::SocketError QWebSocket::error() const

Returns the type of error that last occurred

See also errorString().

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

Note: Signal error is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:


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

QString QWebSocket::errorString() const

Returns a human-readable description of the last error that occurred

See also error().

bool QWebSocket::flush()

This function writes as much as possible from the internal write buffer to the underlying network socket, without blocking. If any data was written, this function returns true; otherwise false is returned. Call this function if you need QWebSocket to start sending buffered data immediately. The number of bytes successfully written depends on the operating system. In most cases, you do not need to call this function, because QWebSocket will start sending data automatically once control goes back to the event loop.

[slot] void QWebSocket::ignoreSslErrors()

This slot tells QWebSocket to ignore errors during QWebSocket's handshake phase and continue connecting. If you want to continue with the connection even if errors occur during the handshake phase, then you must call this slot, either from a slot connected to sslErrors(), or before the handshake phase. If you don't call this slot, either in response to errors or before the handshake, the connection will be dropped after the sslErrors() signal has been emitted.

Warning: Be sure to always let the user inspect the errors reported by the sslErrors() signal, and only call this method upon confirmation from the user that proceeding is ok. If there are unexpected errors, the connection should be aborted. Calling this method without inspecting the actual errors will most likely pose a security risk for your application. Use it with great care!

See also sslErrors(), QSslSocket::ignoreSslErrors(), and QNetworkReply::ignoreSslErrors().

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

This is an overloaded function.

This method tells QWebSocket to ignore the errors given in errors.

Note that you can set the expected certificate in the SSL error: If, for instance, you want to connect to a server that uses a self-signed certificate, consider the following snippet:


  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")));

Multiple calls to this function will replace the list of errors that were passed in previous calls. You can clear the list of errors you want to ignore by calling this function with an empty list.

See also sslErrors().

bool QWebSocket::isValid() const

Returns true if the socket is ready for reading and writing; otherwise returns false.

QHostAddress QWebSocket::localAddress() const

Returns the local address

quint16 QWebSocket::localPort() const

Returns the local port

const QMaskGenerator *QWebSocket::maskGenerator() const

Returns the mask generator that is currently used by this QWebSocket.

See also setMaskGenerator().

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

Opens a WebSocket connection using the given url.

If the url contains newline characters (\r\n), then the error signal will be emitted with QAbstractSocket::ConnectionRefusedError as error type.

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

Opens a WebSocket connection using the given request.

The request url will be used to open the WebSocket connection. Headers present in the request will be sent to the server in the upgrade request, together with the ones needed for the websocket handshake.

This function was introduced in Qt 5.6.

QString QWebSocket::origin() const

Returns the current origin.

QAbstractSocket::PauseModes QWebSocket::pauseMode() const

Returns the pause mode of this socket

See also setPauseMode().

QHostAddress QWebSocket::peerAddress() const

Returns the peer address

QString QWebSocket::peerName() const

Returns the peerName

quint16 QWebSocket::peerPort() const

Returns the peerport

[slot] void QWebSocket::ping(const QByteArray &payload = QByteArray())

Pings the server to indicate that the connection is still alive. Additional payload can be sent along the ping message.

The size of the payload cannot be bigger than 125. If it is larger, the payload is clipped to 125 bytes.

See also pong().

[signal] void QWebSocket::pong(quint64 elapsedTime, const QByteArray &payload)

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

QNetworkProxy QWebSocket::proxy() const

Returns the currently configured proxy

See also setProxy().

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

qint64 QWebSocket::readBufferSize() const

Returns the size in bytes of the readbuffer that is used by the socket.

See also setReadBufferSize().

[signal] void QWebSocket::readChannelFinished()

QNetworkRequest QWebSocket::request() const

Returns the request that was or will be used to open this socket.

This function was introduced in Qt 5.6.

QUrl QWebSocket::requestUrl() const

Returns the url the socket is connected to or will connect to.

QString QWebSocket::resourceName() const

Returns the name of the resource currently accessed.

void QWebSocket::resume()

Continues data transfer on the socket. This method should only be used after the socket has been set to pause upon notifications and a notification has been received. The only notification currently supported is sslErrors(). Calling this method if the socket is not paused results in undefined behavior.

See also pauseMode() and setPauseMode().

qint64 QWebSocket::sendBinaryMessage(const QByteArray &data)

Sends the given data over the socket as a binary message and returns the number of bytes actually sent.

See also sendTextMessage().

qint64 QWebSocket::sendTextMessage(const QString &message)

Sends the given message over the socket as a text message and returns the number of bytes actually sent.

See also sendBinaryMessage().

void QWebSocket::setMaskGenerator(const QMaskGenerator *maskGenerator)

Sets the generator to use for creating masks to maskGenerator. The default QWebSocket generator can be reset by supplying a nullptr. The mask generator can be changed at any time, even while the connection is open.

See also maskGenerator().

void QWebSocket::setPauseMode(QAbstractSocket::PauseModes pauseMode)

Controls whether to pause upon receiving a notification. The pauseMode parameter specifies the conditions in which the socket should be paused.

The only notification currently supported is sslErrors(). If set to PauseOnSslErrors, data transfer on the socket will be paused and needs to be enabled explicitly again by calling resume(). By default, this option is set to PauseNever. This option must be called before connecting to the server, otherwise it will result in undefined behavior.

See also pauseMode() and resume().

void QWebSocket::setProxy(const QNetworkProxy &networkProxy)

Sets the proxy to networkProxy

See also proxy().

void QWebSocket::setReadBufferSize(qint64 size)

Sets the size of QWebSocket's internal read buffer to be size bytes.

If the buffer size is limited to a certain size, QWebSocket won't buffer more than this size of data. Exceptionally, a buffer size of 0 means that the read buffer is unlimited and all incoming data is buffered. This is the default. This option is useful if you only read the data at certain points in time (for example, in a real-time streaming application) or if you want to protect your socket against receiving too much data, which may eventually cause your application to run out of memory.

See also readBufferSize().

void QWebSocket::setSslConfiguration(const QSslConfiguration &sslConfiguration)

Sets the socket's SSL configuration to be the contents of sslConfiguration.

This function sets the local certificate, the ciphers, the private key and the CA certificates to those stored in sslConfiguration. It is not possible to set the SSL-state related fields.

See also sslConfiguration().

QSslConfiguration QWebSocket::sslConfiguration() const

Returns the socket's SSL configuration state. The default SSL configuration of a socket is to use the default ciphers, default CA certificates, no local private key or certificate. The SSL configuration also contains fields that can change with time without notice.

See also setSslConfiguration().

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

QAbstractSocket::SocketState QWebSocket::state() const

Returns the current state of the socket.

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

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

[signal] void QWebSocket::textMessageReceived(const QString &message)

QWebSocketProtocol::Version QWebSocket::version() const

Returns the version the socket is currently using.