Rename networkAccess property to networkAccessible.

Add unit test and update docs.

7 files changed, 225 insertions, 31 deletions

diff --git a/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp b/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp
index 5db6676036..1853650561 100644
--- a/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp
+++ b/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp
@@ -69,3 +69,12 @@ networkAccessManager->setConfiguration(manager.defaultConfiguration());
 //! [3]
 networkAccessManager->setConfiguration(QNetworkConfiguration());
 //! [3]
+
+//! [4]
+networkAccessManager->setNetworkAccessible(QNetworkAccessManager::NotAccessible);
+//! [4]
+
+//! [5]
+networkAccessManager->setNetworkAccessible(QNetworkAccessManager::Accessible);
+//! [5]
+
diff --git a/src/network/access/qnetworkaccessmanager.cpp b/src/network/access/qnetworkaccessmanager.cpp
index f52eec553f..8fe185712b 100644
--- a/src/network/access/qnetworkaccessmanager.cpp
+++ b/src/network/access/qnetworkaccessmanager.cpp
@@ -173,28 +173,46 @@ static void ensureInitialized()
 */
 
 /*!
-    \property QNetworkAccessManager::networkAccess
-    \brief states whether network access is enabled or disabled through this network access
-    manager.
+    \enum QNetworkAccessManager::NetworkAccessibility
+
+    Indicates whether the network is accessible via this network access manager.
+
+    \value UnknownAccessibility     The network accessibility cannot be determined.
+    \value NotAccessible            The network is not currently accessible, either because there
+                                    is currently no network coverage or network access has been
+                                    explicitly disabled by a call to setNetworkAccessible().
+    \value Accessible               The network is accessible.
+
+    \sa networkAccessible
+*/
+
+/*!
+    \property QNetworkAccessManager::networkAccessible
+    \brief whether the network is currently accessible via this network access manager.
 
     \since 4.7
 
-    Network access is enabled by default.
+    If the network is \l {NotAccessible}{not accessible} the network access manager will not
+    process any new network requests, all such requests will fail with an error.  Requests with
+    URLs with the file:// scheme will still be processed.
+
+    By default the value of this property reflects the physical state of the device.  Applications
+    may override it to disable all network requests via this network access manager by calling
 
-    When network access is disabled the network access manager will not process any new network
-    requests, all such requests will fail with an error. Requests with URLs with the file:// scheme
-    will still be processed.
+    \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 4
 
-    This property can be used to enable and disable network access for all clients of a single
-    network access manager instance.
+    Network requests can be reenabled again by calling
+
+    \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 5
+
+    \note Calling setNetworkAccessible() does not change the network state.
 */
 
 /*!
-    \fn void QNetworkAccessManager::networkAccessChanged(bool enabled)
+    \fn void QNetworkAccessManager::networkAccessibleChanged(QNetworkAccessManager::NetworkAccessibility accessible)
 
-    This signal is emitted when the value of the \l networkAccess property changes. If \a enabled
-    is true new requests that access the network will be processed; otherwise new network requests
-    that require network access will fail with an error.
+    This signal is emitted when the value of the \l networkAccessible property changes.
+    \a accessible is the new network accessibility.
 */
 
 /*!
@@ -792,30 +810,42 @@ QNetworkConfiguration QNetworkAccessManager::activeConfiguration() const
 /*!
     \since 4.7
 
-    Enables network access via this QNetworkAccessManager if \a enabled is true; otherwise disables
-    access.
+    Overrides the reported network accessibility.  If \a accessible is NotAccessible the reported
+    network accessiblity will always be NotAccessible.  Otherwise the reported network
+    accessibility will reflect the actual device state.
 */
-void QNetworkAccessManager::setNetworkAccessEnabled(bool enabled)
+void QNetworkAccessManager::setNetworkAccessible(QNetworkAccessManager::NetworkAccessibility accessible)
 {
     Q_D(QNetworkAccessManager);
 
-    if (d->networkAccessEnabled != enabled) {
-        d->networkAccessEnabled = enabled;
-        emit networkAccessChanged(enabled);
+    if (d->networkAccessible != accessible) {
+        NetworkAccessibility previous = networkAccessible();
+        d->networkAccessible = accessible;
+        NetworkAccessibility current = networkAccessible();
+        if (previous != current)
+            emit networkAccessibleChanged(current);
     }
 }
 
 /*!
     \since 4.7
 
-    Returns true if network access via this QNetworkAccessManager is enabled; otherwise returns
-    false.
+    Returns the current network accessibility.
 */
-bool QNetworkAccessManager::networkAccessEnabled() const
+QNetworkAccessManager::NetworkAccessibility QNetworkAccessManager::networkAccessible() const
 {
     Q_D(const QNetworkAccessManager);
 
-    return d->networkAccessEnabled;
+    if (d->networkSession) {
+        // d->online holds online/offline state of this network session.
+        if (d->online)
+            return d->networkAccessible;
+        else
+            return NotAccessible;
+    } else {
+        // Network accessibility is either disabled or unknown.
+        return (d->networkAccessible == NotAccessible) ? NotAccessible : UnknownAccessibility;
+    }
 }
 
 /*!
@@ -875,7 +905,7 @@ QNetworkReply *QNetworkAccessManager::createRequest(QNetworkAccessManager::Opera
 
     // Return a disabled network reply if network access is disabled.
     // Except if the scheme is empty or file://.
-    if (!d->networkAccessEnabled && !(req.url().scheme() == QLatin1String("file") ||
+    if (!d->networkAccessible && !(req.url().scheme() == QLatin1String("file") ||
                                       req.url().scheme().isEmpty())) {
         return new QDisabledNetworkReply(this, req, op);
     }
@@ -1221,6 +1251,13 @@ void QNetworkAccessManagerPrivate::createSession(const QNetworkConfiguration &co
 
     if (!config.isValid()) {
         networkSession = 0;
+        online = false;
+
+        if (networkAccessible == QNetworkAccessManager::NotAccessible)
+            emit q->networkAccessibleChanged(QNetworkAccessManager::NotAccessible);
+        else
+            emit q->networkAccessibleChanged(QNetworkAccessManager::UnknownAccessibility);
+
         return;
     }
 
@@ -1228,12 +1265,16 @@ void QNetworkAccessManagerPrivate::createSession(const QNetworkConfiguration &co
 
     QObject::connect(networkSession, SIGNAL(opened()), q, SIGNAL(networkSessionConnected()));
     QObject::connect(networkSession, SIGNAL(closed()), q, SLOT(_q_networkSessionClosed()));
+    QObject::connect(networkSession, SIGNAL(stateChanged(QNetworkSession::State)),
+                     q, SLOT(_q_networkSessionStateChanged(QNetworkSession::State)));
     QObject::connect(networkSession, SIGNAL(newConfigurationActivated()),
                      q, SLOT(_q_networkSessionNewConfigurationActivated()));
     QObject::connect(networkSession,
                      SIGNAL(preferredConfigurationChanged(QNetworkConfiguration,bool)),
                      q,
                      SLOT(_q_networkSessionPreferredConfigurationChanged(QNetworkConfiguration,bool)));
+
+    _q_networkSessionStateChanged(networkSession->state());
 }
 
 void QNetworkAccessManagerPrivate::_q_networkSessionClosed()
@@ -1263,6 +1304,23 @@ void QNetworkAccessManagerPrivate::_q_networkSessionPreferredConfigurationChange
         networkSession->migrate();
 }
 
+void QNetworkAccessManagerPrivate::_q_networkSessionStateChanged(QNetworkSession::State state)
+{
+    Q_Q(QNetworkAccessManager);
+
+    if (online) {
+        if (state != QNetworkSession::Connected && state != QNetworkSession::Roaming) {
+            online = false;
+            emit q->networkAccessibleChanged(QNetworkAccessManager::NotAccessible);
+        }
+    } else {
+        if (state == QNetworkSession::Connected || state == QNetworkSession::Roaming) {
+            online = true;
+            emit q->networkAccessibleChanged(networkAccessible);
+        }
+    }
+}
+
 QT_END_NAMESPACE
 
 #include "moc_qnetworkaccessmanager.cpp"
diff --git a/src/network/access/qnetworkaccessmanager.h b/src/network/access/qnetworkaccessmanager.h
index e3dbb40e64..1d794a2f2d 100644
--- a/src/network/access/qnetworkaccessmanager.h
+++ b/src/network/access/qnetworkaccessmanager.h
@@ -70,7 +70,7 @@ class Q_NETWORK_EXPORT QNetworkAccessManager: public QObject
 {
     Q_OBJECT
 
-    Q_PROPERTY(bool networkAccess READ networkAccessEnabled WRITE setNetworkAccessEnabled NOTIFY networkAccessChanged)
+    Q_PROPERTY(NetworkAccessibility networkAccessible READ networkAccessible WRITE setNetworkAccessible NOTIFY networkAccessibleChanged)
 
 public:
     enum Operation {
@@ -84,6 +84,12 @@ public:
         UnknownOperation = 0
     };
 
+    enum NetworkAccessibility {
+        UnknownAccessibility = -1,
+        NotAccessible = 0,
+        Accessible = 1
+    };
+
     explicit QNetworkAccessManager(QObject *parent = 0);
     ~QNetworkAccessManager();
 
@@ -113,8 +119,8 @@ public:
     QNetworkConfiguration configuration() const;
     QNetworkConfiguration activeConfiguration() const;
 
-    void setNetworkAccessEnabled(bool enabled);
-    bool networkAccessEnabled() const;
+    void setNetworkAccessible(NetworkAccessibility accessible);
+    NetworkAccessibility networkAccessible() const;
 
 Q_SIGNALS:
 #ifndef QT_NO_NETWORKPROXY
@@ -128,7 +134,7 @@ Q_SIGNALS:
 
     void networkSessionConnected();
 
-    void networkAccessChanged(bool enabled);
+    void networkAccessibleChanged(QNetworkAccessManager::NetworkAccessibility accessible);
 
 protected:
     virtual QNetworkReply *createRequest(Operation op, const QNetworkRequest &request,
@@ -142,6 +148,7 @@ private:
     Q_PRIVATE_SLOT(d_func(), void _q_networkSessionClosed())
     Q_PRIVATE_SLOT(d_func(), void _q_networkSessionNewConfigurationActivated())
     Q_PRIVATE_SLOT(d_func(), void _q_networkSessionPreferredConfigurationChanged(QNetworkConfiguration,bool))
+    Q_PRIVATE_SLOT(d_func(), void _q_networkSessionStateChanged(QNetworkSession::State));
 };
 
 QT_END_NAMESPACE
diff --git a/src/network/access/qnetworkaccessmanager_p.h b/src/network/access/qnetworkaccessmanager_p.h
index 0140268b73..1785685365 100644
--- a/src/network/access/qnetworkaccessmanager_p.h
+++ b/src/network/access/qnetworkaccessmanager_p.h
@@ -58,6 +58,7 @@
 #include "qnetworkaccessbackend_p.h"
 #include "private/qobject_p.h"
 #include "QtNetwork/qnetworkproxy.h"
+#include "QtNetwork/qnetworksession.h"
 
 QT_BEGIN_NAMESPACE
 
@@ -65,7 +66,6 @@ class QAuthenticator;
 class QAbstractNetworkCache;
 class QNetworkAuthenticationCredential;
 class QNetworkCookieJar;
-class QNetworkSession;
 
 class QNetworkAccessManagerPrivate: public QObjectPrivate
 {
@@ -76,7 +76,8 @@ public:
           proxyFactory(0),
 #endif
           networkSession(0),
-          networkAccessEnabled(true),
+          networkAccessible(QNetworkAccessManager::Accessible),
+          online(false),
           initializeSession(true),
           cookieJarCreated(false)
     { }
@@ -109,6 +110,7 @@ public:
     void _q_networkSessionNewConfigurationActivated();
     void _q_networkSessionPreferredConfigurationChanged(const QNetworkConfiguration &config,
                                                         bool isSeamless);
+    void _q_networkSessionStateChanged(QNetworkSession::State state);
 
     // this is the cache for storing downloaded files
     QAbstractNetworkCache *networkCache;
@@ -123,7 +125,8 @@ public:
 
     QNetworkSession *networkSession;
     QString networkConfiguration;
-    bool networkAccessEnabled;
+    QNetworkAccessManager::NetworkAccessibility networkAccessible;
+    bool online;
     bool initializeSession;
 
     bool cookieJarCreated;
diff --git a/tests/auto/network.pro b/tests/auto/network.pro
index 6b24850808..2a7c178efe 100644
--- a/tests/auto/network.pro
+++ b/tests/auto/network.pro
@@ -16,6 +16,7 @@ SUBDIRS=\
     qhttpnetworkreply \
     qhttpsocketengine \
     qnativesocketengine \
+    qnetworkaccessmanager \
     qnetworkaddressentry \
     qnetworkconfigmanager \
     qnetworkconfiguration \
diff --git a/tests/auto/qnetworkaccessmanager/qnetworkaccessmanager.pro b/tests/auto/qnetworkaccessmanager/qnetworkaccessmanager.pro
new file mode 100644
index 0000000000..e2889c140a
--- /dev/null
+++ b/tests/auto/qnetworkaccessmanager/qnetworkaccessmanager.pro
@@ -0,0 +1,5 @@
+load(qttest_p4)
+SOURCES += tst_qnetworkaccessmanager.cpp
+QT = core network
+
+
diff --git a/tests/auto/qnetworkaccessmanager/tst_qnetworkaccessmanager.cpp b/tests/auto/qnetworkaccessmanager/tst_qnetworkaccessmanager.cpp
new file mode 100644
index 0000000000..9267389443
--- /dev/null
+++ b/tests/auto/qnetworkaccessmanager/tst_qnetworkaccessmanager.cpp
@@ -0,0 +1,111 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtTest/QtTest>
+
+#include <QtNetwork/QNetworkAccessManager>
+#include <QtNetwork/QNetworkConfigurationManager>
+
+#include <QtCore/QDebug>
+
+Q_DECLARE_METATYPE(QNetworkAccessManager::NetworkAccessibility);
+
+class tst_QNetworkAccessManager : public QObject
+{
+    Q_OBJECT
+
+public:
+    tst_QNetworkAccessManager();
+
+private slots:
+    void networkAccessible();
+};
+
+tst_QNetworkAccessManager::tst_QNetworkAccessManager()
+{
+}
+
+void tst_QNetworkAccessManager::networkAccessible()
+{
+    QNetworkAccessManager manager;
+
+    qRegisterMetaType<QNetworkAccessManager::NetworkAccessibility>("QNetworkAccessManager::NetworkAccessibility");
+
+    QSignalSpy spy(&manager,
+                   SIGNAL(networkAccessibleChanged(QNetworkAccessManager::NetworkAccessibility)));
+
+    QCOMPARE(manager.isNetworkAccessible(), QNetworkAccessManager::UnknownAccessibility);
+
+    manager.setNetworkAccessible(QNetworkAccessManager::NotAccessible);
+
+    QCOMPARE(spy.count(), 1);
+    QCOMPARE(spy.takeFirst().at(0).value<QNetworkAccessManager::NetworkAccessibility>(),
+             QNetworkAccessManager::NotAccessible);
+    QCOMPARE(manager.isNetworkAccessible(), QNetworkAccessManager::NotAccessible);
+
+    manager.setNetworkAccessible(QNetworkAccessManager::Accessible);
+
+    QCOMPARE(spy.count(), 1);
+    QCOMPARE(spy.takeFirst().at(0).value<QNetworkAccessManager::NetworkAccessibility>(),
+             QNetworkAccessManager::UnknownAccessibility);
+    QCOMPARE(manager.isNetworkAccessible(), QNetworkAccessManager::UnknownAccessibility);
+
+    QNetworkConfigurationManager configManager;
+    QNetworkConfiguration defaultConfig = configManager.defaultConfiguration();
+    if (defaultConfig.isValid()) {
+        manager.setConfiguration(defaultConfig);
+
+        QCOMPARE(spy.count(), 1);
+        QCOMPARE(spy.takeFirst().at(0).value<QNetworkAccessManager::NetworkAccessibility>(),
+                 QNetworkAccessManager::Accessible);
+        QCOMPARE(manager.isNetworkAccessible(), QNetworkAccessManager::Accessible);
+
+        manager.setNetworkAccessible(QNetworkAccessManager::NotAccessible);
+
+        QCOMPARE(spy.count(), 1);
+        QCOMPARE(QNetworkAccessManager::NetworkAccessibility(spy.takeFirst().at(0).toInt()),
+                 QNetworkAccessManager::NotAccessible);
+        QCOMPARE(manager.isNetworkAccessible(), QNetworkAccessManager::NotAccessible);
+    }
+}
+
+QTEST_MAIN(tst_QNetworkAccessManager)
+#include "tst_qnetworkaccessmanager.moc"