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/doc/config/b2qt.qdocconf | 13 +- src/doc/src/qtee-changelog.qdoc | 2 +- src/doc/src/qtee-index.qdoc | 2 +- src/doc/src/qtee-licenses.qdoc | 2 +- src/doc/src/qtee-qml-reference.qdoc | 16 +- src/imports/utils/plugin.cpp | 11 +- src/imports/wifi/pluginmain.cpp | 298 ++++++++++++++++++++++++++++++ src/wifi/qwificonfiguration.cpp | 47 +++-- src/wifi/qwificonfiguration.h | 2 +- src/wifi/qwifidevice.cpp | 83 ++++----- src/wifi/qwifimanager.cpp | 349 +++++++++++++++++++----------------- src/wifi/qwifimanager.h | 18 +- src/wifi/qwifinetwork.cpp | 73 -------- src/wifi/qwifinetworklistmodel.cpp | 28 +-- 14 files changed, 606 insertions(+), 338 deletions(-) (limited to 'src') diff --git a/src/doc/config/b2qt.qdocconf b/src/doc/config/b2qt.qdocconf index c5b4a9a..727930a 100644 --- a/src/doc/config/b2qt.qdocconf +++ b/src/doc/config/b2qt.qdocconf @@ -4,15 +4,18 @@ naturallanguage = en_US outputencoding = UTF-8 sourceencoding = UTF-8 -project = QtEnterpriseEmbedded +project = QtForDeviceCreation description = Qt for Device Creation version = 4.0.0 sourcedirs = ../src \ ../../imports/wifi \ - ../../imports/utils + ../../imports/utils \ + ../../wifi -headerdirs = ../../imports/wifi +headerdirs += ../../wifi + +exampledirs += ../../../examples imagedirs += ../images @@ -43,4 +46,6 @@ macro.B2QA = "\\e {Boot to Qt for embedded Android}" macro.B2QL = "\\e {Boot to Qt for embedded Linux}" navigation.landingpage = "Qt for Device Creation" -navigation.qmltypespage = "Add-On QML Types" +navigation.qmltypespage = "Add-On Modules" + +Cpp.ignoreDirectives += Q_DECLARE_LOGGING_CATEGORY diff --git a/src/doc/src/qtee-changelog.qdoc b/src/doc/src/qtee-changelog.qdoc index 5f18e4c..4113e52 100644 --- a/src/doc/src/qtee-changelog.qdoc +++ b/src/doc/src/qtee-changelog.qdoc @@ -179,7 +179,7 @@ \li Update new content to device without erasing it first on \B2QL \li All images now contain generally used CA certificates \li Toolchains updated to support Qt WebEngine - \li Documentation was added for QML types provided by the \l {QtWifi Module} + \li Documentation was added for QML types provided by the \l {B2Qt.Wifi Module} \li Emulator: Debug logging functionality was added \li Various documentation improvements \li \SDK installer error handling was improved diff --git a/src/doc/src/qtee-index.qdoc b/src/doc/src/qtee-index.qdoc index 02eb4e2..41eff4b 100644 --- a/src/doc/src/qtee-index.qdoc +++ b/src/doc/src/qtee-index.qdoc @@ -68,7 +68,7 @@ \section1 Reference Documentation \list - \li \l{Add-On QML Types} + \li \l{Add-On Modules} \endlist */ diff --git a/src/doc/src/qtee-licenses.qdoc b/src/doc/src/qtee-licenses.qdoc index daf8b82..791ec92 100644 --- a/src/doc/src/qtee-licenses.qdoc +++ b/src/doc/src/qtee-licenses.qdoc @@ -21,7 +21,7 @@ \page qtee-licenses.html \title License Information \previouspage qtee-troubleshooting.html - \nextpage qtee-qml-reference.html + \nextpage qtee-module-reference.html \section1 Licensing diff --git a/src/doc/src/qtee-qml-reference.qdoc b/src/doc/src/qtee-qml-reference.qdoc index 0107e97..121b534 100644 --- a/src/doc/src/qtee-qml-reference.qdoc +++ b/src/doc/src/qtee-qml-reference.qdoc @@ -18,14 +18,14 @@ ****************************************************************************/ /*! - \page qtee-qml-reference.html - \title Add-On QML Types + \page qtee-module-reference.html + \title Add-On Modules \previouspage qtee-licenses.html - The following QML modules are included in the \B2Q stack and provide - additional QML types that are useful in an embedded application: + The following modules included in the \B2Q stack, provide + additional API that are useful for an embedded application: - \annotatedlist qtee-qmlmodules + \annotatedlist qtee-modules \section1 B2Qt Utils Module @@ -33,6 +33,12 @@ \section1 B2Qt Wifi Module + \section2 QML Types + \annotatedlist wifi-qmltypes + + \section2 C++ Classes + + \annotatedlist wifi-cppclasses */ 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; diff --git a/src/wifi/qwificonfiguration.cpp b/src/wifi/qwificonfiguration.cpp index f2c859a..87ef440 100644 --- a/src/wifi/qwificonfiguration.cpp +++ b/src/wifi/qwificonfiguration.cpp @@ -38,6 +38,18 @@ QWifiConfigurationPrivate::QWifiConfigurationPrivate(QWifiConfiguration *config) { } +/*! + \class QWifiConfiguration + \inmodule B2Qt.Wifi.Cpp + \ingroup wifi-cppclasses + \brief Used to define a network configuration. + + QWifiConfiguration object represents a single network configuration. Use it + to configure properties of your network. For example, passphrase, security + protocol to use, and so on. QWifiManager::connect() function uses this + information to find a network that matches the provided configuration, before + establishing a connection. + */ QWifiConfiguration::QWifiConfiguration(QObject *parent) : QObject(parent) @@ -50,40 +62,55 @@ QWifiConfiguration::~QWifiConfiguration() delete d_ptr; } -void QWifiConfiguration::setSsid(const QString &ssid) -{ - Q_D(QWifiConfiguration); - d->m_ssid = ssid; -} - +/*! + \property QWifiConfiguration::ssid + \brief a human-readable name of a Wifi network +*/ QString QWifiConfiguration::ssid() const { Q_D(const QWifiConfiguration); return d->m_ssid; } -void QWifiConfiguration::setPassphrase(const QString &psk) +void QWifiConfiguration::setSsid(const QString &ssid) { Q_D(QWifiConfiguration); - d->m_psk = psk; + d->m_ssid = ssid; } +/*! + \property QWifiConfiguration::passphrase + \brief a passphrase to use for authenticating access to a network +*/ QString QWifiConfiguration::passphrase() const { Q_D(const QWifiConfiguration); return d->m_psk; } -void QWifiConfiguration::setProtocol(const QString &protocol) +void QWifiConfiguration::setPassphrase(const QString &passphrase) { Q_D(QWifiConfiguration); - d->m_protocol = protocol; + d->m_psk = passphrase; } +/*! + \property QWifiConfiguration::protocol + \brief a security protocol to use for Wifi connection + + WPA is used by default if protocol is not explicitly set. + Supported values are: WPA, WPA2, WEP, WPS. +*/ QString QWifiConfiguration::protocol() const { Q_D(const QWifiConfiguration); return d->m_protocol; } +void QWifiConfiguration::setProtocol(const QString &protocol) +{ + Q_D(QWifiConfiguration); + d->m_protocol = protocol; +} + QT_END_NAMESPACE diff --git a/src/wifi/qwificonfiguration.h b/src/wifi/qwificonfiguration.h index 2253fbb..9b03c9e 100644 --- a/src/wifi/qwificonfiguration.h +++ b/src/wifi/qwificonfiguration.h @@ -38,7 +38,7 @@ public: void setSsid(const QString &ssid); QString ssid() const; - void setPassphrase(const QString &psk); + void setPassphrase(const QString &passphrase); QString passphrase() const; void setProtocol(const QString &protocol); QString protocol() const; diff --git a/src/wifi/qwifidevice.cpp b/src/wifi/qwifidevice.cpp index 4f100c4..f3eb62b 100644 --- a/src/wifi/qwifidevice.cpp +++ b/src/wifi/qwifidevice.cpp @@ -28,44 +28,25 @@ QT_BEGIN_NAMESPACE /*! - \qmltype WifiDevice - \inqmlmodule QtWifi - \ingroup wifi-qmltypes - \brief Represents a physical device - - Use this element to query if a device is WiFi capable before attempting - to use functionality of WifiManager. - - \qml - import QtWifi 1.0 - - GroupBox { - id: wifiOptions - title: "Wifi" - visible: false - - Component.onCompleted: { - if (WifiDevice.wifiSupported()) { - var component = Qt.createComponent("WifiGroupBox.qml") - var wifi = component.createObject(wifiOptions.contentItem) - if (wifi) - wifiOptions.visible = true - } else { - print("WiFi functionality not available on this device.") - } - } + \class QWifiDevice + \inmodule B2Qt.Wifi.Cpp + \ingroup wifi-cppclasses + \brief Represents a physical device. + + Use this class to query if a device is Wifi capable, before attempting + to use the functionality of QWifiManager. + + \code + QWifiManager *m_wifiManager = 0; + if (QWifiDevice::wifiSupported()) + m_wifiManager = QWifiManager::instance(); + + if (m_wifiManager) { + m_wifiManager->start(); + // and other wifi related code } - \endqml -*/ - -/*! - \qmlmethod bool QWifiDevice::wifiSupported() - - Returns true if the device is WiFi capable - WiFi driver and firmware has been - successfully loaded by the system, otherwise returns false. - - \sa wifiInterfaceName -*/ + \endcode + */ QWifiDevice::QWifiDevice() { @@ -75,6 +56,10 @@ QWifiDevice::~QWifiDevice() { } +/*! + Returns \a true if a device is Wifi capable - Wifi driver and firmware has been + successfully loaded by the system, otherwise returns \a false. +*/ bool QWifiDevice::wifiSupported() { #ifdef Q_OS_ANDROID_NO_SDK @@ -108,18 +93,15 @@ bool QWifiDevice::wifiSupported() } /*! - \fn QByteArray QWifiDevice::wifiInterfaceName() - - Returns WiFi interface name. + Returns Wifi interface name. - \note On Android WiFi interface name is read from "wifi.interface" system property. - On Linux WiFi interface name is read from B2QT_WIFI_INTERFACE environmental variable if - it is set. The default interface name is "wlan0" if reading the designated places does not - provide an interface name. - - /sa setWifiInterfaceName -*/ + \note On Android, the Wifi interface name is read from "wifi.interface" + system property. On Linux, it is read from the \c B2QT_WIFI_INTERFACE + environment variable if it is set, otherwise, the default interface + name ("\e{wlan0}") is used. + \sa setWifiInterfaceName() + */ QByteArray QWifiDevice::wifiInterfaceName() { QByteArray ifc; @@ -135,11 +117,10 @@ QByteArray QWifiDevice::wifiInterfaceName() } /*! - \fn void QWifiDevice::setWifiInterfaceName(const QByteArray &name) - - A conveniece method for settings WiFi interface name. -*/ + A conveniece method to set the Wifi interface name. + \sa wifiInterfaceName() + */ void QWifiDevice::setWifiInterfaceName(const QByteArray &name) { #ifdef Q_OS_ANDROID_NO_SDK diff --git a/src/wifi/qwifimanager.cpp b/src/wifi/qwifimanager.cpp index de35224..db188bf 100644 --- a/src/wifi/qwifimanager.cpp +++ b/src/wifi/qwifimanager.cpp @@ -27,73 +27,6 @@ QT_BEGIN_NAMESPACE -/*! - \qmlmodule QtWifi 1.0 - \title QtWifi Module - \ingroup qtee-qmlmodules - \brief A module for managing wireless network connectivity. - - Provides QML types for controlling WiFi networks - handling WiFi backend initialization, - retrieving information from nearby WiFi access points, setting up and bringing down WiFi - connections, querying DHCP server for IP address. - - The import command for adding these QML types is: - - \code - import QtWifi 1.0 - \endcode - - \section1 API Reference -*/ - -/*! - - \qmltype WifiManager - \inqmlmodule QtWifi - \ingroup wifi-qmltypes - \brief Main interface to the WiFi functionality. - - WifiManager is a singleton type that provides information about the WiFi backend and - available networks, use it to control the WiFi backend, scan for wireless networks - and connect to selected network. WifiManager provides events for backend and network - state changes. - - */ - -/*! - \qmlsignal void WifiManager::networkStateChanged(NetworkState networkState) - - This signal is emitted whenever changes in a network state occur. The network name for - which the state changes events are send can be obtained from currentSSID. - - \sa networkState -*/ - -/*! - \qmlsignal void WifiManager::backendStateChanged(BackendState backendState) - - This signal is emitted whenever changes in a backend state occur. - - \sa start, stop -*/ - -/*! - \qmlsignal void WifiManager::currentSSIDChanged(string currentSSID) - - This signal is emitted when switching between different WiFi networks. - - \sa start, stop -*/ - -/*! - \qmlsignal void WifiManager::scanningChanged(bool scanning) - - This signal is emitted when device starts or stops to scan for available wifi networks. - - \sa scanning - -*/ - // must be in the same order as in enum {} definiton const char *nsText[] = { "Disconnected", "Authenticating", "HandshakeFailed", "ObtainingIPAddress", "DhcpRequestFailed", "Connected" }; @@ -259,8 +192,105 @@ void QWifiManagerPrivate::updateLastError(const QString &error) emit q->lastErrorChanged(m_lastError); } +/*! + \class QWifiManager + \inmodule B2Qt.Wifi.Cpp + \ingroup wifi-cppclasses + \brief Enables an application to be Wifi-capable. + + QWifiManager is a singleton class that handles Wifi-related tasks. You can + use QWifiManager to control the Wifi backend, scan for Wifi access points, + and connect to a wireless network. + + QWifiManager packs the scan results in a list-based data model, which can + be used with Qt's Model/View classes. Information about a Wifi network can + be accessed using the QWifiManager::Roles data roles. + */ + +/*! + \enum QWifiManager::NetworkState + + Describes current state of the network connection. + + \value Disconnected Not connected to any network + \value Authenticating Verifying password with the network provider + \value HandshakeFailed Incorrect password provided + \value ObtainingIPAddress Requesting IP address from DHCP server + \value DhcpRequestFailed Could not retrieve IP address + \value Connected Ready to process network requests + */ + +/*! + \enum QWifiManager::BackendState + + Describes current state of the Wifi backend. + + \value Initializing Wireless supplicant is starting up + \value Running Supplicant is initialized and ready to process commands + \value Terminating Shutting down wireless supplicant + \value NotRunning Wireless supplicant process is not running + */ + +/*! + \enum QWifiManager::Roles + + Data roles supported by the data model returned from QWifiManager::networks() + + \value SSID informal (human) name of a Wifi network (QString) + \value BSSID basic service set identification of a network, used to uniquely identify BSS (QString) + \value SignalStrength strength of a Wifi signal, measured in dBm (int) + \value WPASupported holds whether network access point supports WPA security protocol (QString) + \value WPA2Supported holds whether network access point supports WPA2 security protocol (QString) + \value WEPSupported holds whether network access point supports WEP security protocol (QString) + \value WPSSupported holds whether network access point supports WPS security protocol (QString) + */ + +/*! + \fn QWifiManager::networkStateChanged(NetworkState networkState) + + This signal is emitted whenever the network state changes. The network name + for which the signal is emitted, can be obtained from currentSSID. + + \sa NetworkState, currentSSID() + */ + +/*! + \fn QWifiManager::backendStateChanged(BackendState backendState) + + This signal is emitted whenever the backend state changes. + + \sa start(), stop() + */ + +/*! + \fn QWifiManager::currentSSIDChanged(string currentSSID) + + This signal is emitted when switching between different Wifi networks. + + \sa start(), stop() + */ + +/*! + \fn QWifiManager::scanningChanged(bool scanning) + + This signal is emitted when device starts or stops to scan for available Wifi networks. + + \sa isScanning() + */ + +/*! + \fn QWifiManager::lastErrorChanged(const string error) + + This signal is emitted if some internal process has failed, \a error contains + a message on what has failed. + + \sa connect() + */ QWifiManager* QWifiManager::m_instance = 0; +/*! + Returns a singleton instance of QWifiManager. +*/ QWifiManager* QWifiManager::instance() { if (!m_instance) @@ -287,6 +317,9 @@ QWifiManager::QWifiManager() d->updateWifiState(); } +/*! + Destroys the QWifiManager singleton instance. + */ QWifiManager::~QWifiManager() { Q_D(QWifiManager); @@ -296,17 +329,15 @@ QWifiManager::~QWifiManager() } /*! - \qmlproperty WifiNetworkListModel WifiManager::networks - \readonly + \property QWifiManager::networks + \brief a list-based data model of networks - This property holds a list of networks that can be sensed by a device. Use the returned - model as data model in ListView, model is updated every 5 seconds. - - WifiNetworkListModel is a simple data model consisting of WifiNetwork objects, accessed with - the "network" data role name. Instances of WifiNetwork cannot be created directly from the QML system. + Returns a list-based data model of networks that can be sensed by a device. + Model can be used with Qt's Model/View classes such as QListView. Data in + the model is updated every 5 seconds if scanning is enabled. + \sa isScanning() */ - QAbstractListModel *QWifiManager::networks() const { Q_D(const QWifiManager); @@ -314,13 +345,13 @@ QAbstractListModel *QWifiManager::networks() const } /*! - \qmlproperty string WifiManager::currentSSID - \readonly + \property QWifiManager::currentSSID + \brief a network name of the last selected network - This property holds the network name for which the networkState changes events are sent or - or an empty string when there is no active network. + The network for which the NetworkState change signals are emitted. + Property can contain an empty string when there is no active network + connection. */ - QString QWifiManager::currentSSID() const { Q_D(const QWifiManager); @@ -328,21 +359,11 @@ QString QWifiManager::currentSSID() const } /*! - \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 -*/ + \property QWifiManager::networkState + \brief the current network state + Returns the current network state. +*/ QWifiManager::NetworkState QWifiManager::networkState() const { Q_D(const QWifiManager); @@ -350,19 +371,11 @@ QWifiManager::NetworkState QWifiManager::networkState() const } /*! - \qmlproperty enumeration WifiManager::backendState - \readonly + \property QWifiManager::backendState + \brief the current backend state. - 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 + Returns the current backend state. */ - QWifiManager::BackendState QWifiManager::backendState() const { Q_D(const QWifiManager); @@ -370,14 +383,11 @@ QWifiManager::BackendState QWifiManager::backendState() const } /*! - \qmlmethod void WifiManager::start() - - Start the WiFi backend. This function returns immediately, the backendState + Start the Wifi backend. This function returns immediately, the BackendState change events are delivered asynchronously. - \sa stop, backendState - */ - + \sa stop(), BackendState +*/ void QWifiManager::start() { Q_D(QWifiManager); @@ -385,47 +395,35 @@ void QWifiManager::start() } /*! - \qmlmethod void WifiManager::stop() - - Stop the WiFi backend and if connected to any network shut down network connection. - This function returns immediately, the backendState change events are delivered asynchronously. - - \sa start, backendState - */ + Stop the Wifi backend. Closes the open network connection if any. + This function returns immediately, and the BackendState change events are + delivered asynchronously. + \sa start(), BackendState +*/ void QWifiManager::stop() { Q_D(QWifiManager); d->m_wifiController->call(QWifiController::TerminateBackend); } -void QWifiManager::handleBackendStateChanged(BackendState backendState) -{ - Q_D(QWifiManager); - switch (backendState) { - case Running: - d->m_setCurrentSSID = true; - break; - case NotRunning: - d->updateNetworkState(Disconnected); - break; - default: - break; - } - d->updateBackendState(backendState); -} +/*! + \property QWifiManager::scanning + \brief whether the backend is scanning for Wifi networks. -void QWifiManager::handleDhcpRequestFinished(const QString &status) + Sets whether to scan the environment for Wifi access points. + + To preserve battery energy, set this property to false when scanning is not required. + When enabled, new readings are taken every 5 seconds. + + \note You must initialize the Wifi backend to scan for networks. + + \sa start() +*/ +bool QWifiManager::isScanning() const { - Q_D(QWifiManager); - qCDebug(B2QT_WIFI) << "handleDhcpRequestFinished: " << status << " for " << d->m_currentSSID; - if (status == QLatin1String("success")) { - d->emitCurrentSSIDChanged(); - d->updateNetworkState(Connected); - d->call(QStringLiteral("SAVE_CONFIG")); - } else { - d->updateNetworkState(DhcpRequestFailed); - } + Q_D(const QWifiManager); + return d->m_scanning; } void QWifiManager::setScanning(bool scanning) @@ -446,22 +444,14 @@ void QWifiManager::setScanning(bool scanning) } /*! - \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. + \property QWifiManager::lastError + \brief a QString containing the last error message set by QWifiManager. - Before starting to scan for networks, you need to initialize the WiFi backend. + Returns a QString containing the last error message set by QWifiManager. + This helps in diagnosing the internal process failures. - \sa start + \sa connect() */ - -bool QWifiManager::scanning() const -{ - Q_D(const QWifiManager); - return d->m_scanning; -} - QString QWifiManager::lastError() const { Q_D(const QWifiManager); @@ -502,15 +492,14 @@ bool QWifiManager::event(QEvent *event) return QObject::event(event); } - /*! - \qmlmethod void WifiManager::connect(WifiNetwork network, string passphrase) - - Connect to network \a network and use passphrase \a passphrase for authentication. - - \sa disconnect, networkState - */ + Connect a device to a network using the \a config network configuration. + This method returns \c true if the network with the provided configuration + could be successfully added by the backend or \c false on failure. + Use lastError() to obtain the error message on failure. + \sa disconnect(), NetworkState, lastError() +*/ bool QWifiManager::connect(QWifiConfiguration *config) { Q_D(QWifiManager); @@ -583,13 +572,10 @@ bool QWifiManager::connect(QWifiConfiguration *config) } /*! - \qmlmethod void WifiManager::disconnect() - Disconnect from currently connected network connection. - \sa connect, networkState + \sa connect(), networkState() */ - void QWifiManager::disconnect() { Q_D(QWifiManager); @@ -597,4 +583,33 @@ void QWifiManager::disconnect() d->m_wifiController->call(QWifiController::StopDhcp); } +void QWifiManager::handleBackendStateChanged(BackendState backendState) +{ + Q_D(QWifiManager); + switch (backendState) { + case Running: + d->m_setCurrentSSID = true; + break; + case NotRunning: + d->updateNetworkState(Disconnected); + break; + default: + break; + } + d->updateBackendState(backendState); +} + +void QWifiManager::handleDhcpRequestFinished(const QString &status) +{ + Q_D(QWifiManager); + qCDebug(B2QT_WIFI) << "handleDhcpRequestFinished: " << status << " for " << d->m_currentSSID; + if (status == QLatin1String("success")) { + d->emitCurrentSSIDChanged(); + d->updateNetworkState(Connected); + d->call(QStringLiteral("SAVE_CONFIG")); + } else { + d->updateNetworkState(DhcpRequestFailed); + } +} + QT_END_NAMESPACE diff --git a/src/wifi/qwifimanager.h b/src/wifi/qwifimanager.h index cd55f4d..7fc658c 100644 --- a/src/wifi/qwifimanager.h +++ b/src/wifi/qwifimanager.h @@ -42,7 +42,7 @@ class Q_DECL_EXPORT QWifiManager : public QObject Q_ENUMS(BackendState) Q_PROPERTY(NetworkState networkState READ networkState NOTIFY networkStateChanged) Q_PROPERTY(BackendState backendState READ backendState NOTIFY backendStateChanged) - Q_PROPERTY(bool scanning READ scanning WRITE setScanning NOTIFY scanningChanged) + Q_PROPERTY(bool scanning READ isScanning WRITE setScanning NOTIFY scanningChanged) Q_PROPERTY(QString currentSSID READ currentSSID NOTIFY currentSSIDChanged) Q_PROPERTY(QString lastError READ lastError NOTIFY lastErrorChanged) Q_PROPERTY(QAbstractListModel *networks READ networks CONSTANT) @@ -64,13 +64,13 @@ public: }; enum Roles { - SSIDRole = Qt::UserRole + 1, - BSSIDRole = Qt::UserRole + 2, - SignalRole = Qt::UserRole + 3, - WPARole = Qt::UserRole + 4, - WPA2Role = Qt::UserRole + 5, - WEPRole = Qt::UserRole + 6, - WPSRole = Qt::UserRole + 7 + SSID = Qt::UserRole + 1, + BSSID = Qt::UserRole + 2, + SignalStrength = Qt::UserRole + 3, + WPASupported = Qt::UserRole + 4, + WPA2Supported = Qt::UserRole + 5, + WEPSupported = Qt::UserRole + 6, + WPSSupported = Qt::UserRole + 7 }; static QWifiManager *instance(); @@ -78,7 +78,7 @@ public: QAbstractListModel *networks() const; QString currentSSID() const; - bool scanning() const; + bool isScanning() const; void setScanning(bool scanning); NetworkState networkState() const; BackendState backendState() const; diff --git a/src/wifi/qwifinetwork.cpp b/src/wifi/qwifinetwork.cpp index 937cbfc..eb2b669 100644 --- a/src/wifi/qwifinetwork.cpp +++ b/src/wifi/qwifinetwork.cpp @@ -20,79 +20,6 @@ QT_BEGIN_NAMESPACE -/*! - \qmltype WifiNetwork - \inqmlmodule QtWifi - \ingroup wifi-qmltypes - \brief Represents a single WiFi network access point. - - WifiNetwork provides a various information about WiFi network, like network - name, siganl strength and supported security protocols. Instances of WifiNetwork cannot - be created directly from the QML system, see WifiManager::networks. -*/ - -/*! - \qmlproperty string WifiNetwork::bssid - \readonly - - This property holds basic service set identification of a network, used to uniquely - identify BSS. - -*/ - -/*! - \qmlproperty string WifiNetwork::ssid - \readonly - - This property holds a network name. The SSID is the informal (human) name of BSS. -*/ - -/*! - \qmlproperty int WifiNetwork::signalStrength - \readonly - - This property holds the current strength of a WiFi signal, measured in dBm. New readings are - taken every 5 seconds. - - \sa signalStrengthChanged -*/ - -/*! - \qmlproperty bool WifiNetwork::supportsWPA - \readonly - - This property holds whether network access point supports WPA security protocol. -*/ - -/*! - \qmlproperty bool WifiNetwork::supportsWPA2 - \readonly - - This property holds whether network access point supports WPA2 security protocol. -*/ - -/*! - \qmlproperty bool WifiNetwork::supportsWEP - \readonly - - This property holds whether network access point supports WEP security protocol. -*/ - -/*! - \qmlproperty bool WifiNetwork::supportsWPS - \readonly - - This property holds whether network access point supports WPS security protocol. -*/ - -/*! - \qmlsignal void WifiNetwork::signalStrengthChanged(int strength) - - This signal is emitted whenever signal strength has changed comparing the the - previous reading, the new signal's strength is \a strength. - -*/ - QWifiNetwork::QWifiNetwork(QObject *parent) : QObject(parent) , m_isOutOfRange(false) diff --git a/src/wifi/qwifinetworklistmodel.cpp b/src/wifi/qwifinetworklistmodel.cpp index 7a5de2a..6f53295 100644 --- a/src/wifi/qwifinetworklistmodel.cpp +++ b/src/wifi/qwifinetworklistmodel.cpp @@ -43,13 +43,13 @@ QWifiNetworkListModel::~QWifiNetworkListModel() QHash QWifiNetworkListModel::roleNames() const { QHash names; - names.insert(QWifiManager::SSIDRole, "ssid"); - names.insert(QWifiManager::BSSIDRole, "bssid"); - names.insert(QWifiManager::SignalRole, "signalStrength"); - names.insert(QWifiManager::WPARole, "supportsWPA"); - names.insert(QWifiManager::WPA2Role, "supportsWPA2"); - names.insert(QWifiManager::WEPRole, "supportsWEP"); - names.insert(QWifiManager::WPSRole, "supportsWPS"); + names.insert(QWifiManager::SSID, "ssid"); + names.insert(QWifiManager::BSSID, "bssid"); + names.insert(QWifiManager::SignalStrength, "signalStrength"); + names.insert(QWifiManager::WPASupported, "supportsWPA"); + names.insert(QWifiManager::WPA2Supported, "supportsWPA2"); + names.insert(QWifiManager::WEPSupported, "supportsWEP"); + names.insert(QWifiManager::WPSSupported, "supportsWPS"); return names; } @@ -58,25 +58,25 @@ QVariant QWifiNetworkListModel::data(const QModelIndex &index, int role) const QWifiNetwork *n = m_networks.at(index.row()); switch (role) { - case QWifiManager::SSIDRole: + case QWifiManager::SSID: return n->ssid(); break; - case QWifiManager::BSSIDRole: + case QWifiManager::BSSID: return n->bssid(); break; - case QWifiManager::SignalRole: + case QWifiManager::SignalStrength: return n->signalStrength(); break; - case QWifiManager::WPARole: + case QWifiManager::WPASupported: return n->supportsWPA(); break; - case QWifiManager::WPA2Role: + case QWifiManager::WPA2Supported: return n->supportsWPA2(); break; - case QWifiManager::WEPRole: + case QWifiManager::WEPSupported: return n->supportsWEP(); break; - case QWifiManager::WPSRole: + case QWifiManager::WPSSupported: return n->supportsWPS(); break; default: -- cgit v1.2.3