From a5db288e9f55f27644c332dd66c98513fce7d123 Mon Sep 17 00:00:00 2001 From: Gatis Paeglis Date: Tue, 18 Mar 2014 09:48:40 +0100 Subject: Add documentation to QtWifi library MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: Ifd71c65a155ad296f3491085e91556eb69226b2b Reviewed-by: Topi Reiniö --- src/imports/wifi/pluginmain.cpp | 29 +++++ src/imports/wifi/qwifimanager.cpp | 215 ++++++++++++++++++++++++++++++++++++++ src/imports/wifi/qwifinetwork.cpp | 74 +++++++++++++ 3 files changed, 318 insertions(+) (limited to 'src/imports/wifi') diff --git a/src/imports/wifi/pluginmain.cpp b/src/imports/wifi/pluginmain.cpp index 97f16f3..6b8c0c3 100644 --- a/src/imports/wifi/pluginmain.cpp +++ b/src/imports/wifi/pluginmain.cpp @@ -25,6 +25,35 @@ #include +/*! + \qmltype Interface + \inqmlmodule Qt.labs.wifi + \brief The Interface element provides the module API. + + This element cannot be directly created. It can only be accessed via a namespace import. + + \code + import Qt.labs.wifi 0.1 + import Qt.labs.wifi 0.1 as Wifi + + Component.onCompleted: { + if (Wifi.Interface.wifiSupported()) { + var component = Qt.createComponent("WifiMenu.qml") + } else { + print("WiFi functionality not available on this device.") + } + } + + \endcode +*/ + +/*! + \qmlmethod bool Interface::wifiSupported() + + Returns true if the device is WiFi capable (provides a WiFi driver), otherwise returns false. +*/ + + class QWifiGlobal : public QObject { Q_OBJECT diff --git a/src/imports/wifi/qwifimanager.cpp b/src/imports/wifi/qwifimanager.cpp index 7d6683b..04faa93 100644 --- a/src/imports/wifi/qwifimanager.cpp +++ b/src/imports/wifi/qwifimanager.cpp @@ -119,6 +119,221 @@ public: QByteArray m_if; }; +/*! + \qmlmodule Qt.labs.wifi 0.1 + \title WiFi Module + \ingroup b2qt-qmlmodules + + Provides QML types for controlling and accessing information about wireless network interfaces. + + The import command for adding these QML types is: + + \code + import Qt.labs.wifi 0.1 + \endcode + + If the module is imported into a namespace, some additional methods become available through the + \l Interface element. + + \code + import Qt.labs.wifi 0.1 as Wifi + \endcode + +*/ + +/*! + + \qmltype WifiManager + \inqmlmodule Qt.labs.wifi + \brief WifiManager provides information about the wifi backend and available networks. + + This element is the main interface to the WiFi functionality. + + */ + +/*! + \qmlproperty enumeration WifiManager::networkState + + This property holds the current state of the network connection. + + \list + \li \e WifiManager.Disconnected - Not connected to any network + \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 bool WifiManager::backendReady + + This property holds whether or not the backend has been successfully initialized. + + \code + WifiManager { + id: wifiManager + scanning: backendReady + } + + Button { + id: wifiOnOffButton + text: (wifiManager.backendReady) ? "Switch Off" : "Switch On" + onClicked: { + if (wifiManager.backendReady) { + wifiManager.stop() + } else { + wifiManager.start() + } + } + } + \endcode +*/ + +/*! + \qmlproperty bool WifiManager::scanning + + This property holds whether or not the backend is scanning for WiFi networks. To + preserve battery energy, stop scanning for networks once you are done with configuring a network. + + Before starting to scan for networks, you need to initialize the WiFi backend. + + \sa start +*/ + +/*! + \qmlproperty string WifiManager::connectedSSID + + This property holds the network name. +*/ + +/*! + \qmlproperty WifiNetworkListModel WifiManager::networks + + This property holds a list of networks that can be sensed by a device and should be used as a + data model in ListView. List is updated every 5 seconds. + + WifiNetworkListModel is a simple data model consisting of WifiNetwork objects, accessed with + the "network" data role. Instances of WifiNetwork cannot be created directly from the QML system. + + \code + WifiManager { + id: wifiManager + scanning: backendReady + Component.onCompleted: start() + } + + Component { + id: listDelegate + Rectangle { + id: delegateBackground + height: 60 + width: parent.width + color: "#5C5C5C" + border.color: "black" + border.width: 1 + + Text { + id: ssidLabel + anchors.top: parent.top + anchors.left: parent.left + anchors.margins: 10 + font.pixelSize: 20 + font.bold: true + color: "#E6E6E6" + text: network.ssid + } + + Rectangle { + width: Math.max(100 + network.signalStrength, 0) / 100 * parent.width; + height: 20 + radius: 10 + antialiasing: true + anchors.margins: 20 + anchors.right: parent.right + anchors.top: parent.top + color: "#BF8888" + border.color: "#212126" + } + } + } + + + ListView { + id: networkView + anchors.fill: parent + model: wifiManager.networks + delegate: listDelegate + } + \endcode + +*/ + +/*! + \qmlmethod void WifiManager::start() + + Start an initialization of the WiFi backend. + + \sa stop + */ + +/*! + \qmlmethod void WifiManager::stop() + + Stop the WiFi backend and shut down all network functionality. + + \sa start + */ + +/*! + \qmlmethod void WifiManager::connect(WifiNetwork network, const string passphrase) + + Connect to network \a network and use passphrase \a passphrase for authentication. + + \sa disconnect, networkState + */ + +/*! + \qmlmethod void WifiManager::disconnect() + + Disconnect from currently connected network connection. + + \sa connect, networkState + */ + +/*! + \qmlsignal void WifiManager::scanningChanged(bool scanning) + + This signal is emitted when device starts or stops to scan for available wifi networks. + + \sa scanning + +*/ + +/*! + \qmlsignal void WifiManager::networkStateChanged() + + This signal is emitted whenever changes in a network state occur. + + \sa networkState +*/ + +/*! + \qmlsignal void WifiManager::backendReadyChanged() + + This signal is emitted when backend has been successfully initialized or shut down. + + \sa start, stop +*/ + +/*! + \qmlsignal void WifiManager::connectedSSIDChanged(string ssid) + + This signal is emitted when the device has connected to or disconnected from a network. + \a ssid contains the name of the connected network, or an empty string if the network was disconnected. + + \sa connect, disconnect +*/ + QWifiManager::QWifiManager() : m_networks(this) , m_eventThread(0) diff --git a/src/imports/wifi/qwifinetwork.cpp b/src/imports/wifi/qwifinetwork.cpp index a159e59..2ff8d7b 100644 --- a/src/imports/wifi/qwifinetwork.cpp +++ b/src/imports/wifi/qwifinetwork.cpp @@ -18,6 +18,80 @@ ****************************************************************************/ #include "qwifinetwork.h" +/*! + \qmltype WifiNetwork + \inqmlmodule Qt.labs.wifi + \brief WifiNetwork represents a single wifi network access point. + + Instances of WifiNetwork cannot be created directly from the QML system, use + WifiManager::networks. +*/ + +/*! + \qmlproperty string WifiNetwork::bssid + + This property holds basic service set identification of a network, used to uniquely + identify BSS. + +*/ + +/*! + \qmlproperty string WifiNetwork::ssid + + This property holds a network name. The SSID is the informal (human) name of BSS. +*/ + +/*! + \qmlproperty int WifiNetwork::signalStrength + + This property holds the current strength of a WiFi signal. New readings are + taken every 5 seconds. + + \sa signalStrengthChanged +*/ + +/*! + \qmlproperty bool WifiNetwork::supportsWPA + + This property holds whether network access point supports WPA security protocol. +*/ + +/*! + \qmlproperty bool WifiNetwork::supportsWPA2 + + This property holds whether network access point supports WPA2 security protocol. +*/ + +/*! + \qmlproperty bool WifiNetwork::supportsWEP + + This property holds whether network access point supports WEP security protocol. +*/ + +/*! + \qmlproperty bool WifiNetwork::supportsWPS + + 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. + + \code + function handleStrengthChanged(currentStrength) { + if (currentStrength < UNTOLERABLE_SPEED) + print("network speed has dropped under " + UNTOLERABLE_SPEED) + } + + Component.onCompleted: { + network.onSignalStrengthChanged.connect(handleStrengthChanged) + } + \endcode +*/ + QWifiNetwork::QWifiNetwork() { } -- cgit v1.2.3