summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKai Koehne <kai.koehne@theqtcompany.com>2016-04-07 09:52:29 +0200
committerKai Koehne <kai.koehne@theqtcompany.com>2016-04-07 12:46:21 +0000
commitbe4bfc5feeb61e97378bee325d36bb74f007fe04 (patch)
tree8b7fa16f684a7df6e8f5b927d32e4b4dea94e91a
parent3b128f9b45f4fafc305ff0c89cfc2cb665c856d5 (diff)
downloadqtwebsockets-be4bfc5feeb61e97378bee325d36bb74f007fe04.tar.gz
Doc: Add external-resources.qdoc
Also sanitize some linking, e.g. by referencing to the paper by title, not by link. Change-Id: I95482994ca569001a23a3beb0e3cbe6739f4ed77 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com> Reviewed-by: Topi Reiniƶ <topi.reinio@theqtcompany.com>
-rw-r--r--src/imports/qmlwebsockets/qqmlwebsocket.cpp3
-rw-r--r--src/websockets/doc/src/external-resources.qdoc106
-rw-r--r--src/websockets/doc/src/index.qdoc8
-rw-r--r--src/websockets/doc/src/overview.qdoc2
-rw-r--r--src/websockets/qdefaultmaskgenerator_p.cpp4
-rw-r--r--src/websockets/qmaskgenerator.cpp4
-rw-r--r--src/websockets/qwebsocket.cpp16
-rw-r--r--src/websockets/qwebsocketcorsauthenticator.cpp2
-rw-r--r--src/websockets/qwebsocketdataprocessor.cpp2
-rw-r--r--src/websockets/qwebsocketprotocol.cpp18
-rw-r--r--src/websockets/qwebsocketserver.cpp9
11 files changed, 136 insertions, 38 deletions
diff --git a/src/imports/qmlwebsockets/qqmlwebsocket.cpp b/src/imports/qmlwebsockets/qqmlwebsocket.cpp
index 82a5f9b..ef97413 100644
--- a/src/imports/qmlwebsockets/qqmlwebsocket.cpp
+++ b/src/imports/qmlwebsockets/qqmlwebsocket.cpp
@@ -42,8 +42,7 @@
WebSockets is a web technology providing full-duplex communications channels over a
single TCP connection.
- The WebSocket protocol was standardized by the IETF as
- \l {http://tools.ietf.org/html/rfc6455} {RFC 6455} in 2011.
+ The WebSocket protocol was standardized by the IETF as \l {RFC 6455} in 2011.
*/
/*!
diff --git a/src/websockets/doc/src/external-resources.qdoc b/src/websockets/doc/src/external-resources.qdoc
new file mode 100644
index 0000000..be49ded
--- /dev/null
+++ b/src/websockets/doc/src/external-resources.qdoc
@@ -0,0 +1,106 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \externalpage http://w2spconf.com/2011/papers/websocket.pdf
+ \title "Talking to Yourself for Fun and Profit" by Lin-Shung Huang et al
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/html/rfc6454
+ \title RFC 6454
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/html/rfc6455
+ \title RFC 6455
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/html/rfc6455#section-10
+ \title WebSocket Security Considerations
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/html/rfc6455#page-39
+ \title WebSocket Extensions
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/html/rfc6455#page-12
+ \title WebSocket Subprotocols
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76
+ \title hixie76
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-00
+ \title hybi-00
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/id/draft-ietf-hybi-thewebsocketprotocol-04.txt
+ \title hybi-04
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/id/draft-ietf-hybi-thewebsocketprotocol-05.txt
+ \title hybi-05
+*/
+
+/*!
+ \externalpage http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-07
+ \title hybi-07
+*/
+
+/*!
+ \externalpage https://github.com/google/pywebsocket/wiki/WebSocketProtocolSpec
+ \title pywebsocket's WebSocketProtocolSpec
+*/
+
+/*!
+ \externalpage http://autobahn.ws/testsuite/
+ \title Autobahn|Testsuite
+*/
+
+/*!
+ \externalpage http://autobahn.ws/testsuite/installation.html
+ \title Autobahn|Testsuite installation documentation
+*/
+
+/*!
+ \externalpage https://www.mozilla.org/firefox
+ \title Firefox
+*/
+
+/*!
+ \externalpage https://bugzilla.mozilla.org/show_bug.cgi?id=594502
+ \title Firefox bug 594502
+*/
diff --git a/src/websockets/doc/src/index.qdoc b/src/websockets/doc/src/index.qdoc
index e0f219c..9e1c40c 100644
--- a/src/websockets/doc/src/index.qdoc
+++ b/src/websockets/doc/src/index.qdoc
@@ -77,10 +77,10 @@
\page qtwebsockets-testing.html
\title Testing Qt WebSockets
- \l {http://autobahn.ws/testsuite/}{Autobahn|Testsuite}, a standard test
- suite for WebSocket Protocol (RFC 6455), can be used for testing the
- conformance of Qt WebSockets. Refer to Autobahn|Testsuite
- \l {http://autobahn.ws/testsuite/installation.html}{installation documentation}
+ \l {Autobahn|Testsuite}, a standard test
+ suite for WebSocket Protocol (\l{RFC 6455}), can be used for testing the
+ conformance of Qt WebSockets. Refer to
+ \l {Autobahn|Testsuite installation documentation}
to set up the test suite.
\include README testsuite
diff --git a/src/websockets/doc/src/overview.qdoc b/src/websockets/doc/src/overview.qdoc
index 3250828..eb9e429 100644
--- a/src/websockets/doc/src/overview.qdoc
+++ b/src/websockets/doc/src/overview.qdoc
@@ -106,6 +106,6 @@ WebSocket URL and receive data.
\section2 Related Information
\list
-\li \l {http://tools.ietf.org/html/rfc6455}{WebSocket RFC 6455}
+\li \l{RFC 6455}
\endlist
*/
diff --git a/src/websockets/qdefaultmaskgenerator_p.cpp b/src/websockets/qdefaultmaskgenerator_p.cpp
index 0992e3a..9a8ef30 100644
--- a/src/websockets/qdefaultmaskgenerator_p.cpp
+++ b/src/websockets/qdefaultmaskgenerator_p.cpp
@@ -37,11 +37,11 @@
\brief The QDefaultMaskGenerator class provides the default mask generator for QtWebSockets.
- The WebSockets specification as outlined in {http://tools.ietf.org/html/rfc6455}{RFC 6455}
+ The WebSockets specification as outlined in \l {RFC 6455}
requires that all communication from client to server must be masked. This is to prevent
malicious scripts to attack bad behaving proxies.
For more information about the importance of good masking,
- see \l {http://w2spconf.com/2011/papers/websocket.pdf}.
+ see \l {"Talking to Yourself for Fun and Profit" by Lin-Shung Huang et al}.
The default mask generator uses the cryptographically insecure qrand() function.
The best measure against attacks mentioned in the document above,
is to use QWebSocket over a secure connection (\e wss://).
diff --git a/src/websockets/qmaskgenerator.cpp b/src/websockets/qmaskgenerator.cpp
index cc53156..88baab6 100644
--- a/src/websockets/qmaskgenerator.cpp
+++ b/src/websockets/qmaskgenerator.cpp
@@ -39,11 +39,11 @@
\brief The QMaskGenerator class provides an abstract base for custom 32-bit mask generators.
- The WebSockets specification as outlined in \l {http://tools.ietf.org/html/rfc6455}{RFC 6455}
+ The WebSockets specification as outlined in \l {RFC 6455}
requires that all communication from client to server be masked. This is to prevent
malicious scripts from attacking badly behaving proxies.
For more information about the importance of good masking,
- see \l {http://w2spconf.com/2011/papers/websocket.pdf}.
+ see \l {"Talking to Yourself for Fun and Profit" by Lin-Shung Huang et al}.
By default QWebSocket uses the cryptographically insecure qrand() function.
The best measure against attacks mentioned in the document above,
is to use QWebSocket over a secure connection (\e wss://).
diff --git a/src/websockets/qwebsocket.cpp b/src/websockets/qwebsocket.cpp
index 0286196..52b5083 100644
--- a/src/websockets/qwebsocket.cpp
+++ b/src/websockets/qwebsocket.cpp
@@ -41,17 +41,17 @@
WebSockets is a web technology providing full-duplex communications channels over
a single TCP connection.
The WebSocket protocol was standardized by the IETF as
- \l {http://tools.ietf.org/html/rfc6455} {RFC 6455} in 2011.
+ \l {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
- \l {http://tools.ietf.org/html/rfc6455#page-39} {extensions} and
- \l {http://tools.ietf.org/html/rfc6455#page-12} {subprotocols}.
+ \l {WebSocket Extensions} and
+ \l {WebSocket Subprotocols}.
QWebSocket only supports version 13 of the WebSocket protocol, as outlined in
- \l {http://tools.ietf.org/html/rfc6455}{RFC 6455}.
+ \l {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
@@ -60,7 +60,7 @@
\warning To generate masks, this implementation of WebSockets uses the cryptographically
insecure qrand() function.
For more information about the importance of good masking,
- see \l {http://w2spconf.com/2011/papers/websocket.pdf}.
+ see \l {"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 (\e wss://).
In general, always be careful to not have 3rd party script access to
@@ -259,12 +259,12 @@ QT_BEGIN_NAMESPACE
* \brief Creates a new QWebSocket with the given \a origin,
* the \a version of the protocol to use and \a parent.
*
- * The \a origin of the client is as specified in \l {http://tools.ietf.org/html/rfc6454}{RFC 6454}.
+ * The \a origin of the client is as specified in \l {RFC 6454}.
* (The \a origin is not required for non-web browser clients
- * (see \l {http://tools.ietf.org/html/rfc6455}{RFC 6455})).
+ * (see \l {RFC 6455})).
* The \a origin may not contain new line characters, otherwise the connection will be
* aborted immediately during the handshake phase.
- * \note Currently only V13 (\l {http://tools.ietf.org/html/rfc6455} {RFC 6455}) is supported
+ * \note Currently only V13 (\l {RFC 6455}) is supported
*/
QWebSocket::QWebSocket(const QString &origin,
QWebSocketProtocol::Version version,
diff --git a/src/websockets/qwebsocketcorsauthenticator.cpp b/src/websockets/qwebsocketcorsauthenticator.cpp
index 4645302..7e544a6 100644
--- a/src/websockets/qwebsocketcorsauthenticator.cpp
+++ b/src/websockets/qwebsocketcorsauthenticator.cpp
@@ -53,7 +53,7 @@
\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
+ \sa {WebSocket Security Considerations}
\sa QWebSocketServer
*/
diff --git a/src/websockets/qwebsocketdataprocessor.cpp b/src/websockets/qwebsocketdataprocessor.cpp
index 6ffd751..79a50ad 100644
--- a/src/websockets/qwebsocketdataprocessor.cpp
+++ b/src/websockets/qwebsocketdataprocessor.cpp
@@ -34,7 +34,7 @@
\class QWebSocketDataProcessor
The class QWebSocketDataProcessor is responsible for reading, validating and
interpreting data from a WebSocket.
- It reads data from a QIODevice, validates it against RFC 6455, and parses it into
+ It reads data from a QIODevice, validates it against \l{RFC 6455}, and parses it into
frames (data, control).
It emits signals that correspond to the type of the frame: textFrameReceived(),
binaryFrameReceived(), textMessageReceived(), binaryMessageReceived(), pingReceived(),
diff --git a/src/websockets/qwebsocketprotocol.cpp b/src/websockets/qwebsocketprotocol.cpp
index 77b4a4c..eb75f24 100644
--- a/src/websockets/qwebsocketprotocol.cpp
+++ b/src/websockets/qwebsocketprotocol.cpp
@@ -76,40 +76,34 @@ QT_BEGIN_NAMESPACE
\brief The different defined versions of the WebSocket protocol.
For an overview of the differences between the different protocols, see
- <http://code.google.com/p/pywebsocket/wiki/WebSocketProtocolSpec>
+ \l {pywebsocket's WebSocketProtocolSpec}.
\value VersionUnknown Unknown or unspecified version.
- \value Version0 hixie76:
- http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76 &
- hybi-00:
- http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-00.
+ \value Version0 \l{hixie76} and \l{hybi-00}.
Works with key1, key2 and a key in the payload.
Attribute: Sec-WebSocket-Draft value 0.
Not supported by QtWebSockets.
- \value Version4 hybi-04:
- http://tools.ietf.org/id/draft-ietf-hybi-thewebsocketprotocol-04.txt.
+ \value Version4 \l{hybi-04}.
Changed handshake: key1, key2, key3
==> Sec-WebSocket-Key, Sec-WebSocket-Nonce, Sec-WebSocket-Accept
Sec-WebSocket-Draft renamed to Sec-WebSocket-Version
Sec-WebSocket-Version = 4.
Not supported by QtWebSockets.
- \value Version5 hybi-05:
- http://tools.ietf.org/id/draft-ietf-hybi-thewebsocketprotocol-05.txt.
+ \value Version5 \l{hybi-05}.
Sec-WebSocket-Version = 5
Removed Sec-WebSocket-Nonce
Added Sec-WebSocket-Accept.
Not supported by QtWebSockets.
\value Version6 Sec-WebSocket-Version = 6.
Not supported by QtWebSockets.
- \value Version7 hybi-07:
- http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-07.
+ \value Version7 \l{hybi-07}.
Sec-WebSocket-Version = 7.
Not supported by QtWebSockets.
\value Version8 hybi-8, hybi-9, hybi-10, hybi-11 and hybi-12.
Status codes 1005 and 1006 are added and all codes are now unsigned
Internal error results in 1006.
Not supported by QtWebSockets.
- \value Version13 hybi-13, hybi14, hybi-15, hybi-16, hybi-17 and RFC 6455.
+ \value Version13 hybi-13, hybi14, hybi-15, hybi-16, hybi-17 and \l{RFC 6455}.
Sec-WebSocket-Version = 13
Status code 1004 is now reserved
Added 1008, 1009 and 1010
diff --git a/src/websockets/qwebsocketserver.cpp b/src/websockets/qwebsocketserver.cpp
index 49d8799..ff64f3e 100644
--- a/src/websockets/qwebsocketserver.cpp
+++ b/src/websockets/qwebsocketserver.cpp
@@ -60,17 +60,16 @@
Calling close() makes QWebSocketServer stop listening for incoming connections.
QWebSocketServer currently does not support
- \l {http://tools.ietf.org/html/rfc6455#page-39} {extensions} and
- \l {http://tools.ietf.org/html/rfc6455#page-12} {subprotocols}.
+ \l {WebSocket Extensions} and
+ \l {WebSocket Subprotocols}.
- \note When working with self-signed certificates, FireFox currently has a
- \l {https://bugzilla.mozilla.org/show_bug.cgi?id=594502} {bug} that prevents it to
+ \note When working with self-signed certificates, \l{Firefox bug 594502} prevents \l{Firefox} to
connect to a secure WebSocket server. To work around this problem, first browse to the
secure WebSocket server using HTTPS. FireFox will indicate that the certificate is invalid.
From here on, the certificate can be added to the exceptions. After this, the secure WebSockets
connection should work.
- QWebSocketServer only supports version 13 of the WebSocket protocol, as outlined in RFC 6455.
+ QWebSocketServer only supports version 13 of the WebSocket protocol, as outlined in \l{RFC 6455}.
\sa {WebSocket Server Example}, QWebSocket
*/