// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page topics-network-connectivity.html
\title Networking and Connectivity
\brief Qt's network and connectivity features.
\ingroup explanations-networkingandconnectivity

Qt provides classes for both high-level and low-level network communication,
classes for web integration, and classes for inter-process communication (IPC).

For high-level network traffic, \l{Qt Network} provides an abstraction layer
over the operations used, showing only high-level classes and functions. Qt
Network can also handle lower level protocols like TCP and UDP. Classes like
QTcpSocket and QUdpSocket enable the developer to send and receive messages
using the TCP or UDP protocol. Name resolution is done with QHostInfo. QHostInfo
is called before creating a network connection with QTcpSocket or QUdpSocket.
Filtering and redistributing network traffic via proxies can be handled by the
QNetworkProxy class.

Qt provides \e connectivity options to connect systems or applications using modules like
\l {Qt Bluetooth}, which provides connectivity between Bluetooth enabled devices.
\l {Qt Serial Bus} provides classes and functions to access the various industrial
serial buses and protocols, and \l {Qt NFC} provides connectivity between NFC enabled devices.
Also, \l{Qt Serial Port} provides the basic functionality, including configuring, I/O operations,
and getting and setting the control signals of the RS-232 pinouts.

Qt offers functionalities for \l {Inter-Process Communication}.
The class QProcess is used to start external programs. \l{Qt D-Bus} provides support
for D-Bus, an inter-process communication and remote procedure calling mechanism.
It communicates via a central server application called a bus. However,
it is also possible to let applications communicate directly with each other.
QSharedMemory provides access to a shared memory segment by multiple threads
and processes. However, a single process can exclusively lock that shared memory.

\section1 Network Communication

Qt supports a wide range of network communication, with a focus on HTTP, TCP, and
UDP.

At the HTTP level, the \l{Qt Network} module offers the network access API,
which consists mainly of QNetworkRequest, QNetworkAccessManager, and
QNetworkReply. The QNetworkRequest resembles an HTTP request, which
gets passed to the QNetworkAccessManager to send the request on the wire; this
class returns a QNetworkReply, which enables parsing the HTTP reply. The network
access API internally uses the socket classes mentioned below (for TCP and SSL).

QTcpSocket, QUdpSocket, and QSslSocket should be used for communication at the socket level.
These classes offer a synchronous API through the waitFor* methods as well as an
asynchronous API; if possible (that is if the event loop is running), the asynchronous
API should always be preferred. Qt also offers QTcpServer to enable the server-side
part of a TCP communication.

For secure communication via SSL, Qt Network offers a wide range of classes
alongside the central QSslSocket. For example, QSslCertificate, QSslConfiguration, and
QSslError.

Qt also offers HTTP support in QML by either using HTTP explicitly via
XmlHttpRequest, or by transparently using HTTP URLs in Image sources for example.

Related Topics:
\list
    \li \l {Network Programming with Qt}
    \li \l {Secure Sockets Layer (SSL) Classes}
    \li \l {Resource Loading and Network Transparency} - network and URL transparency in QML
    \li \l {Qt Network Authorization} - set of APIs that enable Qt applications to
           obtain limited access to online accounts and HTTP services without exposing
           users' passwords.
    \li \l {Qt Remote Objects} - an inter-process communication (IPC) module that enables
           information exchange between processes or computers.
    \li \l {Qt MQTT} - machine-to-machine (M2M) protocol that uses the publish-and-subscribe
           paradigm to provide a channel with minimal communication overhead.
    \li \l {Qt OPC UA} - server that offers access to data that is organized in a mesh of nodes
           connected by references. The use of different reference types and nodes containing
           metadata enables a client to navigate and interpret the data without knowing their
           structure in advance.
    \li \l {Qt WebSockets} - web-based protocol designed to enable a two-way interactive
           communication session between a client application and a remote host. It enables
           the two entities to send data back and forth if the initial handshake succeeds.
    \li \l {Qt WebChannel} - enables peer-to-peer communication between a server
           (QML/C++ application) and a client (HTML/JavaScript or QML application). It is
           supported out of the box by Qt WebEngine. In addition, it can work on all browsers
           that support WebSockets, enabling Qt WebChannel clients to run in any JavaScript
           environment (including QML). This requires implementing a custom transport based
           on Qt WebSockets.
    \li \l [QtProtobuf]{Qt Protobuf} - a generator that can be used to generate Qt-based classes
           from \c .proto files.
    \li \l [QtGrpc]{Qt GRPC} - allows you to define data and messages in proto files and then
           use the code generators, which generate code allowing accessors for fields and gRPC
           services in the Qt framework.
    \li \l {Qt OpenAPI} - a generator that can be used to generate
           Qt-based HTTP client classes from .yaml OpenAPI specification files.
\endlist

\section1 Connectivity

Qt supports a range of connectivity options, with a focus on \l {Qt Serial Bus},
\l {Qt Serial Port}, \l {Qt Bluetooth} and \l{Qt NFC}.

\list
    \li \l {Qt Serial Bus} - provides classes and functions to access the various
            industrial serial buses and protocols, such as CAN, ModBus, and others.
    \li \l {Qt Serial Port} - provides the basic functionality, which includes
            configuring, I/O operations, getting and setting the control signals
            of the RS-232 pinouts.
    \li \l {Qt Bluetooth} - provides classes and functions to use Bluetooth devices,
            which includes scanning for devices, gathering information, and exchanging
            data between them. Qt Bluetooth supports both Classic and Low Energy
            Bluetooth technologies.
    \li \l {Qt NFC} - provides classes and functions to establish connectivity between
            NFC enabled devices. NFC is a short-range (less than 20 centimeters)
            wireless technology with a maximum transfer rate of 424 Kbps. NFC is
            ideal for transferring small packets of data when two devices are placed together.
\endlist

Related Topics:

\list
\li \l {Inter-process communication in Qt}
\li \l {Qt D-Bus} - module documentation
    \list
    \li \l {Using Qt D-Bus Adaptors}
    \li \l {Declaring Signals in D-Bus Adaptors}
    \li \l {Declaring Slots in D-Bus Adaptors}
    \li \l {The Qt D-Bus Type System}
    \li \l {Qt D-Bus XML compiler (qdbusxml2cpp)}
    \endlist
\li \l {QProcess}
\li \l {QLocalSocket}
\li \l {QSharedMemory}
\endlist

*/
