/****************************************************************************
**
** 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 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 run the server
on an enterprise WebSocket gateway service such as a cloud service, avoiding
the hassle of maintaining the necessary infrastructure required to host such
a service.

Most of the cloud Services provide a Platform as a service (PaaS) backend,
which enables deploying and running an instance of your server application on
the cloud. The client applications can connect to the running server using a
WebSocket URL and receive data.

\section2 Related Information
\list
\li \l{RFC 6455}
\endlist
*/