Add class documentation for QLowEnergyController

This class is part of the new Bluetooth Low Energy feature in Qt 5.4

Change-Id: Ib1a8000b4ad256400f18e241a296fe1ffa97414a
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>

1 files changed, 205 insertions, 1 deletions

diff --git a/src/bluetooth/qlowenergycontroller.cpp b/src/bluetooth/qlowenergycontroller.cpp
index d0c70ba3..43b96dc8 100644
--- a/src/bluetooth/qlowenergycontroller.cpp
+++ b/src/bluetooth/qlowenergycontroller.cpp
@@ -48,6 +48,140 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class QLowEnergyController
+    \inmodule QtBluetooth
+    \brief The QLowEnergyController class provides access to Bluetooth
+    Low Energy Devices.
+
+    \since 5.4
+
+    QLowEnergyController acts as the entry point for Bluetooth Low Energy
+    development. Each QLowEnergyController instance acts as placeholder
+    towards a remote Low Energy device enabling connection control,
+    service discovery and state tracking.
+
+    Bluetooth Low Energy defines two types of devices; the peripheral and
+    the central. Each role performs a different task. The peripheral device
+    provides data which is utilized by central devices. An example might be a
+    humidity sensor which measures the moisture in a winter garden. A device
+    such as a mobile phone might read the sensor's value and display it to the user
+    in the greater context of all sensors in the same environment. In this case
+    the sensor is the peripheral device and the mobile phone acts as the
+    central device.
+
+    At the moment Qt only supports the central role and therefore the remote
+    device can only be a device acting as a peripheral. This implies that the local
+    device acts within the boundaries of the central role as per the Bluetooth 4.0
+    specification.
+
+    The first step is to establish a connection via \l connectToDevice().
+    Once the connection has been established, the controller's \l state()
+    changes to \l QLowEnergyController::ConnectedState and the \l connected()
+    signal is emitted. It is important to mention that the remote device can
+    usually only be connected to a single device. Therefore it is not
+    possible to have multiple instances of this class being connected to the
+    same remote device. The \l disconnectFromDevice() function is used to break
+    the existing connection.
+
+    The second step after establishing the connection is to discover the services
+    offered by the remote peripheral device. This process is started via
+    \l discoverServices() and has finished once the \l discoveryFinished() signal
+    has been emitted. The discovered services can be enumerated via
+    \l services().
+
+    The last step is to create service objects. The \l createServiceObject()
+    function acts as factory for each service object and expects the service
+    UUID as parameter. The calling context should take ownership of the returned
+    \l QLowEnergyService instance.
+
+    Any \l QLowEnergyService, \l QLowEnergyCharacteristic or
+    \l QLowEnergyDescriptor instance which is later created from this controller's
+    connection becomes invalid as soon as the controller disconnects from the
+    remote Bluetooth Low Energy device.
+
+    \sa QLowEnergyService, QLowEnergyCharacteristic, QLowEnergyDescriptor
+*/
+
+/*!
+    \enum QLowEnergyController::Error
+
+    Indicates all possible error conditions found during the controller's
+    existence.
+
+    \value NoError                      No error has occurred.
+    \value UnknownError                 An unknown error has occurred.
+    \value UnknownRemoteDeviceError     The remote Bluetooth Low Energy device with the address passed to
+                                        the constructor of this class cannot be found.
+    \value NetworkError                 The attempt to read from or write to the
+                                        remote device failed.
+    \value InvalidBluetoothAdapterError The local Bluetooth device with the address passed to
+                                        the constructor of this class cannot be found or
+                                        there is no local Bluetooth device.
+*/
+
+/*!
+    \enum QLowEnergyController::ControllerState
+
+    Indicates the state of the controller object.
+
+    \value UnconnectedState   The controller is not connected to a remote device.
+    \value ConnectingState    The controller is attempting to connect to a remote device.
+    \value ConnectedState     The controller is connected to a remote device.
+    \value ClosingState       The controller is about to be disconnected from the remote device.
+*/
+
+/*!
+    \fn void QLowEnergyController::connected()
+
+    This signal is emitted when the controller successfully connects to the remote
+    Low Energy device.
+*/
+
+/*!
+    \fn void QLowEnergyController::disconnected()
+
+    This signal is emitted when the controller disconnects from the remote
+    Low Energy device.
+*/
+
+/*!
+    \fn void QLowEnergyController::stateChanged(ControllerState state)
+
+    This signal is emitted when the controller's state changes. The new
+    \a state can also be retrieved via \l state().
+
+    \sa state()
+*/
+
+/*!
+    \fn void QLowEnergyController::error(QLowEnergyController::Error newError)
+
+    This signal is emitted when an error occurs.
+    The \a newError parameter describes the error that occurred.
+
+    \sa error(), errorString()
+*/
+
+/*!
+    \fn void QLowEnergyController::serviceDiscovered(const QBluetoothUuid &newService)
+
+    This signal is emitted each time a new service is discovered. The
+    \a newService parameter contains the UUID of the found service.
+
+    \sa discoverServices(), discoveryFinished()
+*/
+
+/*!
+    \fn void QLowEnergyController::discoveryFinished()
+
+    This signal is emitted when the running service discovery finishes.
+    The signal is not emitted if the discovery process finishes with
+    an error.
+
+    \sa discoverServices(), error()
+*/
+
 void QLowEnergyControllerPrivate::setError(
         QLowEnergyController::Error newError)
 {
@@ -215,6 +349,16 @@ quint16 QLowEnergyControllerPrivate::updateValueOfDescriptor(
     return service->characteristicList[charHandle].descriptorList[descriptorHandle].value.size();
 }
 
+/*!
+    Constructs a new instance of this class with \a parent.
+
+    The \a remoteDevice must contain the address of the
+    remote Bluetooth Low Energy device to which this object
+    should attempt to connect later on.
+
+    The controller uses the local default Bluetooth adapter for
+    the connection management.
+ */
 QLowEnergyController::QLowEnergyController(
                             const QBluetoothAddress &remoteDevice,
                             QObject *parent)
@@ -226,6 +370,19 @@ QLowEnergyController::QLowEnergyController(
     d->localAdapter = QBluetoothLocalDevice().address();
 }
 
+/*!
+    Constructs a new instance of this class with \a parent.
+
+    The \a remoteDevice must contain the address of the
+    remote Bluetooth Low Energy device to which this object
+    should attempt to connect later on.
+
+    The connection is established via \a localDevice. If \a localDevice
+    is invalid, the local default device is automatically selected. If
+    \a localDevice specifies a local device that is not a local Bluetooth
+    adapter, \l error() is set to \l InvalidBluetoothAdapterError once
+    \l connectToDevice() is called.
+ */
 QLowEnergyController::QLowEnergyController(
                             const QBluetoothAddress &remoteDevice,
                             const QBluetoothAddress &localDevice,
@@ -238,6 +395,9 @@ QLowEnergyController::QLowEnergyController(
     d->localAdapter = localDevice;
 }
 
+/*!
+    Destroys the QLowEnergyController instance.
+ */
 QLowEnergyController::~QLowEnergyController()
 {
     disconnectFromDevice(); //in case we were connected
@@ -259,16 +419,34 @@ QBluetoothAddress QLowEnergyController::localAddress() const
     return d_ptr->localAdapter;
 }
 
+/*!
+    Returns the address of the remote Bluetooth Low Energy device.
+ */
 QBluetoothAddress QLowEnergyController::remoteAddress() const
 {
     return d_ptr->remoteDevice;
 }
 
+/*!
+    Returns the current state of the controller.
+
+    \sa stateChanged()
+ */
 QLowEnergyController::ControllerState QLowEnergyController::state() const
 {
     return d_ptr->state;
 }
 
+
+/*!
+    Connects to the remote Bluetooth Low Energy device.
+
+    This function does nothing if the controller's \l state()
+    is \l UnconnectedState. The \l connected() signal is emitted
+    once the connection is successfully established.
+
+    \sa disconnectFromDevice()
+ */
 void QLowEnergyController::connectToDevice()
 {
     Q_D(QLowEnergyController);
@@ -284,6 +462,16 @@ void QLowEnergyController::connectToDevice()
     d->connectToDevice();
 }
 
+/*!
+    Disconnects from the remote device.
+
+    Any \l QLowEnergyService, \l QLowEnergyCharacteristic or \l QLowEnergyDescriptor
+    instance that resulted from the current connection is automatically invalidated.
+    Once any of those objects become invalid they remain invalid even if this
+    controller object reconnects.
+
+    \sa connectToDevice()
+ */
 void QLowEnergyController::disconnectFromDevice()
 {
     Q_D(QLowEnergyController);
@@ -295,6 +483,15 @@ void QLowEnergyController::disconnectFromDevice()
     d->disconnectFromDevice();
 }
 
+/*!
+    Initiates the service discovery process.
+
+    The discovery progress is indicated via the \l serviceDiscovered() signal.
+    The \l discoveryFinished() signal is emitted when the process has finished.
+
+    If the controller instance is not connected or the controller has performed
+    the service discovery already this function will do nothing.
+ */
 void QLowEnergyController::discoverServices()
 {
     Q_D(QLowEnergyController);
@@ -326,7 +523,7 @@ QList<QBluetoothUuid> QLowEnergyController::services() const
     a \a parent parameter as default owner.
 
     This function returns a null pointer if no service with
-    \a serviceUUid can be found on the remote device.
+    \a serviceUuid can be found on the remote device.
 
     This function can return instances for secondary services
     too. The include relationships between services can be expressed
@@ -347,11 +544,18 @@ QLowEnergyService *QLowEnergyController::createServiceObject(
     return service;
 }
 
+/*!
+    Returns the last occurred error or \l NoError.
+*/
 QLowEnergyController::Error QLowEnergyController::error() const
 {
     return d_ptr->error;
 }
 
+/*!
+    Returns a textual representation of the last occurred error.
+    The string is translated.
+*/
 QString QLowEnergyController::errorString() const
 {
     return d_ptr->errorString;