From 8d93772285f06f3e5239183a7fd8306c9d090930 Mon Sep 17 00:00:00 2001 From: Gatis Paeglis Date: Wed, 3 Dec 2014 09:40:48 +0100 Subject: 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 Reviewed-by: Kalle Viironen --- src/imports/wifi/pluginmain.cpp | 298 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) (limited to 'src/imports/wifi') 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; -- cgit v1.2.3