Doc: Added an overview page and updated the qdocconf

Task-number: QTBUG-41044
Change-Id: I074573e814de63e009744a11054365fb2f25bdb9
Reviewed-by: Liang Qi <liang.qi@theqtcompany.com>

4 files changed, 118 insertions, 6 deletions

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
--- /dev/null
+++ b/src/websockets/doc/images/websockets-pictorial-representation.jpg
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
+*/