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

/*!
    \example btchat
    \title Bluetooth Chat
    \meta category {Connectivity}
    \brief Shows communication through Bluetooth using RFCOMM protocol.

    The Bluetooth Chat example shows how to use the \l{Qt Bluetooth} API to communicate
    with another application on a remote device using Bluetooth RFCOMM protocol.

    \image btchat-example.png

    The Bluetooth Chat example implements a simple chat program between multiple parties. The
    application always acts as both a server and a client eliminating the need to determine who
    should connect to whom.

    \include examples-run.qdocinc

    \section1 Chat Server

    The chat server is implemented by the \c ChatServer class.
    The \c ChatServer class is declared as:

    \snippet btchat/chatserver.h declaration

    The first thing the chat server needs to do is create an instance of
    QBluetoothServer to listen for incoming Bluetooth connections. The
    \c {clientConnected()} slot will be called whenever a new connection is
    created.

    \snippet btchat/chatserver.cpp Create the server

    The chat server is only useful if others know that it is there. To enable other devices to
    discover it, a record describing the service needs to be published in the system's SDP (Service
    Discovery Protocol) database. The QBluetoothServiceInfo class encapsulates a service record.

    We will publish a service record that contains some textual descriptions of the services, a
    UUID that uniquely identifies the service, the discoverability attribute, and connection
    parameters.

    The textual description of the service is stored in the \c {ServiceName},
    \c {ServiceDescription}, and \c {ServiceProvider} attributes.

    \snippet btchat/chatserver.cpp Service name, description and provider

    Bluetooth uses UUIDs as unique identifiers. The chat service uses a randomly generated
    UUID.

    \snippet btchat/chatserver.cpp Service UUID
    \snippet btchat/chatserver.cpp Service UUID set

    A Bluetooth service is only discoverable if it is in the
    \l {QBluetoothUuid::}{PublicBrowseGroup}.

    \snippet btchat/chatserver.cpp Service Discoverability

    The \c ProtocolDescriptorList attribute is used to publish the connection parameters that the
    remote device requires to connect to our service. Here we specify that the \c Rfcomm protocol
    is used and set the port number to the port that our \c rfcommServer instance is listening to.

    \snippet btchat/chatserver.cpp Protocol descriptor list

    Finally, we register the service record with the system.

    \snippet btchat/chatserver.cpp Register service

    As mentioned earlier, incoming connections are handled in the
    \c {clientConnected()} slot where pending connections are connected to the
    \l {QBluetoothSocket::}{readyRead()} and
    \l {QBluetoothSocket::}{disconnected()} signals. The signals notify others
    that a new client has connected.

    \snippet btchat/chatserver.cpp clientConnected

    The \c {readSocket()} slot is called whenever data is ready to be read from
    a client socket. The slot reads individual lines from the socket, converts
    them from UTF-8, and emits the \c {messageReceived()} signal.

    \snippet btchat/chatserver.cpp readSocket

    The \c {clientDisconnected()} slot is called whenever a client disconnects
    from the service. The slot emits a signal to notify others that a client
    has disconnected, and deletes the socket.

    \snippet btchat/chatserver.cpp clientDisconnected

    The \c {sendMessage()} slot is used to send a message to all connected clients. The message is
    converted into UTF-8 and appended with a newline before being sent to all clients.

    \snippet btchat/chatserver.cpp sendMessage

    When the chat server is stopped, the service record is removed from the
    system SDP database, all connected client sockets are deleted, and the
    \c rfcommServer instance is deleted.

    \snippet btchat/chatserver.cpp stopServer

    \section1 Service Discovery

    Before connecting to the server, the client needs to scan the nearby
    devices and search for the device that is advertising the chat service.
    This is done by the \c RemoteSelector class.

    To start service lookup, the \c RemoteSelector creates an instance of
    \l QBluetoothServiceDiscoveryAgent and connects to its signals.

    \snippet btchat/remoteselector.cpp createDiscoveryAgent

    An UUID filter is set, so that the service discovery only shows the devices
    that advertise the needed service. After that a
    \l {QBluetoothServiceDiscoveryAgent::}{FullDiscovery} is started:

    \snippet btchat/remoteselector.cpp startDiscovery

    When a matching service is discovered, a
    \l {QBluetoothServiceDiscoveryAgent::}{serviceDiscovered()} signal is
    emitted with an instance of \l QBluetoothServiceInfo as a parameter. This
    service info is used to extract the device name and the service name,
    and add a new entry to the list of discovered remote devices:

    \snippet btchat/remoteselector.cpp serviceDiscovered

    Later the user can select one of the devices from the list and try to
    connect to it.

    \section1 Chat Client

    The chat client is implemented by the \c ChatClient class.
    The \c ChatClient class is declared as:

    \snippet btchat/chatclient.h declaration

    The client creates a new QBluetoothSocket and connects to the remote
    service described by the \c remoteService parameter. Slots are connected
    to the socket's \l {QBluetoothSocket::}{readyRead()},
    \l {QBluetoothSocket::}{connected()}, and
    \l {QBluetoothSocket::}{disconnected()} signals.

    \snippet btchat/chatclient.cpp startClient

    On successful socket connection we emit a signal to notify other users.

    \snippet btchat/chatclient.cpp connected

    Similarly to the chat server, the \c readSocket() slot is called when data
    is available from the socket. Lines are read individually and converted
    from UTF-8. The \c {messageReceived()} signal is emitted.

    \snippet btchat/chatclient.cpp readSocket

    The \c {sendMessage()} slot is used to send a message to the remote device.
    The message is converted to UTF-8 and a newline is appended.

    \snippet btchat/chatclient.cpp sendMessage

    To disconnect from the remote chat service, the QBluetoothSocket instance is deleted.

    \snippet btchat/chatclient.cpp stopClient

    \section1 Chat Dialog

    The main window of this example is the chat dialog, implemented in the
    \c Chat class. This class displays a chat session between a single
    \c ChatServer and zero or more \c {ChatClient}s. The \c Chat class is
    declared as:

    \snippet btchat/chat.h declaration

    First we construct the user interface

    \snippet btchat/chat.cpp Construct UI

    We create an instance of the \c ChatServer and respond to its
    \c {clientConnected()}, \c {clientDiconnected()}, and
    \c {messageReceived()} signals.

    \snippet btchat/chat.cpp Create Chat Server

    In response to the \c {clientConnected()} and \c {clientDisconnected()}
    signals of the \c ChatServer, we display the typical "X has joined chat."
    and "Y has left." messages in the chat session.

    \snippet btchat/chat.cpp clientConnected clientDisconnected

    Incoming messages from clients connected to the \c ChatServer are handled
    in the \c {showMessage()} slot. The message text tagged with the remote
    device name is displayed in the chat session.

    \snippet btchat/chat.cpp showMessage

    In response to the connect button being clicked, the application starts service discovery and
    presents a list of discovered chat services on remote devices. A \c ChatClient for the service
    is selected by the user.

    \snippet btchat/chat.cpp Connect to remote service

    In reponse to the \c {connected()} signals from \c ChatClient, we display
    the "Joined chat with X." message in the chat session.

    \snippet btchat/chat.cpp connected

    Messages are sent to all remote devices via the \c ChatServer and
    \c ChatClient instances by emitting the \c {sendMessage()} signal.

    \snippet btchat/chat.cpp sendClicked

    We need to clean up \c ChatClient instances when the remote device forces
    a disconnect.

    \snippet btchat/chat.cpp clientDisconnected
*/
