Rename networkAccess property to networkAccessible.

Add unit test and update docs.

3 files changed, 99 insertions, 31 deletions

diff --git a/src/network/access/qnetworkaccessmanager.cpp b/src/network/access/qnetworkaccessmanager.cpp
index f52eec5..8fe1857 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 e3dbb40..1d794a2 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 0140268..1785685 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;