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 f4875015e48532b15d71bd94da6c8d00d9f36da7..3e2de493d32798c624f2ed30da20307a2ba7e430 100644
--- a/net/base/network_change_notifier.h
+++ b/net/base/network_change_notifier.h
@@ -31,6 +31,18 @@ class NET_EXPORT NetworkChangeNotifier {
     CHANGE_DNS_LOCALHOST = 1 << 2,
   };
 
+  // Using the terminology of the Netwotk Information API:
+  // http://www.w3.org/TR/netinfo-api.
+  enum ConnectionType {
+    CONNECTION_NONE,     // No connection.
+    CONNECTION_UNKNOWN,  // A connection exists, but its type is unknown.
+    CONNECTION_2G,
+    CONNECTION_3G,
+    CONNECTION_4G,
+    CONNECTION_WIFI,
+    CONNECTION_ETHERNET

[wtc, 2012/05/11 01:35:05]

Nit: I suggest listing these enumerators in the same order
as in the Netwotk Information API:
  CONNECTION_UNKNOWN, // A connection exists, but its type is unknown.
  CONNECTION_ETHERNET
  CONNECTION_WIFI,
  CONNECTION_2G,
  CONNECTION_3G,
  CONNECTION_4G,
  CONNECTION_NONE, // No connection.

We can also list CONNECTION_NONE first so that it gets the
value 0.  But it seems that we use CONNECTION_UNKNOWN as the
default initial values.

+  };
+
   class NET_EXPORT IPAddressObserver {
    public:
     virtual ~IPAddressObserver() {}
@@ -46,20 +58,20 @@ class NET_EXPORT NetworkChangeNotifier {
     DISALLOW_COPY_AND_ASSIGN(IPAddressObserver);
   };
 
-  class NET_EXPORT OnlineStateObserver {
+  class NET_EXPORT ConnectionTypeObserver {
    public:
-    virtual ~OnlineStateObserver() {}
+    virtual ~ConnectionTypeObserver() {}
 
-    // Will be called when the online state of the system may have changed.
-    // See NetworkChangeNotifier::IsOffline() for important caveats about
-    // the unreliability of this signal.
-    virtual void OnOnlineStateChanged(bool online) = 0;
+    // Will be called when the connection type of the system may have changed.
+    // See NetworkChangeNotifier::GetConnectionType() for important caveats
+    // about the unreliability of this signal.

[wtc, 2012/05/11 01:35:05]

Does this comment still apply?  Is the "connection type changed"
signal also unreliable?

Perhaps we should change this comment to:
  // Will be called when the connection type of the system has changed.
  // See NetworkChangeNotifier::GetConnectionType() for important caveats
  // about the unreliability of using this signal to infer the ability to
  // reach remote sites.

Note the change from "may have changed" to "has changed".

+    virtual void OnConnectionTypeChanged(ConnectionType type) = 0;
 
    protected:
-    OnlineStateObserver() {}
+    ConnectionTypeObserver() {}
 
    private:
-    DISALLOW_COPY_AND_ASSIGN(OnlineStateObserver);
+    DISALLOW_COPY_AND_ASSIGN(ConnectionTypeObserver);
   };
 
   class NET_EXPORT DNSObserver {
@@ -79,10 +91,10 @@ class NET_EXPORT NetworkChangeNotifier {
 
   virtual ~NetworkChangeNotifier();
 
-  // See the description of NetworkChangeNotifier::IsOffline().
+  // See the description of NetworkChangeNotifier::GetConnectionType().
   // 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 ConnectionType GetCurrentConnectionType() const = 0;
 
   // Replaces the default class factory instance of NetworkChangeNotifier class.
   // The method will take over the ownership of |factory| object.
@@ -96,14 +108,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

[wtc, 2012/05/11 01:35:05]

|NONE| => |CONNECTION_NONE|

+  // won't be able to connect to remote sites. However, another return value is

[wtc, 2012/05/11 01:35:05]

Nit: "another return value is inconclusive" needs more rewriting because
"inconclusive" now means the returned
connection type (rather than the online/offline state) is
inconclusive.

I think we should say "another return value doesn't imply
the user will be able to connect to remote sites."  It's
a little verbose but more clear.

+  // inconclusive; even if some link is up, it is uncertain whether a particular
+  // connection attempt to a particular remote site will be successfully.

[wtc, 2012/05/11 01:35:05]

successfully => successful

+  static ConnectionType GetConnectionType();
 
   // Like Create(), but for use in tests.  The mock object doesn't monitor any
   // events, it merely rebroadcasts notifications when requested.
@@ -115,7 +124,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 AddConnectionTypeObserver(ConnectionTypeObserver* observer);
   static void AddDNSObserver(DNSObserver* observer);
 
   // Unregisters |observer| from receiving notifications.  This must be called
@@ -126,7 +135,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 RemoveConnectionTypeObserver(ConnectionTypeObserver* observer);
   static void RemoveDNSObserver(DNSObserver* observer);
 
   // Allow unit tests to trigger notifications.
@@ -141,7 +150,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 NotifyObserversOfConnectionTypeChange();
   static void NotifyObserversOfDNSChange(unsigned detail);
 
  private:
@@ -167,8 +176,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<ConnectionTypeObserver> >
+      connection_type_observer_list_;
   const scoped_refptr<ObserverListThreadSafe<DNSObserver> >
       resolver_state_observer_list_;