API for connection type (Ethernet/WIFI/WWAN ...) in NetworkChangeNotifier.

net/base/network_change_notifier.h

Index: net/base/network_change_notifier.h
diff --git a/net/base/network_change_notifier.h b/net/base/network_change_notifier.h
index 94e23a9c5e8a4b8865b7c7abc506ae4f1d45db6e..5ca46808221a8ed22cfc2777c6881cc984c8c873 100644
--- a/net/base/network_change_notifier.h
+++ b/net/base/network_change_notifier.h
@@ -21,6 +21,19 @@ class NetworkChangeNotifierFactory;
 // destroyed on the same thread.
 class NET_EXPORT NetworkChangeNotifier {
  public:
+
+  // Using the terminology of the Netwotk Information API:
+  // http://www.w3.org/TR/netinfo-api.
+  enum ConnectionState {
+    UNKNOWN,
+    NONE,

[joth, 2012/01/10 10:48:35]

Suggest putting NONE first, with a value of 0, as this reinforces the "if (state
!= NONE) ..." pattern for detecting online state.

+    TWO_G,
+    THREE_G,
+    FOUR_G,
+    WIFI,
+    ETHERNET
+  };
+
   class NET_EXPORT IPAddressObserver {
    public:
     virtual ~IPAddressObserver() {}
@@ -36,20 +49,20 @@ class NET_EXPORT NetworkChangeNotifier {
     DISALLOW_COPY_AND_ASSIGN(IPAddressObserver);
   };
 
-  class NET_EXPORT OnlineStateObserver {
+  class NET_EXPORT ConnectionStateObserver {
    public:
-    virtual ~OnlineStateObserver() {}
+    virtual ~ConnectionStateObserver() {}
 
-    // Will be called when the online state of the system may have changed.
+    // Will be called when the connection state of the system may have changed.
     // See NetworkChangeNotifier::IsOffline() for important caveats about

[joth, 2012/01/10 10:48:35]

IsOffline -> GetConnectionState

     // the unreliability of this signal.
-    virtual void OnOnlineStateChanged(bool online) = 0;
+    virtual void OnConnectionStateChanged(ConnectionState state) = 0;
 
    protected:
-    OnlineStateObserver() {}
+    ConnectionStateObserver() {}
 
    private:
-    DISALLOW_COPY_AND_ASSIGN(OnlineStateObserver);
+    DISALLOW_COPY_AND_ASSIGN(ConnectionStateObserver);
   };
 
   class NET_EXPORT DNSObserver {
@@ -70,10 +83,10 @@ class NET_EXPORT NetworkChangeNotifier {
 
   virtual ~NetworkChangeNotifier();
 
-  // See the description of NetworkChangeNotifier::IsOffline().
+  // See the description of NetworkChangeNotifier::GetConnectionState().
   // Implementations must be thread-safe. Implementations must also be
   // cheap as this could be called (repeatedly) from the IO thread.
-  virtual bool IsCurrentlyOffline() const = 0;
+  virtual ConnectionState GetCurrentConnectionState() const = 0;
 
   // Replaces the default class factory instance of NetworkChangeNotifier class.
   // The method will take over the ownership of |factory| object.
@@ -87,14 +100,11 @@ class NET_EXPORT NetworkChangeNotifier {
   // which might try to use it.
   static NetworkChangeNotifier* Create();
 
-  // Returns true if there is currently no internet connection.
-  //
-  // A return value of |true| is a pretty strong indicator that the user
-  // won't be able to connect to remote sites. However, a return value of
-  // |false| is inconclusive; even if some link is up, it is uncertain
-  // whether a particular connection attempt to a particular remote site
-  // will be successfully.
-  static bool IsOffline();
+  // A return value of |NONE| is a pretty strong indicator that the user
+  // won't be able to connect to remote sites. However, another return value is
+  // inconclusive; even if some link is up, it is uncertain whether a particular
+  // connection attempt to a particular remote site will be successfully.
+  static ConnectionState GetConnectionState();

[joth, 2012/01/10 10:48:35]

I'm in two minds about rolling state and connection mode together into one
setting. I guess the contract would be only show a mode beyond 'None' when that
interface is fully connected and operational. Most platforms go through some
intermediate states though (e.g. connected via wifi, not yet got an IP address)
but I think the way the docs are worded (i.e. NONE is the only authoritative
state, the rest are just hints) probably covers this.


Also need to clarify what value would be returned if more than one interface is
available. (presumably report the "faster" - that is enum highest - of them).
Or, could make state into a bitmask of available connection types.

[droger_google, 2012/01/10 11:48:26]

About the bitmasks:
When there are several connections available, the network stack will chose one
of them (usually the faster), and I think we should report only this one. I
don't think the users of these notifications need to know all the connection
types that are not used, and even less to be notified of the changes in unused
connections types.

 
   // Like Create(), but for use in tests.  The mock object doesn't monitor any
   // events, it merely rebroadcasts notifications when requested.
@@ -106,7 +116,7 @@ class NET_EXPORT NetworkChangeNotifier {
   // been called (as long as it doesn't race the Create() call on another
   // thread), in which case it will simply do nothing.
   static void AddIPAddressObserver(IPAddressObserver* observer);
-  static void AddOnlineStateObserver(OnlineStateObserver* observer);
+  static void AddConnectionStateObserver(ConnectionStateObserver* observer);
   static void AddDNSObserver(DNSObserver* observer);
 
   // Unregisters |observer| from receiving notifications.  This must be called
@@ -117,7 +127,7 @@ class NET_EXPORT NetworkChangeNotifier {
   // been destroyed, if the call doesn't race the notifier's destruction, but
   // there's no reason to use the API in this risky way, so don't do it.
   static void RemoveIPAddressObserver(IPAddressObserver* observer);
-  static void RemoveOnlineStateObserver(OnlineStateObserver* observer);
+  static void RemoveConnectionStateObserver(ConnectionStateObserver* observer);
   static void RemoveDNSObserver(DNSObserver* observer);
 
   // Allow unit tests to trigger notifications.
@@ -132,7 +142,7 @@ class NET_EXPORT NetworkChangeNotifier {
   // happens asynchronously, even for observers on the current thread, even in
   // tests.
   static void NotifyObserversOfIPAddressChange();
-  static void NotifyObserversOfOnlineStateChange();
+  static void NotifyObserversOfConnectionStateChange();
   static void NotifyObserversOfDNSChange();
 
  private:
@@ -158,8 +168,8 @@ class NET_EXPORT NetworkChangeNotifier {
 
   const scoped_refptr<ObserverListThreadSafe<IPAddressObserver> >
       ip_address_observer_list_;
-  const scoped_refptr<ObserverListThreadSafe<OnlineStateObserver> >
-      online_state_observer_list_;
+  const scoped_refptr<ObserverListThreadSafe<ConnectionStateObserver> >
+      connection_state_observer_list_;
   const scoped_refptr<ObserverListThreadSafe<DNSObserver> >
       resolver_state_observer_list_;