/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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 connectivity-api.html
\title Connectivity
\brief The Connectivity API facilitates communication with local devices.
\ingroup mobility

\tableofcontents

\section1 Overview

The Connectivity API provides a set of APIs for communicating with local devices.

The current version of the Connectivity API includes support for Bluetooth and Near Field
Communication (NFC) technologies. Bluetooth is a short-range (less than 100 meters) wireless
technology. It has a reasonably high data transfer rate of 2.1 Mbit/s, which makes it ideal for
transfering data between devices.

The Bluetooth API provides classes for controlling the local Bluetooth device, discovering devices
in the local vacinity, discovering services provided by those devices, publishing services and both
server and client sockets for L2CAP and RFCOMM protocols.

NFC is an extremely short-range (approx. 1 centimeter) wireless techonology and has a maximum
transfer rate of 424 kbit/s. NFC is ideal for transfer small packets of data when two devices are
touched together.

The NFC API provides APIs for interacting with NFC Forum Tags and NFC Forum Devices, including
target detection and loss, registering NDEF message handlers, reading and writing NDEF messages to
NFC Forum Tags, send tag specific commands. The API also provides client and server LLCP sockets.

\section1 Known Issues and Limitations

\section2 Bluetooth and S60 5.0/Symbian^1

The S60 5.0 SDK as shipped by Nokia does not include all the required header
files and libraries to compile the bluetooth backend for Symbian. It contains a
subset of the requires bluetooth library. There is a Bluetooth plugin available
for the S60 3.2 SDK but it cannot be used since it will overwrite and damage
part of the bluetooth support already present in the 5.0 SDK. As such,
compiling QtMobility for Symbian/S60 5.0 not recommended until Nokia
releases a S60 5.0/Symbian^1 bluetooth plugin.  A bug has been opened
about this issue: \l http://bugreports.qt.nokia.com/browse/QTMOBILITY-1660

\section2 NFC

The NFC API is only supported on Harmattan and Symbian^3 and the Qt Simulator. On Symbian^3 the API is
fully functional. On the Qt Simulator only target detection and loss and tag access are support. On
Harmattan the following features are \bold NOT supported:

\list
    \o Connectionless LLCP sockets (both client and server).
    \o Tag type specific access.
\endlist


\section1 Examples

Some interesting examples for the API exist.

\table 80%
    \header
        \o Example
        \o Description
    \row
        \o \l{annotatedurl}{NFC Annotated URL}
        \o Displays URL along with caption text and an image from from an NFC tag containing a
           specially formated NDEF message.
    \row
        \o \l{btchat}{Bluetooth Chat}
        \o A chat server and client using bluetooth.
    \row
        \o \l{bttennis}{Bluetooth Tennis}
        \o The classic game of \l {http://en.wikipedia.org/wiki/Pong}{Pong}. Supports multiplayer
           over Bluetooth and touch-to-play functionality on devices that support NFC.
    \row
        \o \l{btfiletransfer}{Bluetooth File Transfer}
        \o Transfer files between Bluetooth devices.
    \row
        \o \l{btscanner}{Bluetooth Scanner}
        \o Scan for Bluetooth devices.
    \row
        \o \l{ndefeditor}{NDEF Editor}
        \o Create NDEF messages using the NDEF records supported by the Connectivity API and save
           them to supported NFC Forum tags.
    \row
        \o \l{declarative-connectivity/tennis}{QML Bluetooth Tennis}
        \o The tennis game using a QML interface to the Bluetooth API. It must connect to an
           instance of the C++ \l{bttennis}{Bluetooth Tennis} game to play.
    \row
        \o \l{declarative-connectivity/scanner}{QML Bluetooth Scanner}
        \o A QML implementation of the Bluetooth device scanner.
    \row
        \o \l{declarative-connectivity/poster}{QML Poster}
        \o A QML implementation of the NFC Annotated URL example.
    \row
        \o \l{https://projects.developer.nokia.com/nfcinfo}{Nfc Info}
        \o Shows all information about NFC tags.
    \row
        \o \l{https://projects.developer.nokia.com/nfccorkboards}{Nfc Corkboard}
        \o Example how to autolauch an application by touching a NFC tag.
    \row
        \o \l{https://projects.developer.nokia.com/nfcchat}{Nfc Chat}
        \o NFC chat application. 
    
\endtable

See also \l{http://www.developer.nokia.com/Develop/NFC/Code_examples/}{Nfc Code Examples} link.

\section1 Main Classes

\section2 NFC Classes

\annotatedlist connectivity-nfc

\section2 Bluetooth Classes

\annotatedlist connectivity-bluetooth

\section2 Qt Quick Elements

\annotatedlist connectivity-qml

*/