/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt local connectivty modules.
**
** $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 https://www.qt.io/terms-conditions. For further
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example chat
    \title Bluetooth QML Chat Example
    \brief An example demonstrating communication through Bluetooth QML API.

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

    \image chat-view.png

    The Bluetooth QML Chat example implements a simple chat program between two parties. The
    application acts as client and attempts to connect to a Bluetooth socket server. It uses
    the \l BluetoothDiscoveryModel type to find the server and \l BluetoothSocket type to
    facilitate the data exchange.

    \include examples-run.qdocinc

    The example only works in connection with the \l {btchat}{Bluetooth Chat Example}.
    The Bluetooth Chat example launches the chat service and advertises it via the
    Bluetooth SDP protocol. It is important that the device running the Bluetooth Chat
    example actively advertises its SDP services.
    This can be checked using the \l QBluetoothLocalDevice::hostMode property.

    \section1 Interacting with the Server

    The example application immediately starts the service discovery using the
    \l BluetoothDiscoveryModel type:

    \snippet chat/chat.qml BtDiscoveryModel-1
    \snippet chat/chat.qml BtDiscoveryModel-3

    The \l {BluetoothDiscoveryModel::uuidFilter}{uuidFilter} property is used to only search for
    the chat server UUID and the \l {BluetoothDiscoveryModel::running}{running}
    property activates the search. Once a service with a matching UUID is found the model emits the
    \l {BluetoothDiscoveryModel::serviceDiscovered}{serviceDiscovered(BluetoothService)} signal.

    \snippet chat/chat.qml BtDiscoveryModel-2

    The \l BluetoothService type encapsulates the details of the found chat server, such as the
    \l {BluetoothService::serviceName}{name} and \l {BluetoothService::serviceDescription}{description} of the
    service, as well as the \l{BluetoothService::deviceName}{name} and \l {BluetoothService::deviceAddress}{address}
    of the Bluetooth device offering the chat server. It is passed to the \l BluetoothSocket
    to establish the connection.

    Once the connection is established the socket's state is managed as follows:
    \snippet chat/chat.qml BluetoothSocket-1
    \snippet chat/chat.qml BluetoothSocket-2

    The payload is received via the \l {BluetoothSocket::stringData}{stringData} property:

    \snippet chat/chat.qml BluetoothSocket-3
    \snippet chat/chat.qml BluetoothSocket-4

    And sent by setting the same property:

    \snippet chat/chat.qml BluetoothSocket-5
*/
