1 /****************************************************************************
3 ** Copyright (C) 2014 Kurt Pattyn <pattyn.kurt@gmail.com>.
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the QtWebSockets module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL21$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
26 ** In addition, as a special exception, Digia gives you certain additional
27 ** rights. These rights are described in the Digia Qt LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
32 ****************************************************************************/
35 \class QWebSocketServer
37 \inmodule QtWebSockets
39 \brief Implements a WebSocket-based server.
41 It is modeled after QTcpServer, and behaves the same. So, if you know how to use QTcpServer,
42 you know how to use QWebSocketServer.
43 This class makes it possible to accept incoming WebSocket connections.
44 You can specify the port or have QWebSocketServer pick one automatically.
45 You can listen on a specific address or on all the machine's addresses.
46 Call listen() to have the server listen for incoming connections.
48 The newConnection() signal is then emitted each time a client connects to the server.
49 Call nextPendingConnection() to accept the pending connection as a connected QWebSocket.
50 The function returns a pointer to a QWebSocket in QAbstractSocket::ConnectedState that you can
51 use for communicating with the client.
53 If an error occurs, serverError() returns the type of error, and errorString() can be called
54 to get a human readable description of what happened.
56 When listening for connections, the address and port on which the server is listening are
57 available as serverAddress() and serverPort().
59 Calling close() makes QWebSocketServer stop listening for incoming connections.
61 QWebSocketServer currently does not support
62 \l {http://tools.ietf.org/html/rfc6455#page-39} {extensions} and
63 \l {http://tools.ietf.org/html/rfc6455#page-12} {subprotocols}.
65 \note When working with self-signed certificates, FireFox currently has a
66 \l {https://bugzilla.mozilla.org/show_bug.cgi?id=594502} {bug} that prevents it to
67 connect to a secure WebSocket server. To work around this problem, first browse to the
68 secure WebSocket server using HTTPS. FireFox will indicate that the certificate is invalid.
69 From here on, the certificate can be added to the exceptions. After this, the secure WebSockets
70 connection should work.
72 QWebSocketServer only supports version 13 of the WebSocket protocol, as outlined in RFC 6455.
74 \sa {WebSocket Server Example}, QWebSocket
78 \page echoserver.html example
79 \title WebSocket server example
80 \brief A sample WebSocket server echoing back messages sent to it.
83 The echoserver example implements a WebSocket server that echoes back everything that is sent
86 We start by creating a QWebSocketServer (`new QWebSocketServer()`). After the creation, we listen
87 on all local network interfaces (`QHostAddress::Any`) on the specified \a port.
88 \snippet echoserver/echoserver.cpp constructor
89 If listening is successful, we connect the `newConnection()` signal to the slot
91 The `newConnection()` signal will be thrown whenever a new WebSocket client is connected to our
94 \snippet echoserver/echoserver.cpp onNewConnection
95 When a new connection is received, the client QWebSocket is retrieved (`nextPendingConnection()`),
96 and the signals we are interested in are connected to our slots
97 (`textMessageReceived()`, `binaryMessageReceived()` and `disconnected()`).
98 The client socket is remembered in a list, in case we would like to use it later
99 (in this example, nothing is done with it).
101 \snippet echoserver/echoserver.cpp processTextMessage
102 Whenever `processTextMessage()` is triggered, we retrieve the sender, and if valid, send back the
103 original message (`sendTextMessage()`).
104 The same is done with binary messages.
105 \snippet echoserver/echoserver.cpp processBinaryMessage
106 The only difference is that the message now is a QByteArray instead of a QString.
108 \snippet echoserver/echoserver.cpp socketDisconnected
109 Whenever a socket is disconnected, we remove it from the clients list and delete the socket.
110 Note: it is best to use `deleteLater()` to delete the socket.
114 \fn void QWebSocketServer::acceptError(QAbstractSocket::SocketError socketError)
115 This signal is emitted when the acceptance of a new connection results in an error.
116 The \a socketError parameter describes the type of error that occurred.
118 \sa pauseAccepting(), resumeAccepting()
122 \fn void QWebSocketServer::serverError(QWebSocketProtocol::CloseCode closeCode)
123 This signal is emitted when an error occurs during the setup of a WebSocket connection.
124 The \a closeCode parameter describes the type of error that occurred
130 \fn void QWebSocketServer::newConnection()
131 This signal is emitted every time a new connection is available.
133 \sa hasPendingConnections(), nextPendingConnection()
137 \fn void QWebSocketServer::closed()
138 This signal is emitted when the server closed its connection.
144 \fn void QWebSocketServer::originAuthenticationRequired(QWebSocketCorsAuthenticator *authenticator)
145 This signal is emitted when a new connection is requested.
146 The slot connected to this signal should indicate whether the origin
147 (which can be determined by the origin() call) is allowed in the \a authenticator object
148 (by issuing \l{QWebSocketCorsAuthenticator::}{setAllowed()}).
150 If no slot is connected to this signal, all origins will be accepted by default.
152 \note It is not possible to use a QueuedConnection to connect to
153 this signal, as the connection will always succeed.
157 \fn void QWebSocketServer::peerVerifyError(const QSslError &error)
159 QWebSocketServer can emit this signal several times during the SSL handshake,
160 before encryption has been established, to indicate that an error has
161 occurred while establishing the identity of the peer. The \a error is
162 usually an indication that QWebSocketServer is unable to securely identify the
165 This signal provides you with an early indication when something is wrong.
166 By connecting to this signal, you can manually choose to tear down the
167 connection from inside the connected slot before the handshake has
168 completed. If no action is taken, QWebSocketServer will proceed to emitting
169 QWebSocketServer::sslErrors().
175 \fn void QWebSocketServer::sslErrors(const QList<QSslError> &errors)
177 QWebSocketServer emits this signal after the SSL handshake to indicate that one
178 or more errors have occurred while establishing the identity of the
179 peer. The errors are usually an indication that QWebSocketServer is unable to
180 securely identify the peer. Unless any action is taken, the connection
181 will be dropped after this signal has been emitted.
183 \a errors contains one or more errors that prevent QSslSocket from
184 verifying the identity of the peer.
186 \sa peerVerifyError()
190 \enum QWebSocketServer::SslMode
191 Indicates whether the server operates over wss (SecureMode) or ws (NonSecureMode)
193 \value SecureMode The server operates in secure mode (over wss)
194 \value NonSecureMode The server operates in non-secure mode (over ws)
197 #include "qwebsocketprotocol.h"
198 #include "qwebsocket.h"
199 #include "qwebsocketserver.h"
200 #include "qwebsocketserver_p.h"
202 #include <QtNetwork/QTcpServer>
203 #include <QtNetwork/QTcpSocket>
204 #include <QtNetwork/QNetworkProxy>
207 #include <QtNetwork/QSslConfiguration>
213 Constructs a new QWebSocketServer with the given \a serverName.
214 The \a serverName will be used in the HTTP handshake phase to identify the server.
215 It can be empty, in which case an empty server name will be sent to the client.
216 The \a secureMode parameter indicates whether the server operates over wss (\l{SecureMode})
217 or over ws (\l{NonSecureMode}).
219 \a parent is passed to the QObject constructor.
221 QWebSocketServer::QWebSocketServer(const QString &serverName, SslMode secureMode,
223 QObject(*(new QWebSocketServerPrivate(serverName,
225 (secureMode == SecureMode) ?
226 QWebSocketServerPrivate::SecureMode :
227 QWebSocketServerPrivate::NonSecureMode,
229 QWebSocketServerPrivate::NonSecureMode,
236 Q_D(QWebSocketServer);
241 Destroys the QWebSocketServer object. If the server is listening for connections,
242 the socket is automatically closed.
243 Any client \l{QWebSocket}s that are still queued are closed and deleted.
247 QWebSocketServer::~QWebSocketServer()
252 Closes the server. The server will no longer listen for incoming connections.
254 void QWebSocketServer::close()
256 Q_D(QWebSocketServer);
261 Returns a human readable description of the last error that occurred.
262 If no error occurred, an empty string is returned.
266 QString QWebSocketServer::errorString() const
268 Q_D(const QWebSocketServer);
269 return d->errorString();
273 Returns true if the server has pending connections; otherwise returns false.
275 \sa nextPendingConnection(), setMaxPendingConnections()
277 bool QWebSocketServer::hasPendingConnections() const
279 Q_D(const QWebSocketServer);
280 return d->hasPendingConnections();
284 Returns true if the server is currently listening for incoming connections;
285 otherwise returns false. If listening fails, error() will return the reason.
287 \sa listen(), error()
289 bool QWebSocketServer::isListening() const
291 Q_D(const QWebSocketServer);
292 return d->isListening();
296 Tells the server to listen for incoming connections on address \a address and port \a port.
297 If \a port is 0, a port is chosen automatically.
298 If \a address is QHostAddress::Any, the server will listen on all network interfaces.
300 Returns true on success; otherwise returns false.
304 bool QWebSocketServer::listen(const QHostAddress &address, quint16 port)
306 Q_D(QWebSocketServer);
307 return d->listen(address, port);
311 Returns the maximum number of pending accepted connections. The default is 30.
313 \sa setMaxPendingConnections(), hasPendingConnections()
315 int QWebSocketServer::maxPendingConnections() const
317 Q_D(const QWebSocketServer);
318 return d->maxPendingConnections();
322 Returns the next pending connection as a connected QWebSocket object.
323 QWebSocketServer does not take ownership of the returned QWebSocket object.
324 It is up to the caller to delete the object explicitly when it will no longer be used,
325 otherwise a memory leak will occur.
326 Q_NULLPTR is returned if this function is called when there are no pending connections.
328 Note: The returned QWebSocket object cannot be used from another thread.
330 \sa hasPendingConnections()
332 QWebSocket *QWebSocketServer::nextPendingConnection()
334 Q_D(QWebSocketServer);
335 return d->nextPendingConnection();
339 Pauses incoming new connections. Queued connections will remain in queue.
340 \sa resumeAccepting()
342 void QWebSocketServer::pauseAccepting()
344 Q_D(QWebSocketServer);
348 #ifndef QT_NO_NETWORKPROXY
350 Returns the network proxy for this server. By default QNetworkProxy::DefaultProxy is used.
354 QNetworkProxy QWebSocketServer::proxy() const
356 Q_D(const QWebSocketServer);
361 Sets the explicit network proxy for this server to \a networkProxy.
363 To disable the use of a proxy, use the QNetworkProxy::NoProxy proxy type:
366 server->setProxy(QNetworkProxy::NoProxy);
371 void QWebSocketServer::setProxy(const QNetworkProxy &networkProxy)
373 Q_D(QWebSocketServer);
374 d->setProxy(networkProxy);
380 Sets the SSL configuration for the QWebSocketServer to \a sslConfiguration.
381 This method has no effect if QWebSocketServer runs in non-secure mode
382 (QWebSocketServer::NonSecureMode).
384 \sa sslConfiguration(), SslMode
386 void QWebSocketServer::setSslConfiguration(const QSslConfiguration &sslConfiguration)
388 Q_D(QWebSocketServer);
389 d->setSslConfiguration(sslConfiguration);
393 Returns the SSL configuration used by the QWebSocketServer.
394 If the server is not running in secure mode (QWebSocketServer::SecureMode),
395 this method returns QSslConfiguration::defaultConfiguration().
397 \sa setSslConfiguration(), SslMode, QSslConfiguration::defaultConfiguration()
399 QSslConfiguration QWebSocketServer::sslConfiguration() const
401 Q_D(const QWebSocketServer);
402 return d->sslConfiguration();
407 Resumes accepting new connections.
410 void QWebSocketServer::resumeAccepting()
412 Q_D(QWebSocketServer);
413 d->resumeAccepting();
417 Sets the server name that will be used during the HTTP handshake phase to the given
419 The \a serverName can be empty, in which case an empty server name will be sent to the client.
420 Existing connected clients will not be notified of this change, only newly connecting clients
421 will see this new name.
423 void QWebSocketServer::setServerName(const QString &serverName)
425 Q_D(QWebSocketServer);
426 d->setServerName(serverName);
430 Returns the server name that is used during the http handshake phase.
432 QString QWebSocketServer::serverName() const
434 Q_D(const QWebSocketServer);
435 return d->serverName();
439 Returns the server's address if the server is listening for connections; otherwise returns
442 \sa serverPort(), listen()
444 QHostAddress QWebSocketServer::serverAddress() const
446 Q_D(const QWebSocketServer);
447 return d->serverAddress();
451 Returns the secure mode the server is running in.
453 \sa QWebSocketServer(), SslMode
455 QWebSocketServer::SslMode QWebSocketServer::secureMode() const
458 Q_D(const QWebSocketServer);
459 return (d->secureMode() == QWebSocketServerPrivate::SecureMode) ?
460 QWebSocketServer::SecureMode : QWebSocketServer::NonSecureMode;
462 return QWebSocketServer::NonSecureMode;
467 Returns an error code for the last error that occurred.
468 If no error occurred, QWebSocketProtocol::CloseCodeNormal is returned.
472 QWebSocketProtocol::CloseCode QWebSocketServer::error() const
474 Q_D(const QWebSocketServer);
475 return d->serverError();
479 Returns the server's port if the server is listening for connections; otherwise returns 0.
481 \sa serverAddress(), listen()
483 quint16 QWebSocketServer::serverPort() const
485 Q_D(const QWebSocketServer);
486 return d->serverPort();
490 Returns a URL clients can use to connect to this server if the server is listening for connections.
491 Otherwise an invalid URL is returned.
493 \sa serverPort(), serverAddress(), listen()
495 QUrl QWebSocketServer::serverUrl() const
499 if (!isListening()) {
503 switch (secureMode()) {
505 url.setScheme(QStringLiteral("ws"));
509 url.setScheme(QStringLiteral("wss"));
514 url.setPort(serverPort());
516 if (serverAddress() == QHostAddress(QHostAddress::Any)) {
517 // NOTE: On Windows at least, clients cannot connect to QHostAddress::Any
518 // so in that case we always return LocalHost instead.
519 url.setHost(QHostAddress(QHostAddress::LocalHost).toString());
521 url.setHost(serverAddress().toString());
528 Sets the maximum number of pending accepted connections to \a numConnections.
529 WebSocketServer will accept no more than \a numConnections incoming connections before
530 nextPendingConnection() is called.
531 By default, the limit is 30 pending connections.
533 QWebSocketServer will emit the error() signal with
534 the QWebSocketProtocol::CloseCodeAbnormalDisconnection close code
535 when the maximum of connections has been reached.
536 The WebSocket handshake will fail and the socket will be closed.
538 \sa maxPendingConnections(), hasPendingConnections()
540 void QWebSocketServer::setMaxPendingConnections(int numConnections)
542 Q_D(QWebSocketServer);
543 d->setMaxPendingConnections(numConnections);
547 Sets the socket descriptor this server should use when listening for incoming connections to
550 Returns true if the socket is set successfully; otherwise returns false.
551 The socket is assumed to be in listening state.
553 \sa socketDescriptor(), isListening()
555 bool QWebSocketServer::setSocketDescriptor(int socketDescriptor)
557 Q_D(QWebSocketServer);
558 return d->setSocketDescriptor(socketDescriptor);
562 Returns the native socket descriptor the server uses to listen for incoming instructions,
563 or -1 if the server is not listening.
564 If the server is using QNetworkProxy, the returned descriptor may not be usable with
565 native socket functions.
567 \sa setSocketDescriptor(), isListening()
569 int QWebSocketServer::socketDescriptor() const
571 Q_D(const QWebSocketServer);
572 return d->socketDescriptor();
576 Returns a list of WebSocket versions that this server is supporting.
578 QList<QWebSocketProtocol::Version> QWebSocketServer::supportedVersions() const
580 Q_D(const QWebSocketServer);
581 return d->supportedVersions();