3 \brief The class QWebSocket implements a TCP socket that talks the websocket protocol.
5 WebSockets is a web technology providing full-duplex communications channels over a single TCP connection.
6 The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011 (see http://tools.ietf.org/html/rfc6455).
7 It can both be used in a client application and server application.
9 This class was modeled after QAbstractSocket.
13 \author Kurt Pattyn (pattyn.kurt@gmail.com)
16 \page echoclient QWebSocket client example
17 \brief A sample websocket client that sends a message and displays the message that it receives back.
20 The EchoClient example implements a web socket client that sends a message to a websocket server and dumps the answer that it gets back.
21 This example should ideally be used with the EchoServer example.
23 We start by connecting to the `connected()` signal.
24 \snippet echoclient.cpp constructor
25 After the connection, we open the socket to the given \a url.
27 \snippet echoclient.cpp onConnected
28 When the client is connected successfully, we connect to the `onTextMessageReceived()` signal, and send out "Hello, world!".
29 If connected with the EchoServer, we will receive the same message back.
31 \snippet echoclient.cpp onTextMessageReceived
32 Whenever a message is received, we write it out.
36 \fn void QWebSocket::connected()
37 \brief Emitted when a connection is successfully established.
38 \sa open(), disconnected()
41 \fn void QWebSocket::disconnected()
42 \brief Emitted when the socket is disconnected.
43 \sa close(), connected()
46 \fn void QWebSocket::aboutToClose()
48 This signal is emitted when the socket is about to close.
49 Connect this signal if you have operations that need to be performed before the socket closes
50 (e.g., if you have data in a separate buffer that needs to be written to the device).
55 \fn void QWebSocket::proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)
57 This signal can be emitted when a \a proxy that requires
58 authentication is used. The \a authenticator object can then be
59 filled in with the required details to allow authentication and
60 continue the connection.
62 \note It is not possible to use a QueuedConnection to connect to
63 this signal, as the connection will fail if the authenticator has
64 not been filled in with new information when the signal returns.
66 \sa QAuthenticator, QNetworkProxy
69 \fn void QWebSocket::stateChanged(QAbstractSocket::SocketState state);
71 This signal is emitted whenever QWebSocket's state changes.
72 The \a socketState parameter is the new state.
74 QAbstractSocket::SocketState is not a registered metatype, so for queued
75 connections, you will have to register it with Q_REGISTER_METATYPE() and
81 \fn void QWebSocket::readChannelFinished()
83 This signal is emitted when the input (reading) stream is closed in this device. It is emitted as soon as the closing is detected.
89 \fn void QWebSocket::textFrameReceived(QString frame, bool isLastFrame);
91 This signal is emitted whenever a text frame is received. The \a frame contains the data and
92 \a isLastFrame indicates whether this is the last frame of the complete message.
94 This signal can be used to process large messages frame by frame, instead of waiting for the complete
97 \sa binaryFrameReceived(QByteArray, bool), textMessageReceived(QString)
100 \fn void QWebSocket::binaryFrameReceived(QByteArray frame, bool isLastFrame);
102 This signal is emitted whenever a binary frame is received. The \a frame contains the data and
103 \a isLastFrame indicates whether this is the last frame of the complete message.
105 This signal can be used to process large messages frame by frame, instead of waiting for the complete
108 \sa textFrameReceived(QString, bool), binaryMessageReceived(QByteArray)
111 \fn void QWebSocket::textMessageReceived(QString message);
113 This signal is emitted whenever a text message is received. The \a message contains the received text.
115 \sa textFrameReceived(QString, bool), binaryMessageReceived(QByteArray)
118 \fn void QWebSocket::binaryMessageReceived(QByteArray message);
120 This signal is emitted whenever a binary message is received. The \a message contains the received bytes.
122 \sa binaryFrameReceived(QByteArray, bool), textMessageReceived(QString)
125 \fn void QWebSocket::error(QAbstractSocket::SocketError error);
127 This signal is emitted after an error occurred. The \a socketError
128 parameter describes the type of error that occurred.
130 QAbstractSocket::SocketError is not a registered metatype, so for queued
131 connections, you will have to register it with Q_DECLARE_METATYPE() and
134 \sa error(), errorString()
137 \fn void QWebSocket::pong(quint64 elapsedTime)
139 Emitted when a pong message is received in reply to a previous ping.
143 #include "qwebsocket.h"
144 #include "qwebsocket_p.h"
146 #include <QTcpSocket>
147 #include <QByteArray>
148 #include <QHostAddress>
156 const quint64 FRAME_SIZE_IN_BYTES = 512 * 512 * 2; //maximum size of a frame when sending a message
159 * \brief Creates a new QWebSocket with the given \a origin, the \a version of the protocol to use and \a parent.
161 * The \a origin of the client is as specified in http://tools.ietf.org/html/rfc6454.
162 * (The \a origin is not required for non-web browser clients (see RFC 6455)).
163 * \note Currently only V13 (RFC 6455) is supported
165 QWebSocket::QWebSocket(QString origin, QWebSocketProtocol::Version version, QObject *parent) :
167 d_ptr(new QWebSocketPrivate(origin, version, this, this))
172 * \brief Destroys the QWebSocket. Closes the socket if it is still open, and releases any used resources.
174 QWebSocket::~QWebSocket()
181 * \brief Aborts the current socket and resets the socket. Unlike close(), this function immediately closes the socket, discarding any pending data in the write buffer.
183 void QWebSocket::abort()
189 * Returns the type of error that last occurred
192 QAbstractSocket::SocketError QWebSocket::error() const
194 return d_ptr->error();
197 //only called by QWebSocketPrivate::upgradeFrom
201 QWebSocket::QWebSocket(QTcpSocket *pTcpSocket, QWebSocketProtocol::Version version, QObject *parent) :
203 d_ptr(new QWebSocketPrivate(pTcpSocket, version, this, this))
208 * Returns a human-readable description of the last error that occurred
212 QString QWebSocket::errorString() const
214 return d_ptr->errorString();
218 This function writes as much as possible from the internal write buffer to the underlying network socket, without blocking.
219 If any data was written, this function returns true; otherwise false is returned.
220 Call this function if you need WebSocket to start sending buffered data immediately.
221 The number of bytes successfully written depends on the operating system.
222 In most cases, you do not need to call this function, because WebSocket will start sending data automatically once control goes back to the event loop.
223 In the absence of an event loop, call waitForBytesWritten() instead.
225 \sa send() and waitForBytesWritten().
227 bool QWebSocket::flush()
229 return d_ptr->flush();
233 * Sends the given \a message over the socket as a text message and returns the number of bytes actually sent.
234 * \param message Text message to be sent. Must be '\0' terminated.
235 * \return The number of bytes actually sent.
236 * \sa write(const QString &message) and write(const char *message, qint64 maxSize)
238 qint64 QWebSocket::write(const char *message)
240 return d_ptr->write(message);
244 * Sends the most \a maxSize bytes of the given \a message over the socket as a text message and returns the number of bytes actually sent.
245 * \param message Text message to be sent.
246 * \return The number of bytes actually sent.
247 * \sa write(const QString &message) and write(const char *message)
249 qint64 QWebSocket::write(const char *message, qint64 maxSize)
251 return d_ptr->write(message, maxSize);
255 \brief Sends the given \a message over the socket as a text message and returns the number of bytes actually sent.
256 \param message The message to be sent
257 \return The number of bytes actually sent.
258 \sa write(const char *message) and write(const char *message, qint64 maxSize)
260 qint64 QWebSocket::write(const QString &message)
262 return d_ptr->write(message);
266 * @brief Sends the given \a data over the socket as a binary message and returns the number of bytes actually sent.
267 * @param data The binary data to be sent.
268 * @return The number of bytes actually sent.
270 qint64 QWebSocket::write(const QByteArray &data)
272 return d_ptr->write(data);
276 * \brief Gracefully closes the socket with the given \a closeCode and \a reason. Any data in the write buffer is flushed before the socket is closed.
277 * \param closeCode The QWebSocketProtocol::CloseCode indicating the reason to close.
278 * \param reason A string describing the error more in detail
280 void QWebSocket::close(QWebSocketProtocol::CloseCode closeCode, QString reason)
282 d_ptr->close(closeCode, reason);
286 * \brief Opens a websocket connection using the given \a url.
287 * If \a mask is true, all frames will be masked; this is only necessary for client side sockets; servers should never mask
288 * \param url The url to connect to
289 * \param mask When true, all frames are masked
290 * \note A client socket must *always* mask its frames; servers may *never* mask its frames
292 void QWebSocket::open(const QUrl &url, bool mask)
294 d_ptr->open(url, mask);
298 * \brief Pings the server to indicate that the connection is still alive.
302 void QWebSocket::ping()
308 * \brief Returns the version the socket is currently using
310 QWebSocketProtocol::Version QWebSocket::version()
312 return d_ptr->version();
316 * @brief Returns the name of the resource currently accessed.
318 QString QWebSocket::resourceName()
320 return d_ptr->resourceName();
324 * \brief Returns the url the socket is connected to or will connect to.
326 QUrl QWebSocket::requestUrl()
328 return d_ptr->requestUrl();
332 Returns the current origin
334 QString QWebSocket::origin()
336 return d_ptr->origin();
340 Returns the currently used protocol.
342 QString QWebSocket::protocol()
344 return d_ptr->protocol();
348 Returns the currently used extension.
350 QString QWebSocket::extension()
352 return d_ptr->extension();
356 Returns the current state of the socket
358 QAbstractSocket::SocketState QWebSocket::state() const
360 return d_ptr->state();
364 @brief Waits until the socket is connected, up to \a msecs milliseconds. If the connection has been established, this function returns true; otherwise it returns false. In the case where it returns false, you can call error() to determine the cause of the error.
365 The following example waits up to one second for a connection to be established:
368 socket->open("ws://localhost:1234", false);
369 if (socket->waitForConnected(1000))
371 qDebug("Connected!");
375 If \a msecs is -1, this function will not time out.
376 @note This function may wait slightly longer than msecs, depending on the time it takes to complete the host lookup.
377 @note Multiple calls to this functions do not accumulate the time. If the function times out, the connecting process will be aborted.
379 \param msecs The number of milliseconds to wait before a time out occurs; when -1, this function will block until the socket is connected.
381 \sa connected(), open(), state()
383 bool QWebSocket::waitForConnected(int msecs)
385 return d_ptr->waitForConnected(msecs);
389 Waits \a msecs for the socket to be disconnected.
390 If the socket was successfully disconnected within time, this method returns true.
391 Otherwise false is returned.
393 \param msecs The number of milliseconds to wait before a time out occurs; when -1, this function will block until the socket is disconnected.
397 bool QWebSocket::waitForDisconnected(int msecs)
399 return d_ptr->waitForDisconnected(msecs);
403 Returns the local address
405 QHostAddress QWebSocket::localAddress() const
407 return d_ptr->localAddress();
411 Returns the local port
413 quint16 QWebSocket::localPort() const
415 return d_ptr->localPort();
419 Returns the peer address
421 QHostAddress QWebSocket::peerAddress() const
423 return d_ptr->peerAddress();
429 QString QWebSocket::peerName() const
431 return d_ptr->peerName();
437 quint16 QWebSocket::peerPort() const
439 return d_ptr->peerPort();
443 * Returns the currently configured proxy
445 QNetworkProxy QWebSocket::proxy() const
447 return d_ptr->proxy();
451 * Returns the size in bytes of the readbuffer that is used by the socket.
453 qint64 QWebSocket::readBufferSize() const
455 return d_ptr->readBufferSize();
459 Sets the proxy to \a networkProxy
461 void QWebSocket::setProxy(const QNetworkProxy &networkProxy)
463 d_ptr->setProxy(networkProxy);
467 Sets the size of WebSocket's internal read buffer to be size bytes.
468 If the buffer size is limited to a certain size, WebSocket won't buffer more than this size of data.
469 Exceptionally, a buffer size of 0 means that the read buffer is unlimited and all incoming data is buffered. This is the default.
470 This option is useful if you only read the data at certain points in time (e.g., 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.
471 \sa readBufferSize() and read().
473 void QWebSocket::setReadBufferSize(qint64 size)
475 d_ptr->setReadBufferSize(size);
479 Sets the given \a option to the value described by \a value.
482 void QWebSocket::setSocketOption(QAbstractSocket::SocketOption option, const QVariant &value)
484 d_ptr->setSocketOption(option, value);
488 Returns the value of the option \a option.
489 \sa setSocketOption().
491 QVariant QWebSocket::socketOption(QAbstractSocket::SocketOption option)
493 return d_ptr->socketOption(option);
497 Returns true if the WebSocket is valid.
499 bool QWebSocket::isValid()
501 return d_ptr->isValid();