src/qwebsocket.cpp

   1 /*!
   2         \class QWebSocket
   3         \brief The class QWebSocket implements a TCP socket that talks the websocket protocol.
   4
   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.
   8
   9         This class was modeled after QAbstractSocket.
  10
  11         \ref echoclient
  12
  13         \author Kurt Pattyn (pattyn.kurt@gmail.com)
  14 */
  15 /*!
  16   \page echoclient QWebSocket client example
  17   \brief A sample websocket client that sends a message and displays the message that it receives back.
  18
  19   \section Description
  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.
  22   \section Code
  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.
  26
  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.
  30
  31   \snippet echoclient.cpp onTextMessageReceived
  32   Whenever a message is received, we write it out.
  33 */
  34
  35 /*!
  36   \fn void QWebSocket::connected()
  37   \brief Emitted when a connection is successfully established.
  38   \sa open(), disconnected()
  39 */
  40 /*!
  41   \fn void QWebSocket::disconnected()
  42   \brief Emitted when the socket is disconnected.
  43   \sa close(), connected()
  44 */
  45 /*!
  46         \fn void QWebSocket::aboutToClose()
  47
  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).
  51
  52         \sa close()
  53  */
  54 /*!
  55 \fn void QWebSocket::proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)
  56
  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.
  61
  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.
  65
  66 \sa QAuthenticator, QNetworkProxy
  67 */
  68 /*!
  69         \fn void QWebSocket::stateChanged(QAbstractSocket::SocketState state);
  70
  71         This signal is emitted whenever QWebSocket's state changes.
  72         The \a socketState parameter is the new state.
  73
  74         QAbstractSocket::SocketState is not a registered metatype, so for queued
  75         connections, you will have to register it with Q_REGISTER_METATYPE() and
  76         qRegisterMetaType().
  77
  78         \sa state()
  79 */
  80 /*!
  81         \fn void QWebSocket::readChannelFinished()
  82
  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.
  84
  85         \sa close()
  86 */
  87
  88 /*!
  89         \fn void QWebSocket::textFrameReceived(QString frame, bool isLastFrame);
  90
  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.
  93
  94         This signal can be used to process large messages frame by frame, instead of waiting for the complete
  95         message to arrive.
  96
  97         \sa binaryFrameReceived(QByteArray, bool), textMessageReceived(QString)
  98 */
  99 /*!
 100         \fn void QWebSocket::binaryFrameReceived(QByteArray frame, bool isLastFrame);
 101
 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.
 104
 105         This signal can be used to process large messages frame by frame, instead of waiting for the complete
 106         message to arrive.
 107
 108         \sa textFrameReceived(QString, bool), binaryMessageReceived(QByteArray)
 109 */
 110 /*!
 111         \fn void QWebSocket::textMessageReceived(QString message);
 112
 113         This signal is emitted whenever a text message is received. The \a message contains the received text.
 114
 115         \sa textFrameReceived(QString, bool), binaryMessageReceived(QByteArray)
 116 */
 117 /*!
 118         \fn void QWebSocket::binaryMessageReceived(QByteArray message);
 119
 120         This signal is emitted whenever a binary message is received. The \a message contains the received bytes.
 121
 122         \sa binaryFrameReceived(QByteArray, bool), textMessageReceived(QString)
 123 */
 124 /*!
 125         \fn void QWebSocket::error(QAbstractSocket::SocketError error);
 126
 127         This signal is emitted after an error occurred. The \a socketError
 128         parameter describes the type of error that occurred.
 129
 130         QAbstractSocket::SocketError is not a registered metatype, so for queued
 131         connections, you will have to register it with Q_DECLARE_METATYPE() and
 132         qRegisterMetaType().
 133
 134         \sa error(), errorString()
 135 */
 136 /*!
 137   \fn void QWebSocket::pong(quint64 elapsedTime)
 138
 139   Emitted when a pong message is received in reply to a previous ping.
 140
 141   \sa ping()
 142   */
 143 #include "qwebsocket.h"
 144 #include "qwebsocket_p.h"
 145 #include <QUrl>
 146 #include <QTcpSocket>
 147 #include <QByteArray>
 148 #include <QHostAddress>
 149
 150 #include <QDebug>
 151
 152 #include <limits>
 153
 154 QT_BEGIN_NAMESPACE
 155
 156 const quint64 FRAME_SIZE_IN_BYTES = 512 * 512 * 2;      //maximum size of a frame when sending a message
 157
 158 /*!
 159  * \brief Creates a new QWebSocket with the given \a origin, the \a version of the protocol to use and \a parent.
 160  *
 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
 164  */
 165 QWebSocket::QWebSocket(QString origin, QWebSocketProtocol::Version version, QObject *parent) :
 166         QObject(parent),
 167         d_ptr(new QWebSocketPrivate(origin, version, this, this))
 168 {
 169 }
 170
 171 /*!
 172  * \brief Destroys the QWebSocket. Closes the socket if it is still open, and releases any used resources.
 173  */
 174 QWebSocket::~QWebSocket()
 175 {
 176         delete d_ptr;
 177         //d_ptr = 0;
 178 }
 179
 180 /*!
 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.
 182  */
 183 void QWebSocket::abort()
 184 {
 185         d_ptr->abort();
 186 }
 187
 188 /*!
 189  * Returns the type of error that last occurred
 190  * \sa errorString()
 191  */
 192 QAbstractSocket::SocketError QWebSocket::error() const
 193 {
 194         return d_ptr->error();
 195 }
 196
 197 //only called by QWebSocketPrivate::upgradeFrom
 198 /*!
 199   \internal
 200  */
 201 QWebSocket::QWebSocket(QTcpSocket *pTcpSocket, QWebSocketProtocol::Version version, QObject *parent) :
 202         QObject(parent),
 203         d_ptr(new QWebSocketPrivate(pTcpSocket, version, this, this))
 204 {
 205 }
 206
 207 /*!
 208  * Returns a human-readable description of the last error that occurred
 209  *
 210  * \sa error()
 211  */
 212 QString QWebSocket::errorString() const
 213 {
 214         return d_ptr->errorString();
 215 }
 216
 217 /*!
 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.
 224
 225         \sa send() and waitForBytesWritten().
 226 */
 227 bool QWebSocket::flush()
 228 {
 229         return d_ptr->flush();
 230 }
 231
 232 /*!
 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)
 237  */
 238 qint64 QWebSocket::write(const char *message)
 239 {
 240         return d_ptr->write(message);
 241 }
 242
 243 /*!
 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)
 248  */
 249 qint64 QWebSocket::write(const char *message, qint64 maxSize)
 250 {
 251         return d_ptr->write(message, maxSize);
 252 }
 253
 254 /*!
 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)
 259  */
 260 qint64 QWebSocket::write(const QString &message)
 261 {
 262         return d_ptr->write(message);
 263 }
 264
 265 /**
 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.
 269  */
 270 qint64 QWebSocket::write(const QByteArray &data)
 271 {
 272         return d_ptr->write(data);
 273 }
 274
 275 /*!
 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
 279  */
 280 void QWebSocket::close(QWebSocketProtocol::CloseCode closeCode, QString reason)
 281 {
 282         d_ptr->close(closeCode, reason);
 283 }
 284
 285 /*!
 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
 291  */
 292 void QWebSocket::open(const QUrl &url, bool mask)
 293 {
 294         d_ptr->open(url, mask);
 295 }
 296
 297 /*!
 298  * \brief Pings the server to indicate that the connection is still alive.
 299  *
 300  * \sa pong()
 301  */
 302 void QWebSocket::ping()
 303 {
 304         d_ptr->ping();
 305 }
 306
 307 /*!
 308  * \brief Returns the version the socket is currently using
 309  */
 310 QWebSocketProtocol::Version QWebSocket::version()
 311 {
 312         return d_ptr->version();
 313 }
 314
 315 /**
 316  * @brief Returns the name of the resource currently accessed.
 317  */
 318 QString QWebSocket::resourceName()
 319 {
 320         return d_ptr->resourceName();
 321 }
 322
 323 /*!
 324  * \brief Returns the url the socket is connected to or will connect to.
 325  */
 326 QUrl QWebSocket::requestUrl()
 327 {
 328         return d_ptr->requestUrl();
 329 }
 330
 331 /*!
 332   Returns the current origin
 333  */
 334 QString QWebSocket::origin()
 335 {
 336         return d_ptr->origin();
 337 }
 338
 339 /*!
 340   Returns the currently used protocol.
 341  */
 342 QString QWebSocket::protocol()
 343 {
 344         return d_ptr->protocol();
 345 }
 346
 347 /*!
 348   Returns the currently used extension.
 349  */
 350 QString QWebSocket::extension()
 351 {
 352         return d_ptr->extension();
 353 }
 354
 355 /*!
 356   Returns the current state of the socket
 357  */
 358 QAbstractSocket::SocketState QWebSocket::state() const
 359 {
 360         return d_ptr->state();
 361 }
 362
 363 /**
 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:
 366
 367         ~~~{.cpp}
 368         socket->open("ws://localhost:1234", false);
 369         if (socket->waitForConnected(1000))
 370         {
 371                 qDebug("Connected!");
 372         }
 373         ~~~
 374
 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.
 378
 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.
 380
 381         \sa connected(), open(), state()
 382  */
 383 bool QWebSocket::waitForConnected(int msecs)
 384 {
 385         return d_ptr->waitForConnected(msecs);
 386 }
 387
 388 /*!
 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.
 392
 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.
 394
 395   \sa close(), state()
 396 */
 397 bool QWebSocket::waitForDisconnected(int msecs)
 398 {
 399         return d_ptr->waitForDisconnected(msecs);
 400 }
 401
 402 /*!
 403   Returns the local address
 404  */
 405 QHostAddress QWebSocket::localAddress() const
 406 {
 407         return d_ptr->localAddress();
 408 }
 409
 410 /*!
 411   Returns the local port
 412  */
 413 quint16 QWebSocket::localPort() const
 414 {
 415         return d_ptr->localPort();
 416 }
 417
 418 /*!
 419   Returns the peer address
 420  */
 421 QHostAddress QWebSocket::peerAddress() const
 422 {
 423         return d_ptr->peerAddress();
 424 }
 425
 426 /*!
 427   Returns the peerName
 428  */
 429 QString QWebSocket::peerName() const
 430 {
 431         return d_ptr->peerName();
 432 }
 433
 434 /*!
 435   Returns the peerport
 436  */
 437 quint16 QWebSocket::peerPort() const
 438 {
 439         return d_ptr->peerPort();
 440 }
 441
 442 #ifndef QT_NO_NETWORKPROXY
 443 /*!
 444   * Returns the currently configured proxy
 445  */
 446 QNetworkProxy QWebSocket::proxy() const
 447 {
 448         return d_ptr->proxy();
 449 }
 450
 451 /*!
 452   Sets the proxy to \a networkProxy
 453  */
 454 void QWebSocket::setProxy(const QNetworkProxy &networkProxy)
 455 {
 456         d_ptr->setProxy(networkProxy);
 457 }
 458 #endif
 459
 460 /*!
 461  * Returns the size in bytes of the readbuffer that is used by the socket.
 462  */
 463 qint64 QWebSocket::readBufferSize() const
 464 {
 465         return d_ptr->readBufferSize();
 466 }
 467
 468 /*!
 469   Sets the proxy to \a networkProxy
 470  */
 471 void QWebSocket::setProxy(const QNetworkProxy &networkProxy)
 472 {
 473         d_ptr->setProxy(networkProxy);
 474 }
 475
 476 /**
 477         Sets the size of WebSocket's internal read buffer to be size bytes.
 478         If the buffer size is limited to a certain size, WebSocket won't buffer more than this size of data.
 479         Exceptionally, a buffer size of 0 means that the read buffer is unlimited and all incoming data is buffered. This is the default.
 480         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.
 481         \sa readBufferSize() and read().
 482 */
 483 void QWebSocket::setReadBufferSize(qint64 size)
 484 {
 485         d_ptr->setReadBufferSize(size);
 486 }
 487
 488 /*!
 489         Sets the given \a option to the value described by \a value.
 490         \sa socketOption().
 491 */
 492 void QWebSocket::setSocketOption(QAbstractSocket::SocketOption option, const QVariant &value)
 493 {
 494         d_ptr->setSocketOption(option, value);
 495 }
 496
 497 /*!
 498         Returns the value of the option \a option.
 499         \sa setSocketOption().
 500 */
 501 QVariant QWebSocket::socketOption(QAbstractSocket::SocketOption option)
 502 {
 503         return d_ptr->socketOption(option);
 504 }
 505
 506 /*!
 507   Returns true if the WebSocket is valid.
 508  */
 509 bool QWebSocket::isValid()
 510 {
 511         return d_ptr->isValid();
 512 }
 513
 514 QT_END_NAMESPACE