From 8c2c5938b79f64e869a82f742da063e281171e1d Mon Sep 17 00:00:00 2001 From: Venugopal Shivashankar Date: Thu, 28 May 2015 22:36:56 +0200 Subject: Doc: Added an overview page and updated the qdocconf Task-number: QTBUG-41044 Change-Id: I074573e814de63e009744a11054365fb2f25bdb9 Reviewed-by: Liang Qi --- .../images/websockets-pictorial-representation.jpg | Bin 0 -> 39914 bytes src/websockets/doc/qtwebsockets.qdocconf | 3 +- src/websockets/doc/src/index.qdoc | 9 +- src/websockets/doc/src/overview.qdoc | 112 +++++++++++++++++++++ 4 files changed, 118 insertions(+), 6 deletions(-) create mode 100644 src/websockets/doc/images/websockets-pictorial-representation.jpg create mode 100644 src/websockets/doc/src/overview.qdoc (limited to 'src') diff --git a/src/websockets/doc/images/websockets-pictorial-representation.jpg b/src/websockets/doc/images/websockets-pictorial-representation.jpg new file mode 100644 index 0000000..5308fdd Binary files /dev/null and b/src/websockets/doc/images/websockets-pictorial-representation.jpg differ diff --git a/src/websockets/doc/qtwebsockets.qdocconf b/src/websockets/doc/qtwebsockets.qdocconf index 8ce18ec..002898c 100644 --- a/src/websockets/doc/qtwebsockets.qdocconf +++ b/src/websockets/doc/qtwebsockets.qdocconf @@ -53,7 +53,8 @@ exampledirs += ../../../examples/websock examples.fileextensions += "*.html" -imagedirs += ../../../examples/websockets/doc/images +imagedirs += ../../../examples/websockets/doc/images \ + images manifestmeta.thumbnail.names += "QtWebSockets/*" diff --git a/src/websockets/doc/src/index.qdoc b/src/websockets/doc/src/index.qdoc index 344a859..e0f219c 100644 --- a/src/websockets/doc/src/index.qdoc +++ b/src/websockets/doc/src/index.qdoc @@ -37,11 +37,9 @@ the solution for applications that struggle to get real-time data feeds with less network latency and minimum data exchange. - The Qt WebSockets module implements the WebSocket protocol as specified in - \l {http://tools.ietf.org/html/rfc6455} {RFC 6455}. It provides C++ and QML - interfaces that enable Qt applications to act as a server that can process - WebSocket-based requests, or a client that can consume data received from - the server, or both. + The Qt WebSockets module provides C++ and QML interfaces that enable + Qt applications to act as a server that can process WebSocket requests, + or a client that can consume data received from the server, or both. To use this module in your application, use the following include statement: @@ -59,6 +57,7 @@ \section1 Reference Documentation \list + \li \l{Qt WebSockets Overview}{Overview} \li \l{Qt WebSockets C++ Classes}{C++ Classes} \li \l{Qt WebSockets QML Types}{QML Types} \endlist diff --git a/src/websockets/doc/src/overview.qdoc b/src/websockets/doc/src/overview.qdoc new file mode 100644 index 0000000..df080c1 --- /dev/null +++ b/src/websockets/doc/src/overview.qdoc @@ -0,0 +1,112 @@ +/**************************************************************************** +** +** Copyright (C) 2015 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$ +** +****************************************************************************/ + +/*! +\page websockets-overview.html +\title Qt WebSockets Overview +\brief Provides insight into the WebSocket protocol and the Qt WebSockets module. + +Qt WebSockets enables you to build WebSocket-aware applications. It +provides an implementation for the WebSocket protocol, which is offered by IETF +(Internet Engineering Task Force) as a better alternative for bidirectional +communication using the existing web infrastructure. + +Historically, web applications that needed bidirectional communication or +push notifications had to use one of the HTTP-based solutions available. These +solutions employed different techniques such as polling, long-polling, and +streaming, to overcome the limitations of HTTP protocol, which is not designed +for such use cases. As a result, high network latency, unnecessary data +exchange, and stale or old data. The WebSocket offering by IETF helps to +overcome these problems to a large extent. + +\section1 How does it Work? + +\image websockets-pictorial-representation.jpg + +As you can see in the pictorial representation, WebSocket-based solution +consists of a client-side and server-side. The native client-side support for +WebSocket is available on most of the popular web browsers such as Google +Chrome, Internet Explorer, Safari, and so on. The server-side support for +WebSocket makes it a complete solution, enabling bidirectional communication. +Any browser with native WebSocket support should let you run a simple HTML and +JavaScript-based client application using the HTML5 WebSocket API. + +A WebSocket connection begins with a initial HTTP-compatible handshake, +which ensures backwards compatibility so that the WebSocket connections can +share the default HTTP (80) and HTTPS (443) ports. On successful handshake, +the connection is open for data exchange, until one of the two entities end +the connection. + +The WebSocket protocol uses \c ws: and \c wss: URL schemes to represent +unsecure and secure WebSocket requests, respectively. During the initial +handshake, if a proxy server is detected, the protocol tries to set up a tunnel +by issuing an \c{HTTP CONNECT} statement to the proxy. The tunnel approach to +handle proxies is used irrespective of the request type, although it is proved +to work better with TLS (Transport Layer Security) in secure connections. + +\section1 Typical Use Cases + +WebSocket suits best for scenarios where, +\list + \li data presented must be up-to-date, + \li low network latency and minimal data exchange is crucial. +\endlist + +A few example applications where we struggle to achieve these using the +traditional approach are, instant messaging, online gaming, online stock +trading, and so on. + +\section1 Role of Qt WebSockets + +The Qt WebSockets module provides APIs to develop WebSocket-based server and +client applications. An example of where these APIs can be used is a server +application that provides stock data, and a client application that registers +for push notification when there is a change in price of a few stocks. + +The module provides both C++ and QML versions of the API, so you can choose +the alternative that suits your need. + +\section2 Qt WebSockets with Qt Cloud Services + +The client application usually depends on an external service for data. Most of +these service providers do not support WebSocket yet, so you end up developing +a WebSocket-aware server application to bridge the gap. You can choose to run +the server on an enterprise WebSocket gateway service such as Qt Cloud +Services, avoiding the hassle of maintaining the necessary infrastructure +required to host such a service. + +The Qt Cloud Services provides a Managed Application Runtime (MAR) backend, +which enables deploying and running an instance of server application on the +cloud. The server instance running on MAR gets a WebSocket URL, which can be +used by the client applications to connect and receive data. + +\section2 Related Information +\list +\li \l {http://tools.ietf.org/html/rfc6455}{WebSocket RFC 6455} +\li \l {https://qtcloudservices.com}{Qt Cloud Services} +\endlist +*/ -- cgit v1.2.1