/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
\ingroup technology-apis
\title Qt Bluetooth Overview
\page qtbluetooth-overview.html
\brief The Qt Bluetooth API enables connectivity with other regular Bluetooth
       and Bluetooth Low Energy enabled devices.

\tableofcontents

    With the Qt Bluetooth API typical use cases are:

        \list
        \li Retrieve information about the local Bluetooth device.
        \li Scan for other Bluetooth devices in range and retrieve information about them.
        \li Push files to remote devices using the OBEX Object Push Profile (OPP)
        \li Connect to remote devices through a RFCOMM channel using the Serial Port Profile (SPP).
        \li Create a RFCOMM server that allows incoming connections using SPP.
        \li Retrieve specification about Bluetooth Low Energy device.
        \li Connect to Bluetooth Low Energy device.
        \li Receive advertisement from Bluetooth Low Energy device.
        \endlist

    Note that the Object Push Profile is not supported on Android.

    The following sections describe how to use the Qt Bluetooth C++ API classes
    for the above use cases.

    \section1 Retrieving Local Device Information

    The Qt Bluetooth API has three main purposes. The first one is to
    obtain local and remote device information. The first steps in retrieving device information are
    to check if Bluetooth is available on the device and read the local device address and name.
    QBluetoothLocalDevice is the class that provides all of this information. Additionally you can use it
    to turn Bluetooth on/off, set the visibility of the device and determine the current connections.

    \snippet doc_src_qtbluetooth.cpp turningon

    \section1 Scanning for Bluetooth Devices

    Similar to the QBluetoothLocalDevice, the API offers QBluetoothDeviceInfo which provides
    similar information for remote devices. Although you can just create QBluetoothDeviceInfo objects on
    your own and fill them with data, the easier way is to use the QBluetoothDeviceDiscoveryAgent to
    start an automated search for visible Bluetooth devices within the connectable range.

    \snippet doc_src_qtbluetooth.cpp device_discovery

    \section1 Pushing Files to Remote Devices

    Once the desired device was found, there are two main use cases provided by Qt Bluetooth. The
    simpler one is to send files via the Obex Object Push Profile (OPP). As the name describes, this
    profile can push files from one device to another. Currently it is not possible to pull files
    or browse the remote file system. The profile does not require the two devices to be
    paired before exchanging data. To push files to remote devices, create a
    QBluetoothTransferRequest and ask the QBluetoothTransferManager to push the file contained in
    the request by calling its \l {QBluetoothTransferManager::put()}{put()} function.

    \snippet doc_src_qtbluetooth.cpp sendfile

    \section1 Exchanging Data Between Devices

    The more flexible approach for communication between two Bluetooth enabled devices, is to
    create a virtual serial port connection and freely exchange data over that connection. This can
    be done by the Serial Port Profile (SPP). The Serial Port Profile emulates a serial connection
    over the Bluetooth transport protocol RFCOMM.

    To be able to receive incoming SPP connections, you need to listen to incoming connections using
    \l QBluetoothServer.

    \snippet btchat/chatserver.cpp Create the server

    Connect to this server from another device playing the client role by using a
    QBluetoothSocket:

    \snippet btchat/chatclient.cpp startClient

    Using such a connection allows to exchange any form of data in both directions.
    It is perfectly suited for gaming or for syncing the state between two instances of
    an application on two devices. For more detailed descriptions on how to configure the server
    and client, please refer to the detailed description sections in the \l QBluetoothServer and
    \l QBluetoothSocket classes. A good example to start with SPP is the \l{btchat}{Bluetooth Chat}
    example.

    \section1 Bluetooth Low Energy

    Bluetooth Low Energy, also known as Bluetooth Smart, is a new technology enabling
    devices with low energy consumption to communicate with each other. More details about
    this technology and the related Qt APIs can be found in the \l {Bluetooth Low Energy Overview}.
*/
