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 --- examples/examples.pro | 3 + examples/wifi/wifi-cpp/doc/images/wifi-cpp.jpg | Bin 0 -> 41866 bytes examples/wifi/wifi-cpp/doc/src/wifi-cpp.qdoc | 97 +++++++ examples/wifi/wifi-cpp/main.cpp | 228 +++++++++++++++ examples/wifi/wifi-cpp/wifi-cpp.pro | 9 + examples/wifi/wifi-qml/WifiConnectionHandler.qml | 51 ++++ examples/wifi/wifi-qml/WifiScanner.qml | 251 ++++++++++++++++ examples/wifi/wifi-qml/doc/images/wifi-qml.jpg | Bin 0 -> 62077 bytes examples/wifi/wifi-qml/doc/src/wifi-qml.qdoc | 85 ++++++ examples/wifi/wifi-qml/main.cpp | 30 ++ examples/wifi/wifi-qml/main.qml | 32 +++ examples/wifi/wifi-qml/qml.qrc | 7 + examples/wifi/wifi-qml/wifi-qml.pro | 11 + examples/wifi/wifi.pro | 4 + 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 +- 28 files changed, 1414 insertions(+), 338 deletions(-) create mode 100644 examples/examples.pro create mode 100644 examples/wifi/wifi-cpp/doc/images/wifi-cpp.jpg create mode 100644 examples/wifi/wifi-cpp/doc/src/wifi-cpp.qdoc create mode 100644 examples/wifi/wifi-cpp/main.cpp create mode 100644 examples/wifi/wifi-cpp/wifi-cpp.pro create mode 100644 examples/wifi/wifi-qml/WifiConnectionHandler.qml create mode 100644 examples/wifi/wifi-qml/WifiScanner.qml create mode 100644 examples/wifi/wifi-qml/doc/images/wifi-qml.jpg create mode 100644 examples/wifi/wifi-qml/doc/src/wifi-qml.qdoc create mode 100644 examples/wifi/wifi-qml/main.cpp create mode 100644 examples/wifi/wifi-qml/main.qml create mode 100644 examples/wifi/wifi-qml/qml.qrc create mode 100644 examples/wifi/wifi-qml/wifi-qml.pro create mode 100644 examples/wifi/wifi.pro diff --git a/examples/examples.pro b/examples/examples.pro new file mode 100644 index 0000000..18801a2 --- /dev/null +++ b/examples/examples.pro @@ -0,0 +1,3 @@ +TEMPLATE = subdirs + +SUBDIRS += wifi diff --git a/examples/wifi/wifi-cpp/doc/images/wifi-cpp.jpg b/examples/wifi/wifi-cpp/doc/images/wifi-cpp.jpg new file mode 100644 index 0000000..90feb20 Binary files /dev/null and b/examples/wifi/wifi-cpp/doc/images/wifi-cpp.jpg differ diff --git a/examples/wifi/wifi-cpp/doc/src/wifi-cpp.qdoc b/examples/wifi/wifi-cpp/doc/src/wifi-cpp.qdoc new file mode 100644 index 0000000..334dba7 --- /dev/null +++ b/examples/wifi/wifi-cpp/doc/src/wifi-cpp.qdoc @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc +** All rights reserved. +** For any questions to Digia, please use the contact form at +** http://www.qt.io +** +** This file is part of Qt Enterprise Embedded. +** +** Licensees holding valid Qt Enterprise licenses may use this file in +** accordance with the Qt Enterprise License Agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. +** +** If you have questions regarding the use of this file, please use +** the contact form at http://www.qt.io +** +****************************************************************************/ +/*! + \title Getting Started with B2Qt.Wifi in C++ + \example wifi/wifi-cpp + \ingroup wifi-examples + \brief Guide to getting started with B2Qt.Wifi using C++. + + \section1 Preparing the Application + + Use the following \c include statement to access the C++ classes: + + \code + #include + \endcode + + Before building your application, add the following statement to your + \c .pro file to link against the B2Qt.Wifi library: + + \code + QT += b2qtwifi + \endcode + + This guide will demonstrate how to create a Qt Widget-based application + that utilizes the B2Qt.Wifi API to set up a wifi network connection. We + will start by looking at how to scan for wifi access points, and how to + display and process this data in the application. At the end of the guide + we will show how to connect directly to a known wifi network configuration. + + \image wifi-cpp.jpg + + \section1 Listing Wifi Networks + + First we need to set up QListView widget which we will use to list wifi + networks that can be detected by the device. The detected network access + points are packed as a list-based data model and can be retrieved using + QWifiManager::networks. Here we also set a custom item delegate and + connect to two QWifiManager signals. + + \snippet wifi/wifi-cpp/main.cpp 0 + + \section1 Creating a Delegate + + The Wifi network model has many data roles that describe the different + properties of Wifi network. This data can be used by an application to list + detailed network information and/or to create QWifiConfiguration objects. + In this example we are interested in the network name. In the paint() + method we check if the network name is equal to the currently active + network connection, and append appropriate network state information. + + \snippet wifi/wifi-cpp/main.cpp 1 + + \section1 Connecting to a Selected Network + + On press of the \uicontrol Connect button, connetToNetwork() slot gets + invoked. In this slot we query network properties for the selected network + and create a QWifiConfiguration object, which we later pass to the + QWifiManager::connect function to set up a connection. During this + operation any changes in the network state is reported by QWifiManager + asynchronously. + + \snippet wifi/wifi-cpp/main.cpp 2 + + We use QWifiManager::NetworkState change event handler to trigger the + repainting of the delegate. This way, we can present a current network + state to the user. + + \snippet wifi/wifi-cpp/main.cpp 4 + + \section1 Connecting To a Known Network + + If you already know the network configuration beforehand, you can skip the + network scanning, listing and selection steps. This can be a valid use-case + for devices that do not change their physical location. + + QWifiManager::BackendState change events are reported asynchronously, so we + must connect the signal to a slot that connects to the network access point + after the backend initialization is complete. + + \snippet wifi/wifi-cpp/main.cpp 3 + */ diff --git a/examples/wifi/wifi-cpp/main.cpp b/examples/wifi/wifi-cpp/main.cpp new file mode 100644 index 0000000..54a35e9 --- /dev/null +++ b/examples/wifi/wifi-cpp/main.cpp @@ -0,0 +1,228 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc +** All rights reserved. +** For any questions to Digia, please use the contact form at +** http://www.qt.io +** +** This file is part of Qt Enterprise Embedded. +** +** Licensees holding valid Qt Enterprise licenses may use this file in +** accordance with the Qt Enterprise License Agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. +** +** If you have questions regarding the use of this file, please use +** the contact form at http://www.qt.io +** +****************************************************************************/ +#include +#include +#include + +class NetworkDelegate : public QStyledItemDelegate +{ + Q_OBJECT +//! [1] +public: + NetworkDelegate(QObject *parent = 0) + : QStyledItemDelegate(parent) + { + m_wifiManager = QWifiManager::instance(); + } + + void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const + { + QStyledItemDelegate::paint(painter, option, index); + painter->save(); + QString ssid = qvariant_cast(index.data(QWifiManager::SSID)); + if (ssid == m_wifiManager->currentSSID()) + ssid += networkStateText(); + painter->drawText(option.rect, Qt::AlignVCenter, ssid); + painter->restore(); + } + + QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const + { + QFont font = QApplication::font(); + QFontMetrics fm(font); + return QSize(option.rect.width(), fm.height() * 2); + } + +protected: + QString networkStateText() const + { + QWifiManager::NetworkState networkState = m_wifiManager->networkState(); + switch (networkState) { + case QWifiManager::Disconnected: + return QStringLiteral(""); + break; + case QWifiManager::Authenticating: + return QStringLiteral(" (authenticating)"); + break; + case QWifiManager::HandshakeFailed: + return QStringLiteral(" (handshake failed)"); + break; + case QWifiManager::ObtainingIPAddress: + return QStringLiteral(" (obtaining IP address)"); + break; + case QWifiManager::DhcpRequestFailed: + return QStringLiteral(" (dhcp request failed)"); + break; + case QWifiManager::Connected: + return QStringLiteral(" (connected)"); + break; + } + } +//! [1] +private: + QWifiManager *m_wifiManager; +}; + +class WifiSettings : public QWidget +{ + Q_OBJECT +public: + //! [0] + WifiSettings(QWidget *parent = 0) + : QWidget(parent) + , m_listView(new QListView(this)) + , m_networkDelegate(new NetworkDelegate(this)) + { + m_wifiManager = QWifiManager::instance(); + m_listView->setModel(m_wifiManager->networks()); + m_listView->setItemDelegate(m_networkDelegate); + + connect(m_wifiManager, &QWifiManager::backendStateChanged, + this, &WifiSettings::handleBackendStateChanged); + connect(m_wifiManager, &QWifiManager::networkStateChanged, + this, &WifiSettings::handleNetworkStateChanged); + + setupWidgets(); + } + //! [0] +protected: + void setupWidgets() + { + m_backendStateReporter = new QLabel(this); + handleBackendStateChanged(m_wifiManager->backendState()); + m_passwordInput = new QLineEdit(this); + m_passwordInput->setPlaceholderText("Enter Password"); + + QPushButton *connectButton = new QPushButton("Connect", this); + QPushButton *disconnectButton = new QPushButton("Disconnect", this); + QPushButton *startBackendButton = new QPushButton("Switch On", this); + QPushButton *stopBackendButton = new QPushButton("Switch Off", this); + + connect(startBackendButton, &QPushButton::clicked, m_wifiManager, &QWifiManager::start); + connect(stopBackendButton, &QPushButton::clicked, m_wifiManager, &QWifiManager::stop); + connect(connectButton, &QPushButton::clicked, this, &WifiSettings::connectToNetwork); + connect(disconnectButton, &QPushButton::clicked, m_wifiManager, &QWifiManager::disconnect); + + QGridLayout *grid = new QGridLayout(this); + grid->addWidget(connectButton, 0, 0); + grid->addWidget(disconnectButton, 0, 1); + grid->addWidget(startBackendButton, 1, 0); + grid->addWidget(stopBackendButton, 1, 1); + grid->addWidget(m_listView, 2, 0, 1, 2); + grid->addWidget(m_passwordInput, 3, 0, 1, 2); + grid->addWidget(m_backendStateReporter, 4, 0, 1, 2); + setLayout(grid); + } + + +protected slots: + void handleBackendStateChanged(QWifiManager::BackendState state) + { + switch (state) { + case QWifiManager::Running: + m_wifiManager->setScanning(true); + m_backendStateReporter->setText("wifi backend state: running<\b>"); + break; + case QWifiManager::NotRunning: + m_wifiManager->setScanning(false); + m_backendStateReporter->setText("wifi backend state: stopped<\b>"); + break; + case QWifiManager::Initializing: + m_backendStateReporter->setText("wifi backend state: initializing<\b>"); + break; + case QWifiManager::Terminating: + m_backendStateReporter->setText("wifi backend state: terminating<\b>"); + break; + } + } + //! [4] + void handleNetworkStateChanged(QWifiManager::NetworkState state) + { + m_listView->viewport()->repaint(); + } + //! [4] + //! [2] + void connectToNetwork() + { + QModelIndex index = m_listView->currentIndex(); + QWifiConfiguration config; + if (index.isValid()) { + QString ssid = qvariant_cast(index.data(QWifiManager::SSID)); + config.setSsid(ssid); + config.setPassphrase(m_passwordInput->text()); + m_wifiManager->connect(&config); + } + } + //! [2] +private: + QWifiManager *m_wifiManager; + QListView *m_listView; + NetworkDelegate *m_networkDelegate; + QLabel *m_backendStateReporter; + QLineEdit *m_passwordInput; +}; + +//! [3] +class WifiConnectionHandler : public QObject +{ + Q_OBJECT +public: + WifiConnectionHandler() + { + // replace with a valid network configuration + m_config.setSsid("my-local-wifi"); + m_config.setPassphrase("helloworld123"); + m_config.setProtocol("WPA"); + m_manager = QWifiManager::instance(); + if (m_manager->backendState() == QWifiManager::Running) { + m_manager->connect(&m_config); + } else { + connect(m_manager, &QWifiManager::backendStateChanged, + this, &WifiConnectionHandler::connectToNetwork); + m_manager->start(); + } + } + +protected slots: + void connectToNetwork(QWifiManager::BackendState state) + { + if (state == QWifiManager::Running) + m_manager->connect(&m_config); + } + +private: + QWifiManager *m_manager; + QWifiConfiguration m_config; +}; +//! [3] + +int main(int argc, char *argv[]) +{ + QApplication a(argc, argv); + + WifiSettings wifiSettingsWindow; + wifiSettingsWindow.show(); + + // disable the above 2 lines before enabling this + // WifiConnectionHandler connectionHandler; + + return a.exec(); +} + +#include "main.moc" diff --git a/examples/wifi/wifi-cpp/wifi-cpp.pro b/examples/wifi/wifi-cpp/wifi-cpp.pro new file mode 100644 index 0000000..f457df3 --- /dev/null +++ b/examples/wifi/wifi-cpp/wifi-cpp.pro @@ -0,0 +1,9 @@ +QT += core widgets b2qtwifi + +TARGET = wifi-cpp +TEMPLATE = app + +target.path = /data/user/qt/$$TARGET +INSTALLS += target + +SOURCES += main.cpp diff --git a/examples/wifi/wifi-qml/WifiConnectionHandler.qml b/examples/wifi/wifi-qml/WifiConnectionHandler.qml new file mode 100644 index 0000000..f3f2c10 --- /dev/null +++ b/examples/wifi/wifi-qml/WifiConnectionHandler.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc +** All rights reserved. +** For any questions to Digia, please use the contact form at +** http://www.qt.io +** +** This file is part of Qt Enterprise Embedded. +** +** Licensees holding valid Qt Enterprise licenses may use this file in +** accordance with the Qt Enterprise License Agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. +** +** If you have questions regarding the use of this file, please use +** the contact form at http://www.qt.io +** +****************************************************************************/ +import QtQuick 2.3 +import B2Qt.Wifi 1.0 + +//! [0] +Item { + WifiConfiguration { + id: localConfig + ssid: "network-for-my-device" + passphrase: "password123" + protocol: "WPA2" + } + + Connections { + target: WifiManager + onBackendStateChanged: { + if (WifiManager.backendState === WifiManager.Running) + WifiManager.connect(localConfig) + } + onNetworkStateChanged: { + if (WifiManager.networkState === WifiManager.Connected) + print("successfully connected to: " + WifiManager.currentSSID) + } + } + + Component.onCompleted: { + if (WifiManager.backendState === WifiManager.Running) { + WifiManager.connect(localConfig) + } else { + WifiManager.start() + } + } +} +//! [0] diff --git a/examples/wifi/wifi-qml/WifiScanner.qml b/examples/wifi/wifi-qml/WifiScanner.qml new file mode 100644 index 0000000..f5ebec2 --- /dev/null +++ b/examples/wifi/wifi-qml/WifiScanner.qml @@ -0,0 +1,251 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc +** All rights reserved. +** For any questions to Digia, please use the contact form at +** http://www.qt.io +** +** This file is part of Qt Enterprise Embedded. +** +** Licensees holding valid Qt Enterprise licenses may use this file in +** accordance with the Qt Enterprise License Agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. +** +** If you have questions regarding the use of this file, please use +** the contact form at http://www.qt.io +** +****************************************************************************/ +import QtQuick 2.3 +import QtQuick.Controls 1.2 +import B2Qt.Wifi 1.0 + +Item { + anchors.fill: parent + + Binding { + target: WifiManager + property: "scanning" + value: networkView.visible + } + + Button { + id: wifiOnOffButton + anchors.top: parent.top + anchors.topMargin: 20 + anchors.left: parent.left + anchors.right: parent.right + onClicked: { + if (WifiManager.backendState === WifiManager.Running) { + if (networkView.visible) + networkView.visible = false + WifiManager.stop() + } else if (WifiManager.backendState === WifiManager.NotRunning) { + WifiManager.start() + } + } + + Component.onCompleted: updateButtonText(WifiManager.backendState) + Connections { + target: WifiManager + onBackendStateChanged: wifiOnOffButton.updateButtonText(backendState) + } + + function updateButtonText(backendState) + { + if (backendState === WifiManager.Initializing) + wifiOnOffButton.text = "Initializing..." + if (backendState === WifiManager.Terminating) + wifiOnOffButton.text = "Terminating..." + if (backendState === WifiManager.NotRunning) + wifiOnOffButton.text = "Switch On" + if (backendState === WifiManager.Running) + wifiOnOffButton.text = "Switch Off" + } + } + + Button { + id: listNetworksButton + anchors.top: wifiOnOffButton.bottom + anchors.topMargin: 30 + anchors.left: parent.left + anchors.right: parent.right + visible: WifiManager.backendState === WifiManager.Running + text: networkView.visible ? "Hide wifi networks" + : "List available wifi networks" + onClicked: networkView.visible = !networkView.visible + } + //! [0] + ListView { + id: networkView + model: WifiManager.networks + delegate: listDelegate + implicitHeight: 800 + anchors.top: listNetworksButton.bottom + anchors.topMargin: 30 + anchors.left: parent.left + anchors.right: parent.right + visible: false + clip: true + + property string networkStateText: "" + property QtObject expandedNetworkBox: null + property bool hasExpandedNetworkBox: expandedNetworkBox !== null + + function setNetworkStateText(networkState) { + if (networkState === WifiManager.ObtainingIPAddress) + networkView.networkStateText = " (obtaining ip..)" + else if (networkState === WifiManager.DhcpRequestFailed) + networkView.networkStateText = " (dhcp request failed)" + else if (networkState === WifiManager.Connected) + networkView.networkStateText = " (connected)" + else if (networkState === WifiManager.Authenticating) + networkView.networkStateText = " (authenticating..)" + else if (networkState === WifiManager.HandshakeFailed) + networkView.networkStateText = " (wrong password)" + else if (networkState === WifiManager.Disconnected) + networkView.networkStateText = "" + } + + Connections { + target: WifiManager + onNetworkStateChanged: networkView.setNetworkStateText(networkState) + } + } + //! [0] + //! [2] + WifiConfiguration { id: config } + //! [2] + Component { + id: listDelegate + Rectangle { + id: networkBox + property bool expanded: false + property bool isCurrentNetwork: WifiManager.currentSSID === ssid + property bool connected: isCurrentNetwork && WifiManager.networkState === WifiManager.Connected + property int notExpandedHeight: ssidLabel.height + bssidLabel.height + 20 + property int expandedHeight: notExpandedHeight + passwordInput.height + connectionButton.height + 54 + property int connectedExpandedHeight: notExpandedHeight + connectionButton.height + 30 + height: expanded ? (connected ? connectedExpandedHeight : expandedHeight) : notExpandedHeight + width: parent.width + clip: true + color: "#5C5C5C" + border.color: "black" + border.width: 1 + + Component.onDestruction: if (expanded) networkView.expandedNetworkBox = null + onHeightChanged: if (expanded) networkView.positionViewAtIndex(index, ListView.Contain) + + Behavior on height { NumberAnimation { duration: 500; easing.type: Easing.InOutCubic } } + //! [1] + Text { + id: ssidLabel + anchors.top: parent.top + anchors.left: parent.left + anchors.margins: 5 + anchors.leftMargin: 10 + font.pixelSize: 26 + font.bold: true + color: "#E6E6E6" + text: isCurrentNetwork ? ssid + networkView.networkStateText : ssid + Component.onCompleted: networkView.setNetworkStateText(WifiManager.networkState) + } + + Text { + id: bssidLabel + anchors.top: ssidLabel.bottom + anchors.left: parent.left + anchors.margins: 5 + anchors.leftMargin: 30 + text: bssid + color: "#E6E6E6" + font.pixelSize: ssidLabel.font.pixelSize * 0.8 + } + + Text { + id: flagsLabel + anchors.top: bssidLabel.top + anchors.left: bssidLabel.right + anchors.leftMargin: 35 + text: (supportsWPA2 ? "WPA2 " : "") + + (supportsWPA ? "WPA " : "") + + (supportsWEP ? "WEP " : "") + + (supportsWPS ? "WPS " : ""); + color: "#E6E6E6" + font.pixelSize: ssidLabel.font.pixelSize * 0.8 + font.italic: true + } + + Rectangle { + id: signalStrengthBar + height: 15 + radius: 20 + antialiasing: true + anchors.margins: 10 + anchors.right: parent.right + anchors.top: parent.top + color: "#BF8888" + border.color: "#212126" + property int strengthBarWidth: Math.max(100 + signalStrength, 0) / 100 * parent.width + onStrengthBarWidthChanged: { + if (strengthBarWidth > parent.width * 0.55) + signalStrengthBar.width = parent.width * 0.55 + else + signalStrengthBar.width = strengthBarWidth + } + } + //! [1] + MouseArea { + anchors.fill: parent + onClicked: handleNetworkBoxExpanding() + } + + function handleNetworkBoxExpanding() + { + expanded = !expanded + if (expanded) { + if (networkView.hasExpandedNetworkBox) + networkView.expandedNetworkBox.expanded = false + networkView.expandedNetworkBox = networkBox + } else { + networkView.expandedNetworkBox = null + } + } + + TextField { + id: passwordInput + anchors.top: flagsLabel.bottom + anchors.topMargin: 15 + anchors.horizontalCenter: parent.horizontalCenter + width: parent.width * 0.36 + height: connectionButton.height * 1.1 + placeholderText: "Enter Password" + visible: !connected + font.pixelSize: 16 + echoMode: TextInput.Password + inputMethodHints: Qt.ImhNoPredictiveText + } + + Button { + id: connectionButton + y: connected ? passwordInput.y + : passwordInput.y + passwordInput.height + 10 + width: passwordInput.width + anchors.horizontalCenter: parent.horizontalCenter + text: connected ? "Disconnect" : "Connect" + //! [3] + onClicked: { + if (connected) { + WifiManager.disconnect() + } else { + config.ssid = ssid; + config.passphrase = passwordInput.text + if (!WifiManager.connect(config)) + print("failed to connect: " + WifiManager.lastError) + } + } + //! [3] + } + } + } +} diff --git a/examples/wifi/wifi-qml/doc/images/wifi-qml.jpg b/examples/wifi/wifi-qml/doc/images/wifi-qml.jpg new file mode 100644 index 0000000..a0780c2 Binary files /dev/null and b/examples/wifi/wifi-qml/doc/images/wifi-qml.jpg differ diff --git a/examples/wifi/wifi-qml/doc/src/wifi-qml.qdoc b/examples/wifi/wifi-qml/doc/src/wifi-qml.qdoc new file mode 100644 index 0000000..ba77c1e --- /dev/null +++ b/examples/wifi/wifi-qml/doc/src/wifi-qml.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc +** All rights reserved. +** For any questions to Digia, please use the contact form at +** http://www.qt.io +** +** This file is part of Qt Enterprise Embedded. +** +** Licensees holding valid Qt Enterprise licenses may use this file in +** accordance with the Qt Enterprise License Agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. +** +** If you have questions regarding the use of this file, please use +** the contact form at http://www.qt.io +** +****************************************************************************/ +/*! + + \title Getting Started with B2Qt.Wifi in QML + \example wifi/wifi-qml + \ingroup wifi-examples + \brief Guide to getting started with B2Qt.Wifi using QML. + + \section1 Preparing the Application + + Use the following \c import statement in the QML files to access the B2Qt.Wifi QML types: + + \code + import B2Qt.Wifi 1.0 + \endcode + + This guide will demonstrate how to create a QML based application that utilizes + B2Qt.Wifi API to set up a wifi network connection. We will start by looking at how to scan the + surroundings for wifi access points and how to display and process this data in the application. + At the end of the guide we will show how to connect directly to a known wifi network configuration. + + \image wifi-qml.jpg + + \section1 Listing Wifi Networks + + First we need to set up ListView which we will use to list wifi networks + that can be sensed by the device. The sensed network access points are packed as a list-based + data model and can be retrieved from WifiManager::networks. Here we also set a custom item + delegate and connect to WifiManager::networkStateChanged signal. + + \snippet wifi/wifi-qml/WifiScanner.qml 0 + + \section1 Creating a Delegate + + The wifi network model has many data roles that describe the different properties of wifi networks. + This data can be used by an application to list detailed network information and/or to set up + WifiConfiguration objects. We use these network data roles in our delegate for listing + ssid, bssid, supported security protocols and for signal strengh representation. + + \snippet wifi/wifi-qml/WifiScanner.qml 1 + + \section1 Connecting To a Selected Network + + WifiConfiguration element will be used to describe the network that we want to connect to, + selected from the network list. + + \snippet wifi/wifi-qml/WifiScanner.qml 2 + + When \uicontrol Connect button is clicked we set the network name and password properties on + the \c config and pass it to WifiManager::connect, which sets up a wifi connection behind-the-scenes. + During this operation or whenever there are changes in the network state, QWifiManager provides + asynchronous QWifiManager::NetworkState change events. + + \snippet wifi/wifi-qml/WifiScanner.qml 3 + + \section1 Connecting To a Known Network + + If you are not interested in scanning the environment for wifi network access points and you already + know the network configuration beforehand, the network scanning, listing and selection steps can be + entirely skipped. This can be a valid use-case for devices that won't be changing their physical location. + + QWifiManager::BackendState change events are delivered asynchronously. Therefore we have to add a signal handler + that will connect to the network access point after the backend initialization process has been completed, + if the backend is not already in the initialized state at the time of running this code. + + \snippet wifi/wifi-qml/WifiConnectionHandler.qml 0 + + */ diff --git a/examples/wifi/wifi-qml/main.cpp b/examples/wifi/wifi-qml/main.cpp new file mode 100644 index 0000000..32c6b74 --- /dev/null +++ b/examples/wifi/wifi-qml/main.cpp @@ -0,0 +1,30 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc +** All rights reserved. +** For any questions to Digia, please use the contact form at +** http://www.qt.io +** +** This file is part of Qt Enterprise Embedded. +** +** Licensees holding valid Qt Enterprise licenses may use this file in +** accordance with the Qt Enterprise License Agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. +** +** If you have questions regarding the use of this file, please use +** the contact form at http://www.qt.io +** +****************************************************************************/ +#include +#include + +int main(int argc, char *argv[]) +{ + QGuiApplication app(argc, argv); + + QQmlApplicationEngine engine; + engine.load(QUrl(QStringLiteral("qrc:/main.qml"))); + + return app.exec(); +} diff --git a/examples/wifi/wifi-qml/main.qml b/examples/wifi/wifi-qml/main.qml new file mode 100644 index 0000000..9c8726d --- /dev/null +++ b/examples/wifi/wifi-qml/main.qml @@ -0,0 +1,32 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc +** All rights reserved. +** For any questions to Digia, please use the contact form at +** http://www.qt.io +** +** This file is part of Qt Enterprise Embedded. +** +** Licensees holding valid Qt Enterprise licenses may use this file in +** accordance with the Qt Enterprise License Agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. +** +** If you have questions regarding the use of this file, please use +** the contact form at http://www.qt.io +** +****************************************************************************/ +import QtQuick 2.3 +import QtQuick.Window 2.2 + +Window { + visible: true + width: Screen.width + height: Screen.height + color: "#D9D9D9" + + WifiScanner {} + + // disable the above line before enabling WifiConnectionHandler + // WifiConnectionHandler {} +} diff --git a/examples/wifi/wifi-qml/qml.qrc b/examples/wifi/wifi-qml/qml.qrc new file mode 100644 index 0000000..3c36973 --- /dev/null +++ b/examples/wifi/wifi-qml/qml.qrc @@ -0,0 +1,7 @@ + + + main.qml + WifiScanner.qml + WifiConnectionHandler.qml + + diff --git a/examples/wifi/wifi-qml/wifi-qml.pro b/examples/wifi/wifi-qml/wifi-qml.pro new file mode 100644 index 0000000..70fc76a --- /dev/null +++ b/examples/wifi/wifi-qml/wifi-qml.pro @@ -0,0 +1,11 @@ +TEMPLATE = app + +QT += qml quick + +SOURCES += main.cpp + +RESOURCES += qml.qrc + +target.path = /data/user/qt +export(target.path) +INSTALLS += target diff --git a/examples/wifi/wifi.pro b/examples/wifi/wifi.pro new file mode 100644 index 0000000..9e03f0e --- /dev/null +++ b/examples/wifi/wifi.pro @@ -0,0 +1,4 @@ +TEMPLATE = subdirs + +SUBDIRS += wifi-cpp \ + wifi-qml 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