net/base/network_change_notifier.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_BASE_NETWORK_CHANGE_NOTIFIER_H_
   6 #define NET_BASE_NETWORK_CHANGE_NOTIFIER_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/observer_list_threadsafe.h"
  10 #include "net/base/net_export.h"
  11
  12 class GURL;
  13
  14 namespace net {
  15
  16 struct DnsConfig;
  17 class HistogramWatcher;
  18 class NetworkChangeNotifierFactory;
  19
  20 #if defined(OS_LINUX)
  21 namespace internal {
  22 class AddressTrackerLinux;
  23 }
  24 #endif
  25
  26 // NetworkChangeNotifier monitors the system for network changes, and notifies
  27 // registered observers of those events.  Observers may register on any thread,
  28 // and will be called back on the thread from which they registered.
  29 // NetworkChangeNotifiers are threadsafe, though they must be created and
  30 // destroyed on the same thread.
  31 class NET_EXPORT NetworkChangeNotifier {
  32  public:
  33   // Using the terminology of the Network Information API:
  34   // http://www.w3.org/TR/netinfo-api.
  35   enum ConnectionType {
  36     CONNECTION_UNKNOWN = 0, // A connection exists, but its type is unknown.
  37     CONNECTION_ETHERNET = 1,
  38     CONNECTION_WIFI = 2,
  39     CONNECTION_2G = 3,
  40     CONNECTION_3G = 4,
  41     CONNECTION_4G = 5,
  42     CONNECTION_NONE = 6     // No connection.
  43   };
  44
  45   class NET_EXPORT IPAddressObserver {
  46    public:
  47     // Will be called when the IP address of the primary interface changes.
  48     // This includes when the primary interface itself changes.
  49     virtual void OnIPAddressChanged() = 0;
  50
  51    protected:
  52     IPAddressObserver() {}
  53     virtual ~IPAddressObserver() {}
  54
  55    private:
  56     DISALLOW_COPY_AND_ASSIGN(IPAddressObserver);
  57   };
  58
  59   class NET_EXPORT ConnectionTypeObserver {
  60    public:
  61     // Will be called when the connection type of the system has changed.
  62     // See NetworkChangeNotifier::GetConnectionType() for important caveats
  63     // about the unreliability of using this signal to infer the ability to
  64     // reach remote sites.
  65     virtual void OnConnectionTypeChanged(ConnectionType type) = 0;
  66
  67    protected:
  68     ConnectionTypeObserver() {}
  69     virtual ~ConnectionTypeObserver() {}
  70
  71    private:
  72     DISALLOW_COPY_AND_ASSIGN(ConnectionTypeObserver);
  73   };
  74
  75   class NET_EXPORT DNSObserver {
  76    public:
  77     // Will be called when the DNS settings of the system may have changed.
  78     // Use GetDnsConfig to obtain the current settings.
  79     virtual void OnDNSChanged() = 0;
  80
  81    protected:
  82     DNSObserver() {}
  83     virtual ~DNSObserver() {}
  84
  85    private:
  86     DISALLOW_COPY_AND_ASSIGN(DNSObserver);
  87   };
  88
  89   virtual ~NetworkChangeNotifier();
  90
  91   // See the description of NetworkChangeNotifier::GetConnectionType().
  92   // Implementations must be thread-safe. Implementations must also be
  93   // cheap as this could be called (repeatedly) from the network thread.
  94   virtual ConnectionType GetCurrentConnectionType() const = 0;
  95
  96   // Replaces the default class factory instance of NetworkChangeNotifier class.
  97   // The method will take over the ownership of |factory| object.
  98   static void SetFactory(NetworkChangeNotifierFactory* factory);
  99
 100   // Creates the process-wide, platform-specific NetworkChangeNotifier.  The
 101   // caller owns the returned pointer.  You may call this on any thread.  You
 102   // may also avoid creating this entirely (in which case nothing will be
 103   // monitored), but if you do create it, you must do so before any other
 104   // threads try to access the API below, and it must outlive all other threads
 105   // which might try to use it.
 106   static NetworkChangeNotifier* Create();
 107
 108   // Returns the connection type.
 109   // A return value of |CONNECTION_NONE| is a pretty strong indicator that the
 110   // user won't be able to connect to remote sites. However, another return
 111   // value doesn't imply that the user will be able to connect to remote sites;
 112   // even if some link is up, it is uncertain whether a particular connection
 113   // attempt to a particular remote site will be successful.
 114   // The returned value only describes the connection currently used by the
 115   // device, and does not take into account other machines on the network. For
 116   // example, if the device is connected using Wifi to a 3G gateway to access
 117   // the internet, the connection type is CONNECTION_WIFI.
 118   static ConnectionType GetConnectionType();
 119
 120   // Retrieve the last read DnsConfig. This could be expensive if the system has
 121   // a large HOSTS file.
 122   static void GetDnsConfig(DnsConfig* config);
 123
 124 #if defined(OS_LINUX)
 125   // Returns the AddressTrackerLinux if present.
 126   static const internal::AddressTrackerLinux* GetAddressTracker();
 127 #endif
 128
 129   // Convenience method to determine if the user is offline.
 130   // Returns true if there is currently no internet connection.
 131   //
 132   // A return value of |true| is a pretty strong indicator that the user
 133   // won't be able to connect to remote sites. However, a return value of
 134   // |false| is inconclusive; even if some link is up, it is uncertain
 135   // whether a particular connection attempt to a particular remote site
 136   // will be successfully.
 137   static bool IsOffline();
 138
 139   // Returns true if |type| is a cellular connection.
 140   // Returns false if |type| is CONNECTION_UNKNOWN, and thus, depending on the
 141   // implementation of GetConnectionType(), it is possible that
 142   // IsConnectionCellular(GetConnectionType()) returns false even if the
 143   // current connection is cellular.
 144   static bool IsConnectionCellular(ConnectionType type);
 145
 146   // Like Create(), but for use in tests.  The mock object doesn't monitor any
 147   // events, it merely rebroadcasts notifications when requested.
 148   static NetworkChangeNotifier* CreateMock();
 149
 150   // Registers |observer| to receive notifications of network changes.  The
 151   // thread on which this is called is the thread on which |observer| will be
 152   // called back with notifications.  This is safe to call if Create() has not
 153   // been called (as long as it doesn't race the Create() call on another
 154   // thread), in which case it will simply do nothing.
 155   static void AddIPAddressObserver(IPAddressObserver* observer);
 156   static void AddConnectionTypeObserver(ConnectionTypeObserver* observer);
 157   static void AddDNSObserver(DNSObserver* observer);
 158
 159   // Unregisters |observer| from receiving notifications.  This must be called
 160   // on the same thread on which AddObserver() was called.  Like AddObserver(),
 161   // this is safe to call if Create() has not been called (as long as it doesn't
 162   // race the Create() call on another thread), in which case it will simply do
 163   // nothing.  Technically, it's also safe to call after the notifier object has
 164   // been destroyed, if the call doesn't race the notifier's destruction, but
 165   // there's no reason to use the API in this risky way, so don't do it.
 166   static void RemoveIPAddressObserver(IPAddressObserver* observer);
 167   static void RemoveConnectionTypeObserver(ConnectionTypeObserver* observer);
 168   static void RemoveDNSObserver(DNSObserver* observer);
 169
 170   // Allow unit tests to trigger notifications.
 171   static void NotifyObserversOfIPAddressChangeForTests() {
 172     NotifyObserversOfIPAddressChange();
 173   }
 174
 175   // Return a string equivalent to |type|.
 176   static const char* ConnectionTypeToString(ConnectionType type);
 177
 178   // Let the NetworkChangeNotifier know we received some data.
 179   // This is used strictly for producing histogram data about the accuracy of
 180   // the NetworkChangenotifier's online detection.
 181   static void NotifyDataReceived(const GURL& source);
 182
 183   // Register the Observer callbacks for producing histogram data.  This
 184   // should be called from the network thread to avoid race conditions.
 185   static void InitHistogramWatcher();
 186
 187  protected:
 188   NetworkChangeNotifier();
 189
 190 #if defined(OS_LINUX)
 191   // Returns the AddressTrackerLinux if present.
 192   // TODO(szym): Retrieve AddressMap from NetworkState. http://crbug.com/144212
 193   virtual const internal::AddressTrackerLinux*
 194       GetAddressTrackerInternal() const;
 195 #endif
 196
 197   // Broadcasts a notification to all registered observers.  Note that this
 198   // happens asynchronously, even for observers on the current thread, even in
 199   // tests.
 200   static void NotifyObserversOfIPAddressChange();
 201   static void NotifyObserversOfConnectionTypeChange();
 202   static void NotifyObserversOfDNSChange();
 203
 204   // Stores |config| in NetworkState and notifies observers.
 205   static void SetDnsConfig(const DnsConfig& config);
 206
 207  private:
 208   friend class HostResolverImplDnsTest;
 209   friend class NetworkChangeNotifierAndroidTest;
 210   friend class NetworkChangeNotifierLinuxTest;
 211   friend class NetworkChangeNotifierWinTest;
 212
 213   class NetworkState;
 214
 215   // Allows a second NetworkChangeNotifier to be created for unit testing, so
 216   // the test suite can create a MockNetworkChangeNotifier, but platform
 217   // specific NetworkChangeNotifiers can also be created for testing.  To use,
 218   // create an DisableForTest object, and then create the new
 219   // NetworkChangeNotifier object.  The NetworkChangeNotifier must be
 220   // destroyed before the DisableForTest object, as its destruction will restore
 221   // the original NetworkChangeNotifier.
 222   class NET_EXPORT_PRIVATE DisableForTest {
 223    public:
 224     DisableForTest();
 225     ~DisableForTest();
 226
 227    private:
 228     // The original NetworkChangeNotifier to be restored on destruction.
 229     NetworkChangeNotifier* network_change_notifier_;
 230   };
 231
 232   const scoped_refptr<ObserverListThreadSafe<IPAddressObserver> >
 233       ip_address_observer_list_;
 234   const scoped_refptr<ObserverListThreadSafe<ConnectionTypeObserver> >
 235       connection_type_observer_list_;
 236   const scoped_refptr<ObserverListThreadSafe<DNSObserver> >
 237       resolver_state_observer_list_;
 238
 239   // The current network state. Hosts DnsConfig, exposed via GetDnsConfig.
 240   scoped_ptr<NetworkState> network_state_;
 241
 242   // A little-piggy-back observer that simply logs UMA histogram data.
 243   scoped_ptr<HistogramWatcher> histogram_watcher_;
 244
 245   DISALLOW_COPY_AND_ASSIGN(NetworkChangeNotifier);
 246 };
 247
 248 }  // namespace net
 249
 250 #endif  // NET_BASE_NETWORK_CHANGE_NOTIFIER_H_