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/wifi/qwifimanager.cpp | 349 ++++++++++++++++++++++++---------------------- 1 file changed, 182 insertions(+), 167 deletions(-) (limited to 'src/wifi/qwifimanager.cpp') 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 -- cgit v1.2.3