/*!
\class QWebSocket
- \brief The class QWebSocket implements a TCP socket that talks the websocket protocol.
+
+ \inmodule QWebSockets
+ \brief 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 (see http://tools.ietf.org/html/rfc6455).
This class was modeled after QAbstractSocket.
- \ref echoclient
+ \sa QAbstractSocket, QTcpSocket
- \author Kurt Pattyn (pattyn.kurt@gmail.com)
+ \sa echoclient.html
*/
+
/*!
- \page echoclient QWebSocket client example
- \brief A sample websocket client that sends a message and displays the message that it receives back.
+ \page echoclient.html example
+ \title QWebSocket client example
+ \brief A sample websocket client that sends a message and displays the message that it receives back.
- \section Description
- The EchoClient example implements a web socket client that sends a message to a websocket server and dumps the answer that it gets back.
- This example should ideally be used with the EchoServer example.
- \section Code
- We start by connecting to the `connected()` signal.
- \snippet echoclient.cpp constructor
- After the connection, we open the socket to the given \a url.
+ \section1 Description
+ The EchoClient example implements a web socket client that sends a message to a websocket server and dumps the answer that it gets back.
+ This example should ideally be used with the EchoServer example.
+ \section1 Code
+ We start by connecting to the `connected()` signal.
+ \snippet echoclient.cpp constructor
+ After the connection, we open the socket to the given \a url.
- \snippet echoclient.cpp onConnected
- When the client is connected successfully, we connect to the `onTextMessageReceived()` signal, and send out "Hello, world!".
- If connected with the EchoServer, we will receive the same message back.
+ \snippet echoclient.cpp onConnected
+ When the client is connected successfully, we connect to the `onTextMessageReceived()` signal, and send out "Hello, world!".
+ If connected with the EchoServer, we will receive the same message back.
- \snippet echoclient.cpp onTextMessageReceived
- Whenever a message is received, we write it out.
+ \snippet echoclient.cpp onTextMessageReceived
+ Whenever a message is received, we write it out.
*/
/*!
\fn void QWebSocket::stateChanged(QAbstractSocket::SocketState state);
This signal is emitted whenever QWebSocket's state changes.
- The \a socketState parameter is the new state.
+ The \a state parameter is the new state.
QAbstractSocket::SocketState is not a registered metatype, so for queued
connections, you will have to register it with Q_REGISTER_METATYPE() and
This signal can be used to process large messages frame by frame, instead of waiting for the complete
message to arrive.
- \sa binaryFrameReceived(QByteArray, bool), textMessageReceived(QString)
+ \sa binaryFrameReceived()
*/
/*!
\fn void QWebSocket::binaryFrameReceived(QByteArray frame, bool isLastFrame);
This signal can be used to process large messages frame by frame, instead of waiting for the complete
message to arrive.
- \sa textFrameReceived(QString, bool), binaryMessageReceived(QByteArray)
+ \sa textFrameReceived()
*/
/*!
\fn void QWebSocket::textMessageReceived(QString message);
This signal is emitted whenever a text message is received. The \a message contains the received text.
- \sa textFrameReceived(QString, bool), binaryMessageReceived(QByteArray)
+ \sa binaryMessageReceived()
*/
/*!
\fn void QWebSocket::binaryMessageReceived(QByteArray message);
This signal is emitted whenever a binary message is received. The \a message contains the received bytes.
- \sa binaryFrameReceived(QByteArray, bool), textMessageReceived(QString)
+ \sa textMessageReceived()
*/
/*!
\fn void QWebSocket::error(QAbstractSocket::SocketError error);
- This signal is emitted after an error occurred. The \a socketError
+ This signal is emitted after an error occurred. The \a error
parameter describes the type of error that occurred.
QAbstractSocket::SocketError is not a registered metatype, so for queued
\sa error(), errorString()
*/
/*!
- \fn void QWebSocket::pong(quint64 elapsedTime)
+ \fn void QWebSocket::pong(quint64 elapsedTime)
- Emitted when a pong message is received in reply to a previous ping.
+ Emitted when a pong message is received in reply to a previous ping.
+ \a elapsedTime contains the roundtrip time in milliseconds
- \sa ping()
+ \sa ping()
*/
#include "qwebsocket.h"
#include "qwebsocket_p.h"
/*!
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 WebSocket to start sending buffered data immediately.
+ 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 WebSocket will start sending data automatically once control goes back to the event loop.
+ 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.
In the absence of an event loop, call waitForBytesWritten() instead.
-
- \sa send() and waitForBytesWritten().
*/
bool QWebSocket::flush()
{
}
/*!
- * Sends the given \a message over the socket as a text message and returns the number of bytes actually sent.
- * \param message Text message to be sent. Must be '\0' terminated.
- * \return The number of bytes actually sent.
- * \sa write(const QString &message) and write(const char *message, qint64 maxSize)
+ Sends the given \a message over the socket as a text message and returns the number of bytes actually sent.
+ \a message must be '\\0' terminated.
*/
qint64 QWebSocket::write(const char *message)
{
}
/*!
- * 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.
- * \param message Text message to be sent.
- * \return The number of bytes actually sent.
- * \sa write(const QString &message) and write(const char *message)
+ 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.
*/
qint64 QWebSocket::write(const char *message, qint64 maxSize)
{
/*!
\brief Sends the given \a message over the socket as a text message and returns the number of bytes actually sent.
- \param message The message to be sent
- \return The number of bytes actually sent.
- \sa write(const char *message) and write(const char *message, qint64 maxSize)
*/
qint64 QWebSocket::write(const QString &message)
{
return d_ptr->write(message);
}
-/**
- * @brief Sends the given \a data over the socket as a binary message and returns the number of bytes actually sent.
- * @param data The binary data to be sent.
- * @return The number of bytes actually sent.
+/*!
+ \brief Sends the given \a data over the socket as a binary message and returns the number of bytes actually sent.
*/
qint64 QWebSocket::write(const QByteArray &data)
{
}
/*!
- * \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.
- * \param closeCode The QWebSocketProtocol::CloseCode indicating the reason to close.
- * \param reason A string describing the error more in detail
+ \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.
+ The \a closeCode is a QWebSocketProtocol::CloseCode indicating the reason to close, and
+ \a reason describes the reason of the closure more in detail
*/
void QWebSocket::close(QWebSocketProtocol::CloseCode closeCode, QString reason)
{
}
/*!
- * \brief Opens a websocket connection using the given \a url.
- * If \a mask is true, all frames will be masked; this is only necessary for client side sockets; servers should never mask
- * \param url The url to connect to
- * \param mask When true, all frames are masked
- * \note A client socket must *always* mask its frames; servers may *never* mask its frames
+ \brief Opens a websocket connection using the given \a url.
+ If \a mask is true, all frames will be masked; this is only necessary for client side sockets; servers should never mask
+ \note A client socket must *always* mask its frames; servers may *never* mask its frames
*/
void QWebSocket::open(const QUrl &url, bool mask)
{
}
/*!
- * \brief Pings the server to indicate that the connection is still alive.
- *
- * \sa pong()
+ \brief Pings the server to indicate that the connection is still alive.
+
+ \sa pong()
*/
void QWebSocket::ping()
{
}
/*!
- * \brief Returns the version the socket is currently using
+ \brief Returns the version the socket is currently using
*/
QWebSocketProtocol::Version QWebSocket::version()
{
return d_ptr->version();
}
-/**
- * @brief Returns the name of the resource currently accessed.
+/*!
+ \brief Returns the name of the resource currently accessed.
*/
QString QWebSocket::resourceName()
{
}
/*!
- * \brief Returns the url the socket is connected to or will connect to.
+ \brief Returns the url the socket is connected to or will connect to.
*/
QUrl QWebSocket::requestUrl()
{
}
/*!
- Returns the current origin
+ \brief Returns the current origin
*/
QString QWebSocket::origin()
{
}
/*!
- Returns the currently used protocol.
+ \brief Returns the currently used protocol.
*/
QString QWebSocket::protocol()
{
}
/*!
- Returns the currently used extension.
+ \brief Returns the currently used extension.
*/
QString QWebSocket::extension()
{
}
/*!
- Returns the current state of the socket
+ \brief Returns the current state of the socket
*/
QAbstractSocket::SocketState QWebSocket::state() const
{
return d_ptr->state();
}
-/**
- @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.
+/*!
+ \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.
The following example waits up to one second for a connection to be established:
~~~{.cpp}
@note This function may wait slightly longer than msecs, depending on the time it takes to complete the host lookup.
@note Multiple calls to this functions do not accumulate the time. If the function times out, the connecting process will be aborted.
- \param msecs The number of milliseconds to wait before a time out occurs; when -1, this function will block until the socket is connected.
-
\sa connected(), open(), state()
*/
bool QWebSocket::waitForConnected(int msecs)
Waits \a msecs for the socket to be disconnected.
If the socket was successfully disconnected within time, this method returns true.
Otherwise false is returned.
-
- \param msecs The number of milliseconds to wait before a time out occurs; when -1, this function will block until the socket is disconnected.
+ When \a msecs is -1, this function will block until the socket is disconnected.
\sa close(), state()
*/
}
/*!
- Returns the local address
+ Returns the local address
*/
QHostAddress QWebSocket::localAddress() const
{
}
/*!
- Returns the local port
+ Returns the local port
*/
quint16 QWebSocket::localPort() const
{
}
/*!
- Returns the pause mode of this socket
+ Returns the pause mode of this socket
*/
QAbstractSocket::PauseModes QWebSocket::pauseMode() const
{
}
/*!
- Returns the peer address
+ Returns the peer address
*/
QHostAddress QWebSocket::peerAddress() const
{
}
/*!
- Returns the peerName
+ Returns the peerName
*/
QString QWebSocket::peerName() const
{
}
/*!
- Returns the peerport
+ Returns the peerport
*/
quint16 QWebSocket::peerPort() const
{
#ifndef QT_NO_NETWORKPROXY
/*!
- * Returns the currently configured proxy
+ Returns the currently configured proxy
*/
QNetworkProxy QWebSocket::proxy() const
{
}
/*!
- Sets the proxy to \a networkProxy
+ Sets the proxy to \a networkProxy
*/
void QWebSocket::setProxy(const QNetworkProxy &networkProxy)
{
#endif
/*!
- * Returns the size in bytes of the readbuffer that is used by the socket.
+ Returns the size in bytes of the readbuffer that is used by the socket.
*/
qint64 QWebSocket::readBufferSize() const
{
The only notification currently supported is sslErrors().
Calling this method if the socket is not paused results in undefined behavior.
- \sa pauseMode() and setPauseMode()
+ \sa pauseMode(), setPauseMode()
*/
void QWebSocket::resume()
{
}
/*!
- Controls whether to pause upon receiving a notification. The \a 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.
+ Controls whether to pause upon receiving a notification. The \a 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.
- \sa pauseMode() and resume()
+ \sa pauseMode(), resume()
*/
void QWebSocket::setPauseMode(QAbstractSocket::PauseModes pauseMode)
{
d_ptr->setPauseMode(pauseMode);
}
-/**
- Sets the size of WebSocket's internal read buffer to be size bytes.
- If the buffer size is limited to a certain size, WebSocket won't buffer more than this size of data.
+/*!
+ Sets the size of QWebSocket's internal read buffer to be \a 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 (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.
- \sa readBufferSize() and read().
+ \sa readBufferSize()
*/
void QWebSocket::setReadBufferSize(qint64 size)
{
/*!
Sets the given \a option to the value described by \a value.
- \sa socketOption().
+ \sa socketOption()
*/
void QWebSocket::setSocketOption(QAbstractSocket::SocketOption option, const QVariant &value)
{
/*!
Returns the value of the option \a option.
- \sa setSocketOption().
+ \sa setSocketOption()
*/
QVariant QWebSocket::socketOption(QAbstractSocket::SocketOption option)
{
}
/*!
- Returns true if the WebSocket is valid.
+ Returns true if the QWebSocket is valid.
*/
bool QWebSocket::isValid()
{
/*!
- \class WebSocketServer
+ \class QWebSocketServer
- The WebSocketServer class provides a websocket-based server.
- It is modeled after QTcpServer, and behaves the same. So, if you know how to use QTcpServer, you know how to use WebSocketServer.\n
- This class makes it possible to accept incoming websocket connections.\n
- You can specify the port or have WebSocketServer pick one automatically.\n
- You can listen on a specific address or on all the machine's addresses.\n
- Call listen() to have the server listen for incoming connections.\n
+ \inmodule QWebSockets
- The newConnection() signal is then emitted each time a client connects to the server.\n
- Call nextPendingConnection() to accept the pending connection as a connected WebSocket.
- The function returns a pointer to a WebSocket in QAbstractSocket::ConnectedState that you can use for communicating with the client.\n
- If an error occurs, serverError() returns the type of error, and errorString() can be called to get a human readable description of what happened.\n
- When listening for connections, the address and port on which the server is listening are available as serverAddress() and serverPort().\n
- Calling close() makes WebSocketServer stop listening for incoming connections.\n
- Although WebSocketServer is mostly designed for use with an event loop, it's possible to use it without one. In that case, you must use waitForNewConnection(), which blocks until either a connection is available or a timeout expires.
+ \brief Implements a websocket-based server.
- \ref echoserver
+ It is modeled after QTcpServer, and behaves the same. So, if you know how to use QTcpServer, you know how to use QWebSocketServer.
+ This class makes it possible to accept incoming websocket connections.
+ You can specify the port or have QWebSocketServer pick one automatically.
+ You can listen on a specific address or on all the machine's addresses.
+ Call listen() to have the server listen for incoming connections.
- \author Kurt Pattyn (pattyn.kurt@gmail.com)
+ The newConnection() signal is then emitted each time a client connects to the server.
+ Call nextPendingConnection() to accept the pending connection as a connected QWebSocket.
+ The function returns a pointer to a QWebSocket in QAbstractSocket::ConnectedState that you can use for communicating with the client.
+ If an error occurs, serverError() returns the type of error, and errorString() can be called to get a human readable description of what happened.
+ When listening for connections, the address and port on which the server is listening are available as serverAddress() and serverPort().
+ Calling close() makes QWebSocketServer stop listening for incoming connections.
+ Although QWebSocketServer is mostly designed for use with an event loop, it's possible to use it without one. In that case, you must use waitForNewConnection(), which blocks until either a connection is available or a timeout expires.
- \sa WebSocket
+ \sa echoserver.html
+
+ \sa QWebSocket
*/
/*!
- \page echoserver WebSocket server example
+ \page echoserver.html example
+ \title WebSocket server example
\brief A sample websocket server echoing back messages sent to it.
- \section Description
+ \section1 Description
The echoserver example implements a web socket server that echoes back everything that is sent to it.
- \section Code
- We start by creating a WebSocketServer (`new WebSocketServer()`). After the creation, we listen on all local network interfaces (`QHostAddress::Any`) on the specified \a port.
+ \section1 Code
+ We start by creating a QWebSocketServer (`new QWebSocketServer()`). After the creation, we listen on all local network interfaces (`QHostAddress::Any`) on the specified \a port.
\snippet echoserver.cpp constructor
If listening is successful, we connect the `newConnection()` signal to the slot `onNewConnection()`.
The `newConnection()` signal will be thrown whenever a new web socket client is connected to our server.
\snippet echoserver.cpp onNewConnection
- When a new connection is received, the client WebSocket is retrieved (`nextPendingConnection()`), and the signals we are interested in
+ When a new connection is received, the client QWebSocket is retrieved (`nextPendingConnection()`), and the signals we are interested in
are connected to our slots (`textMessageReceived()`, `binaryMessageReceived()` and `disconnected()`).
The client socket is remembered in a list, in case we would like to use it later (in this example, nothing is done with it).
*/
/*!
- \fn void WebSocketServer::acceptError(QAbstractSocket::SocketError socketError)
+ \fn void QWebSocketServer::acceptError(QAbstractSocket::SocketError socketError)
This signal is emitted when accepting a new connection results in an error.
The \a socketError parameter describes the type of error that occurred
- \sa pauseAccepting() and resumeAccepting().
+ \sa pauseAccepting(), resumeAccepting()
*/
/*!
- \fn void WebSocketServer::newConnection()
+ \fn void QWebSocketServer::newConnection()
This signal is emitted every time a new connection is available.
- \sa hasPendingConnections() and nextPendingConnection().
+ \sa hasPendingConnections(), nextPendingConnection()
*/
#include <QTcpServer>
QT_BEGIN_NAMESPACE
/*!
- Constructs a new WebSocketServer.
+ Constructs a new WebSocketServer with the given \a serverName.
+ The \a serverName will be used in the http handshake phase to identify the server.
\a parent is passed to the QObject constructor.
*/
/*!
Returns a human readable description of the last error that occurred.
- \sa serverError().
+ \sa serverError()
*/
QString QWebSocketServer::errorString() const
{
/*!
Returns true if the server has pending connections; otherwise returns false.
- \sa nextPendingConnection() and setMaxPendingConnections().
+ \sa nextPendingConnection(), setMaxPendingConnections()
*/
bool QWebSocketServer::hasPendingConnections() const
{
/*!
Returns true if the server is currently listening for incoming connections; otherwise returns false.
- \sa listen().
+ \sa listen()
*/
bool QWebSocketServer::isListening() const
{
/*!
Tells the server to listen for incoming connections on address \a address and port \a port.
- If \a port is 0, a port is chosen automatically.\n
+ If \a port is 0, a port is chosen automatically.
If \a address is QHostAddress::Any, the server will listen on all network interfaces.
Returns true on success; otherwise returns false.
- \sa isListening().
+ \sa isListening()
*/
bool QWebSocketServer::listen(const QHostAddress &address, quint16 port)
{
/*!
Returns the maximum number of pending accepted connections. The default is 30.
- \sa setMaxPendingConnections() and hasPendingConnections().
+ \sa setMaxPendingConnections(), hasPendingConnections()
*/
int QWebSocketServer::maxPendingConnections() const
{
Note: The returned WebSocket object cannot be used from another thread..
- \sa hasPendingConnections().
+ \sa hasPendingConnections()
*/
QWebSocket *QWebSocketServer::nextPendingConnection()
{
/*!
Returns the network proxy for this socket. By default QNetworkProxy::DefaultProxy is used.
- \sa setProxy().
+ \sa setProxy()
*/
QNetworkProxy QWebSocketServer::proxy() const
{
server->setProxy(QNetworkProxy::NoProxy);
\endcode
- \sa proxy().
+ \sa proxy()
*/
void QWebSocketServer::setProxy(const QNetworkProxy &networkProxy)
{
/*!
Returns the server's address if the server is listening for connections; otherwise returns QHostAddress::Null.
- \sa serverPort() and listen().
+ \sa serverPort(), listen()
*/
QHostAddress QWebSocketServer::serverAddress() const
{
/*!
Returns an error code for the last error that occurred.
- \sa errorString().
+ \sa errorString()
*/
QAbstractSocket::SocketError QWebSocketServer::serverError() const
{
/*!
Returns the server's port if the server is listening for connections; otherwise returns 0.
- \sa serverAddress() and listen().
+ \sa serverAddress(), listen()
*/
quint16 QWebSocketServer::serverPort() const
{
/*!
Sets the maximum number of pending accepted connections to \a numConnections.
- WebSocketServer will accept no more than \a numConnections incoming connections before nextPendingConnection() is called.\n
+ WebSocketServer will accept no more than \a numConnections incoming connections before nextPendingConnection() is called.
By default, the limit is 30 pending connections.
Clients may still able to connect after the server has reached its maximum number of pending connections (i.e., WebSocket can still emit the connected() signal). WebSocketServer will stop accepting the new connections, but the operating system may still keep them in queue.
- \sa maxPendingConnections() and hasPendingConnections().
+ \sa maxPendingConnections(), hasPendingConnections()
*/
void QWebSocketServer::setMaxPendingConnections(int numConnections)
{
/*!
Sets the socket descriptor this server should use when listening for incoming connections to \a socketDescriptor.
- Returns true if the socket is set successfully; otherwise returns false.\n
+ Returns true if the socket is set successfully; otherwise returns false.
The socket is assumed to be in listening state.
- \sa socketDescriptor() and isListening().
+ \sa socketDescriptor(), isListening()
*/
bool QWebSocketServer::setSocketDescriptor(int socketDescriptor)
{
Returns the native socket descriptor the server uses to listen for incoming instructions, or -1 if the server is not listening.
If the server is using QNetworkProxy, the returned descriptor may not be usable with native socket functions.
- \sa setSocketDescriptor() and isListening().
+ \sa setSocketDescriptor(), isListening()
*/
int QWebSocketServer::socketDescriptor() const
{
/*!
Waits for at most \a msec milliseconds or until an incoming connection is available.
Returns true if a connection is available; otherwise returns false.
- If the operation timed out and \a timedOut is not 0, \a *timedOut will be set to true.
+ If the operation timed out and \a timedOut is not 0, \a timedOut will be set to true.
\note This is a blocking function call.
\note Its use is disadvised in a single-threaded GUI application, since the whole application will stop responding until the function returns. waitForNewConnection() is mostly useful when there is no event loop available.
If \a msec is -1, this function will not time out.
- \sa hasPendingConnections() and nextPendingConnection().
+ \sa hasPendingConnections(), nextPendingConnection()
*/
bool QWebSocketServer::waitForNewConnection(int msec, bool *timedOut)
{
return d_ptr->supportedExtensions();
}
-//Checking on the origin does not make much sense when the server is accessed
-//via a non-browser client, as that client can set whatever origin header it likes
-//In case of a browser client, the server SHOULD check the validity of the origin
-//see http://tools.ietf.org/html/rfc6455#section-10
+/*!
+ This method checks if the given \a origin is allowed; it returns true when the \a origin is allowed, otherwise false.
+ It is supposed to be overriden by a subclass to filter out unwanted origins.
+ By default, every origin is accepted.
+
+ \note Checking on the origin does not make much sense when the server is accessed
+via a non-browser client, as that client can set whatever origin header it likes
+In case of a browser client, the server SHOULD check the validity of the origin.
+\sa http://tools.ietf.org/html/rfc6455#section-10
+*/
bool QWebSocketServer::isOriginAllowed(const QString &origin) const
{
Q_UNUSED(origin)
projects / contrib / qtwebsockets.git / commitdiff