Wifi - c++/qml getting started guide and wifi doc update

c++ getting started guide
qml getting started guide
documenting qml elements
documenting c++ classes

Task-number: QTEE-810
Change-Id: I669d11c65e5359fc9ec863b03b8b56ce2ef1151b
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@theqtcompany.com>
Reviewed-by: Kalle Viironen <kalle.viironen@theqtcompany.com>

2 files changed, 308 insertions, 1 deletions

diff --git a/src/imports/utils/plugin.cpp b/src/imports/utils/plugin.cpp
index 4012e96..a4f8810 100644
--- a/src/imports/utils/plugin.cpp
+++ b/src/imports/utils/plugin.cpp
@@ -21,9 +21,16 @@
 
 /*!
     \qmlmodule B2Qt.Utils 1.0
-    \title B2Qt Utils Module
+    \title B2Qt Utils QML Module
     \ingroup qtee-qmlmodules
     \brief A collection of utility functions, accessible from QML.
+*/
+
+/*!
+    \page b2qt-addon-utils.html
+    \title B2Qt Utils Module
+    \ingroup qtee-modules
+    \brief A collection of utility functions, accessible from QML.
 
     Provides various utility functions for controlling an embedded
     device, such as display brightness, IP address and hostname, and
@@ -41,6 +48,8 @@
           the platforms.
 
     \section1 QML Types
+
+    \annotatedlist utils-qmltypes
 */
 
 /*!
diff --git a/src/imports/wifi/pluginmain.cpp b/src/imports/wifi/pluginmain.cpp
index f706023..a778fa2 100644
--- a/src/imports/wifi/pluginmain.cpp
+++ b/src/imports/wifi/pluginmain.cpp
@@ -24,6 +24,304 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlmodule B2Qt.Wifi 1.0
+    \title B2Qt Wifi QML Module
+    \ingroup qtee-qmlmodules
+    \brief A module for managing wireless network connectivity.
+
+*/
+
+/*!
+    \page b2qt-addon-wifi.html
+    \title B2Qt Wifi Module
+    \ingroup qtee-modules
+    \brief A module for managing wireless network connectivity.
+
+    B2Qt.Wifi provides QML types and C++ classes for:
+
+    \list
+    \li Wifi backend handling
+    \li Retrieval of information from Wifi network access points
+    \li Wifi connection handling
+    \li System's network interface configuration
+    \li Other tasks that allow the device to access network
+    \endlist
+
+    \section1 Writing the Code
+
+    Depending on what fits best with the application, you can choose to use
+    either C++ or QML for accessing Wifi functionality. If the majority of the
+    user interface is written in QML, it is recommended that you use the QML
+    types, which provide a simpler and declarative way to handle Wifi networks.
+
+    \list
+    \li \l{Getting Started with B2Qt.Wifi in QML}
+    \li \l{Getting Started with B2Qt.Wifi in C++}
+    \endlist
+
+    \section1 API Reference
+
+    \section2 QML Types
+
+    \annotatedlist wifi-qmltypes
+
+    \section2 C++ Classes
+
+    \annotatedlist wifi-cppclasses
+*/
+
+/*!
+    \module B2Qt.Wifi.Cpp 1.0
+    \title B2Qt Wifi C++ Module
+    \ingroup qtee-cppmodules
+    \brief A module for managing wireless network connectivity.
+*/
+
+/*!
+    \qmltype WifiManager
+    \inqmlmodule B2Qt.Wifi
+    \ingroup wifi-qmltypes
+    \brief Main interface to the Wifi functionality.
+
+    WifiManager is a singleton type that is a central point for handling Wifi functionality
+    related tasks. You can use WifiManager's API to control the Wifi backend, scan surroundings for
+    Wifi access points and connect a device to a wireless network.
+
+    When scanning for networks, WifiManager packs the results in a list-based data model which can
+    be used with Qt's Model/View classes. Information about the Wifi networks is supplied via the model's
+    interface, accessed with the following roles:
+
+    \list
+    \li \e ssid - informal (human) name of a Wifi network
+    \li \e bssid - basic service set identification of a network, used to uniquely identify BSS
+    \li \e signalStrength - strength of a Wifi signal, measured in dBm
+    \li \e supportsWPA - holds whether network access point supports WPA security protocol
+    \li \e supportsWPA2 - holds whether network access point supports WPA2 security protocol
+    \li \e supportsWEP - holds whether network access point supports WEP security protocol
+    \li \e supportsWPS - holds whether network access point supports WPS security protocol
+    \endlist
+ */
+
+/*!
+    \qmlproperty enumeration WifiManager::NetworkState
+    \readonly
+
+    This property holds the current state of the network connection.
+
+    \list
+    \li \e WifiManager.Disconnected - Not connected to any network
+    \li \e WifiManager.Authenticating - Verifying password with the network provider
+    \li \e WifiManager.HandshakeFailed - Incorrect password provided
+    \li \e WifiManager.ObtainingIPAddress - Requesting IP address from DHCP server
+    \li \e WifiManager.DhcpRequestFailed - Could not retrieve IP address
+    \li \e WifiManager.Connected - Ready to process network requests
+    \endlist
+*/
+
+/*!
+    \qmlproperty enumeration WifiManager::BackendState
+    \readonly
+
+    This property holds the current state of the Wifi backend.
+
+    \list
+    \li \e WifiManager.Initializing - Wireless supplicant is starting up
+    \li \e WifiManager.Running - Supplicant is initialized and ready to process commands
+    \li \e WifiManager.Terminating - Shutting down wireless supplicant
+    \li \e WifiManager.NotRunning - Wireless supplicant process is not running
+    \endlist
+*/
+
+/*!
+    \qmlsignal WifiManager::networkStateChanged(NetworkState networkState)
+
+    This signal is emitted whenever changes in a network state occur. The network name for
+    which the NetworkState change events are send can be obtained from currentSSID.
+
+    \sa NetworkState, currentSSID
+*/
+
+/*!
+    \qmlsignal WifiManager::backendStateChanged(BackendState backendState)
+
+    This signal is emitted whenever changes in a backend state occur.
+
+    \sa start, stop
+*/
+
+/*!
+    \qmlsignal WifiManager::currentSSIDChanged(string currentSSID)
+
+    This signal is emitted when switching between different Wifi networks.
+
+    \sa start, stop
+*/
+
+/*!
+    \qmlsignal WifiManager::scanningChanged(bool scanning)
+
+    This signal is emitted when device starts or stops to scan for available Wifi networks.
+
+    \sa scanning
+*/
+
+/*!
+    \qmlsignal WifiManager::lastErrorChanged(string error)
+
+    This signal is emitted if some internal process has failed, \a error contains
+    a message on what has failed.
+
+    \sa connect
+*/
+
+/*!
+    \qmlproperty model WifiManager::networks
+    \readonly
+
+    This property holds a list-based data model of networks that can be sensed by a device.
+    Model can be used with Qt's Model/View classes like ListView. Data in the model is updated
+    every 5 seconds if scanning is enabled.
+
+    \sa scanning
+*/
+
+/*!
+    \qmlproperty string WifiManager::currentSSID
+    \readonly
+
+    This property holds a network name of last selected network, the network for
+    which the NetworkState change events are sent. Property can contain an empty
+    string when no active network connection exists.
+*/
+
+/*!
+    \qmlmethod WifiManager::start()
+
+    Start the Wifi backend. This function returns immediately, the BackendState
+    change events are delivered asynchronously.
+
+    \sa stop, BackendState
+*/
+
+/*!
+    \qmlmethod WifiManager::stop()
+
+    Stop the Wifi backend and if connected to any network shut down the network connection.
+    This function returns immediately, the BackendState change events are delivered asynchronously.
+
+    \sa start, BackendState
+*/
+
+/*!
+    \qmlproperty bool WifiManager::scanning
+
+    This property holds whether or not the backend is scanning for Wifi networks. To
+    preserve battery energy, set this property to false when scanning is not required.
+    When enabled, new readings are taken every 5 seconds.
+
+    For scanning to work, first you need to initialize the Wifi backend.
+
+    \sa start
+*/
+
+/*!
+    \qmlproperty string WifiManager::lastError
+    \readonly
+
+    This property holds an error message if some internal process has failed.
+
+    \sa connect
+*/
+
+/*!
+    \qmlmethod bool WifiManager::connect(WifiConfiguration config)
+
+    Connect a device to a network using the \a config network configuration.
+    This method returns \a true if the network with provoded configuration could be
+    successfully added by the backend or \a false on failure, to obtain an error message
+    read lastError property.
+
+    \sa disconnect, NetworkState, lastError
+*/
+
+/*!
+    \qmlmethod WifiManager::disconnect()
+
+    Disconnect from currently connected network connection.
+
+    \sa connect, NetworkState
+*/
+
+/*!
+    \qmltype WifiDevice
+    \inqmlmodule B2Qt.Wifi
+    \ingroup wifi-qmltypes
+    \brief Represents a physical device.
+
+    Use this element to query if a device is Wifi capable, before attempting
+    to use the functionality of WifiManager.
+
+    \qml
+    import B2Qt.Wifi 1.0
+
+    GroupBox {
+        id: wifiOptions
+        title: "Wifi"
+        visible: false
+
+        Component.onCompleted: {
+            if (WifiDevice.wifiSupported()) {
+                var component = Qt.createComponent("WifiGroupBoxContent.qml")
+                var wifi = component.createObject(wifiOptions.contentItem)
+                if (wifi)
+                    wifiOptions.visible = true
+            } else {
+                print("Wifi functionality not available on this device.")
+            }
+        }
+    }
+    \endqml
+*/
+
+/*!
+    \qmlmethod bool WifiDevice::wifiSupported()
+
+    Returns \a true if a device is Wifi capable - Wifi driver and firmware has been
+    successfully loaded by the system, otherwise returns \a false.
+*/
+
+/*!
+    \qmltype WifiConfiguration
+    \inqmlmodule B2Qt.Wifi
+    \ingroup wifi-qmltypes
+    \brief Used to define a network configuration.
+
+    WifiConfiguration object represents a single network configuration. Use this object
+    to configure a properties of your network, for example what passphrase and security
+    protocol to use. WifiManager's connect() function takes this object and connects a
+    device to a network that matches the provided configuration.
+*/
+
+/*!
+    \qmlproperty string WifiConfiguration::ssid
+
+    This property holds informal (human) name of a Wifi network.
+*/
+
+/*!
+    \qmlproperty string WifiConfiguration::passphrase
+
+    This property holds the passphrase to use for authenticating with a network.
+*/
+
+/*!
+    \qmlproperty string WifiConfiguration::protocol
+
+    This property holds the security protocols to use for Wifi connection.
+    WPA is used by default if property is not set, supported values are: WPA, WPA2, WEP, WPS.
+*/
+
 static QObject *globalWifiDevice(QQmlEngine *, QJSEngine *)
 {
     return new QWifiDevice;