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.
5 #ifndef NET_BASE_NETWORK_CHANGE_NOTIFIER_H_
6 #define NET_BASE_NETWORK_CHANGE_NOTIFIER_H_
10 #include "base/basictypes.h"
11 #include "base/observer_list_threadsafe.h"
12 #include "base/time/time.h"
13 #include "net/base/net_export.h"
20 class HistogramWatcher
;
21 class NetworkChangeNotifierFactory
;
22 struct NetworkInterface
;
23 typedef std::vector
<NetworkInterface
> NetworkInterfaceList
;
28 class AddressTrackerLinux
;
32 // NetworkChangeNotifier monitors the system for network changes, and notifies
33 // registered observers of those events. Observers may register on any thread,
34 // and will be called back on the thread from which they registered.
35 // NetworkChangeNotifiers are threadsafe, though they must be created and
36 // destroyed on the same thread.
37 class NET_EXPORT NetworkChangeNotifier
{
39 // This is a superset of the connection types in the NetInfo v3 specification:
40 // http://w3c.github.io/netinfo/.
42 // A Java counterpart will be generated for this enum.
43 // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.net
45 // New enum values should only be added to the end of the enum and no values
46 // should be modified or reused, as this is reported via UMA.
48 CONNECTION_UNKNOWN
= 0, // A connection exists, but its type is unknown.
49 // Also used as a default value.
50 CONNECTION_ETHERNET
= 1,
55 CONNECTION_NONE
= 6, // No connection.
56 CONNECTION_BLUETOOTH
= 7,
57 CONNECTION_LAST
= CONNECTION_BLUETOOTH
60 // This is the NetInfo v3 set of connection technologies as seen in
61 // http://w3c.github.io/netinfo/. This enum is copied in
62 // NetworkChangeNotifier.java so be sure to change both at once.
64 // A Java counterpart will be generated for this enum.
65 // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.net
66 enum ConnectionSubtype
{
84 SUBTYPE_BLUETOOTH_1_2
,
85 SUBTYPE_BLUETOOTH_2_1
,
86 SUBTYPE_BLUETOOTH_3_0
,
87 SUBTYPE_BLUETOOTH_4_0
,
89 SUBTYPE_FAST_ETHERNET
,
90 SUBTYPE_GIGABIT_ETHERNET
,
91 SUBTYPE_10_GIGABIT_ETHERNET
,
100 SUBTYPE_LAST
= SUBTYPE_OTHER
103 class NET_EXPORT IPAddressObserver
{
105 // Will be called when the IP address of the primary interface changes.
106 // This includes when the primary interface itself changes.
107 virtual void OnIPAddressChanged() = 0;
110 IPAddressObserver() {}
111 virtual ~IPAddressObserver() {}
114 DISALLOW_COPY_AND_ASSIGN(IPAddressObserver
);
117 class NET_EXPORT ConnectionTypeObserver
{
119 // Will be called when the connection type of the system has changed.
120 // See NetworkChangeNotifier::GetConnectionType() for important caveats
121 // about the unreliability of using this signal to infer the ability to
122 // reach remote sites.
123 virtual void OnConnectionTypeChanged(ConnectionType type
) = 0;
126 ConnectionTypeObserver() {}
127 virtual ~ConnectionTypeObserver() {}
130 DISALLOW_COPY_AND_ASSIGN(ConnectionTypeObserver
);
133 class NET_EXPORT DNSObserver
{
135 // Will be called when the DNS settings of the system may have changed.
136 // Use GetDnsConfig to obtain the current settings.
137 virtual void OnDNSChanged() = 0;
141 virtual ~DNSObserver() {}
144 DISALLOW_COPY_AND_ASSIGN(DNSObserver
);
147 class NET_EXPORT NetworkChangeObserver
{
149 // OnNetworkChanged will be called when a change occurs to the host
150 // computer's hardware or software that affects the route network packets
151 // take to any network server. Some examples:
152 // 1. A network connection becoming available or going away. For example
153 // plugging or unplugging an Ethernet cable, WiFi or cellular modem
154 // connecting or disconnecting from a network, or a VPN tunnel being
155 // established or taken down.
156 // 2. An active network connection's IP address changes.
157 // 3. A change to the local IP routing tables.
158 // The signal shall only be produced when the change is complete. For
159 // example if a new network connection has become available, only give the
160 // signal once we think the O/S has finished establishing the connection
161 // (i.e. DHCP is done) to the point where the new connection is usable.
162 // The signal shall not be produced spuriously as it will be triggering some
163 // expensive operations, like socket pools closing all connections and
164 // sockets and then re-establishing them.
165 // |type| indicates the type of the active primary network connection after
166 // the change. Observers performing "constructive" activities like trying
167 // to establish a connection to a server should only do so when
168 // |type != CONNECTION_NONE|. Observers performing "destructive" activities
169 // like resetting already established server connections should only do so
170 // when |type == CONNECTION_NONE|. OnNetworkChanged will always be called
171 // with CONNECTION_NONE immediately prior to being called with an online
172 // state; this is done to make sure that destructive actions take place
173 // prior to constructive actions.
174 virtual void OnNetworkChanged(ConnectionType type
) = 0;
177 NetworkChangeObserver() {}
178 virtual ~NetworkChangeObserver() {}
181 DISALLOW_COPY_AND_ASSIGN(NetworkChangeObserver
);
184 class NET_EXPORT MaxBandwidthObserver
{
186 // Will be called when a change occurs to the network's maximum bandwidth as
187 // defined in http://w3c.github.io/netinfo/. Generally this will only be
188 // called on bandwidth changing network connection/disconnection events.
189 // Some platforms may call it more frequently, such as when WiFi signal
191 // TODO(jkarlin): This is currently only implemented for Android. Implement
192 // on every platform.
193 virtual void OnMaxBandwidthChanged(double max_bandwidth_mbps
) = 0;
196 MaxBandwidthObserver() {}
197 virtual ~MaxBandwidthObserver() {}
200 DISALLOW_COPY_AND_ASSIGN(MaxBandwidthObserver
);
203 virtual ~NetworkChangeNotifier();
205 // See the description of NetworkChangeNotifier::GetConnectionType().
206 // Implementations must be thread-safe. Implementations must also be
207 // cheap as it is called often.
208 virtual ConnectionType
GetCurrentConnectionType() const = 0;
210 // Replaces the default class factory instance of NetworkChangeNotifier class.
211 // The method will take over the ownership of |factory| object.
212 static void SetFactory(NetworkChangeNotifierFactory
* factory
);
214 // Creates the process-wide, platform-specific NetworkChangeNotifier. The
215 // caller owns the returned pointer. You may call this on any thread. You
216 // may also avoid creating this entirely (in which case nothing will be
217 // monitored), but if you do create it, you must do so before any other
218 // threads try to access the API below, and it must outlive all other threads
219 // which might try to use it.
220 static NetworkChangeNotifier
* Create();
222 // Returns the connection type.
223 // A return value of |CONNECTION_NONE| is a pretty strong indicator that the
224 // user won't be able to connect to remote sites. However, another return
225 // value doesn't imply that the user will be able to connect to remote sites;
226 // even if some link is up, it is uncertain whether a particular connection
227 // attempt to a particular remote site will be successful.
228 // The returned value only describes the connection currently used by the
229 // device, and does not take into account other machines on the network. For
230 // example, if the device is connected using Wifi to a 3G gateway to access
231 // the internet, the connection type is CONNECTION_WIFI.
232 static ConnectionType
GetConnectionType();
234 // Returns a theoretical upper limit on download bandwidth, potentially based
235 // on underlying connection type, signal strength, or some other signal. The
236 // default mapping of connection type to maximum bandwidth is provided in the
237 // NetInfo spec: http://w3c.github.io/netinfo/. Host-specific application
238 // permissions may be required, please see host-specific declaration for more
240 static double GetMaxBandwidth();
242 // Retrieve the last read DnsConfig. This could be expensive if the system has
243 // a large HOSTS file.
244 static void GetDnsConfig(DnsConfig
* config
);
246 #if defined(OS_LINUX)
247 // Returns the AddressTrackerLinux if present.
248 static const internal::AddressTrackerLinux
* GetAddressTracker();
251 // Convenience method to determine if the user is offline.
252 // Returns true if there is currently no internet connection.
254 // A return value of |true| is a pretty strong indicator that the user
255 // won't be able to connect to remote sites. However, a return value of
256 // |false| is inconclusive; even if some link is up, it is uncertain
257 // whether a particular connection attempt to a particular remote site
258 // will be successfully.
259 static bool IsOffline();
261 // Returns true if |type| is a cellular connection.
262 // Returns false if |type| is CONNECTION_UNKNOWN, and thus, depending on the
263 // implementation of GetConnectionType(), it is possible that
264 // IsConnectionCellular(GetConnectionType()) returns false even if the
265 // current connection is cellular.
266 static bool IsConnectionCellular(ConnectionType type
);
268 // Gets the current connection type based on |interfaces|. Returns
269 // CONNECTION_NONE if there are no interfaces, CONNECTION_UNKNOWN if two
270 // interfaces have different connection types or the connection type of all
271 // interfaces if they have the same interface type.
272 static ConnectionType
ConnectionTypeFromInterfaceList(
273 const NetworkInterfaceList
& interfaces
);
275 // Like Create(), but for use in tests. The mock object doesn't monitor any
276 // events, it merely rebroadcasts notifications when requested.
277 static NetworkChangeNotifier
* CreateMock();
279 // Registers |observer| to receive notifications of network changes. The
280 // thread on which this is called is the thread on which |observer| will be
281 // called back with notifications. This is safe to call if Create() has not
282 // been called (as long as it doesn't race the Create() call on another
283 // thread), in which case it will simply do nothing.
284 static void AddIPAddressObserver(IPAddressObserver
* observer
);
285 static void AddConnectionTypeObserver(ConnectionTypeObserver
* observer
);
286 static void AddDNSObserver(DNSObserver
* observer
);
287 static void AddNetworkChangeObserver(NetworkChangeObserver
* observer
);
288 static void AddMaxBandwidthObserver(MaxBandwidthObserver
* observer
);
290 // Unregisters |observer| from receiving notifications. This must be called
291 // on the same thread on which AddObserver() was called. Like AddObserver(),
292 // this is safe to call if Create() has not been called (as long as it doesn't
293 // race the Create() call on another thread), in which case it will simply do
294 // nothing. Technically, it's also safe to call after the notifier object has
295 // been destroyed, if the call doesn't race the notifier's destruction, but
296 // there's no reason to use the API in this risky way, so don't do it.
297 static void RemoveIPAddressObserver(IPAddressObserver
* observer
);
298 static void RemoveConnectionTypeObserver(ConnectionTypeObserver
* observer
);
299 static void RemoveDNSObserver(DNSObserver
* observer
);
300 static void RemoveNetworkChangeObserver(NetworkChangeObserver
* observer
);
301 static void RemoveMaxBandwidthObserver(MaxBandwidthObserver
* observer
);
303 // Allow unit tests to trigger notifications.
304 static void NotifyObserversOfIPAddressChangeForTests();
305 static void NotifyObserversOfConnectionTypeChangeForTests(
306 ConnectionType type
);
307 static void NotifyObserversOfNetworkChangeForTests(ConnectionType type
);
309 // Enable or disable notifications from the host. After setting to true, be
310 // sure to pump the RunLoop until idle to finish any preexisting
312 static void SetTestNotificationsOnly(bool test_only
);
314 // Return a string equivalent to |type|.
315 static const char* ConnectionTypeToString(ConnectionType type
);
317 // Let the NetworkChangeNotifier know we received some data.
318 // This is used for producing histogram data about the accuracy of
319 // the NetworkChangenotifier's online detection and rough network
320 // connection measurements.
321 static void NotifyDataReceived(const URLRequest
& request
, int bytes_read
);
323 // Register the Observer callbacks for producing histogram data. This
324 // should be called from the network thread to avoid race conditions.
325 // ShutdownHistogramWatcher() must be called prior to NetworkChangeNotifier
327 static void InitHistogramWatcher();
329 // Unregister the Observer callbacks for producing histogram data. This
330 // should be called from the network thread to avoid race conditions.
331 static void ShutdownHistogramWatcher();
333 // Log the |NCN.NetworkOperatorMCCMNC| histogram.
334 static void LogOperatorCodeHistogram(ConnectionType type
);
336 // Allows a second NetworkChangeNotifier to be created for unit testing, so
337 // the test suite can create a MockNetworkChangeNotifier, but platform
338 // specific NetworkChangeNotifiers can also be created for testing. To use,
339 // create an DisableForTest object, and then create the new
340 // NetworkChangeNotifier object. The NetworkChangeNotifier must be
341 // destroyed before the DisableForTest object, as its destruction will restore
342 // the original NetworkChangeNotifier.
343 class NET_EXPORT DisableForTest
{
349 // The original NetworkChangeNotifier to be restored on destruction.
350 NetworkChangeNotifier
* network_change_notifier_
;
354 // NetworkChanged signal is calculated from the IPAddressChanged and
355 // ConnectionTypeChanged signals. Delay parameters control how long to delay
356 // producing NetworkChanged signal after particular input signals so as to
357 // combine duplicates. In other words if an input signal is repeated within
358 // the corresponding delay period, only one resulting NetworkChange signal is
360 struct NET_EXPORT NetworkChangeCalculatorParams
{
361 NetworkChangeCalculatorParams();
362 // Controls delay after OnIPAddressChanged when transitioning from an
364 base::TimeDelta ip_address_offline_delay_
;
365 // Controls delay after OnIPAddressChanged when transitioning from an
367 base::TimeDelta ip_address_online_delay_
;
368 // Controls delay after OnConnectionTypeChanged when transitioning from an
370 base::TimeDelta connection_type_offline_delay_
;
371 // Controls delay after OnConnectionTypeChanged when transitioning from an
373 base::TimeDelta connection_type_online_delay_
;
376 explicit NetworkChangeNotifier(
377 const NetworkChangeCalculatorParams
& params
=
378 NetworkChangeCalculatorParams());
380 #if defined(OS_LINUX)
381 // Returns the AddressTrackerLinux if present.
382 // TODO(szym): Retrieve AddressMap from NetworkState. http://crbug.com/144212
383 virtual const internal::AddressTrackerLinux
*
384 GetAddressTrackerInternal() const;
387 // See the description of NetworkChangeNotifier::GetMaxBandwidth().
388 // Implementations must be thread-safe. Implementations must also be
389 // cheap as it is called often.
390 virtual double GetCurrentMaxBandwidth() const;
392 // Returns a theoretical upper limit on download bandwidth given a connection
393 // subtype. The mapping of connection type to maximum bandwidth is provided in
394 // the NetInfo spec: http://w3c.github.io/netinfo/.
395 static double GetMaxBandwidthForConnectionSubtype(ConnectionSubtype subtype
);
397 // Broadcasts a notification to all registered observers. Note that this
398 // happens asynchronously, even for observers on the current thread, even in
400 static void NotifyObserversOfIPAddressChange();
401 static void NotifyObserversOfConnectionTypeChange();
402 static void NotifyObserversOfDNSChange();
403 static void NotifyObserversOfNetworkChange(ConnectionType type
);
404 static void NotifyObserversOfMaxBandwidthChange(double max_bandwidth_mbps
);
406 // Stores |config| in NetworkState and notifies observers.
407 static void SetDnsConfig(const DnsConfig
& config
);
410 friend class HostResolverImplDnsTest
;
411 friend class NetworkChangeNotifierAndroidTest
;
412 friend class NetworkChangeNotifierLinuxTest
;
413 friend class NetworkChangeNotifierWinTest
;
416 class NetworkChangeCalculator
;
418 void NotifyObserversOfIPAddressChangeImpl();
419 void NotifyObserversOfConnectionTypeChangeImpl(ConnectionType type
);
420 void NotifyObserversOfDNSChangeImpl();
421 void NotifyObserversOfNetworkChangeImpl(ConnectionType type
);
422 void NotifyObserversOfMaxBandwidthChangeImpl(double max_bandwidth_mbps
);
424 const scoped_refptr
<ObserverListThreadSafe
<IPAddressObserver
>>
425 ip_address_observer_list_
;
426 const scoped_refptr
<ObserverListThreadSafe
<ConnectionTypeObserver
>>
427 connection_type_observer_list_
;
428 const scoped_refptr
<ObserverListThreadSafe
<DNSObserver
>>
429 resolver_state_observer_list_
;
430 const scoped_refptr
<ObserverListThreadSafe
<NetworkChangeObserver
>>
431 network_change_observer_list_
;
432 const scoped_refptr
<ObserverListThreadSafe
<MaxBandwidthObserver
>>
433 max_bandwidth_observer_list_
;
435 // The current network state. Hosts DnsConfig, exposed via GetDnsConfig.
436 scoped_ptr
<NetworkState
> network_state_
;
438 // A little-piggy-back observer that simply logs UMA histogram data.
439 scoped_ptr
<HistogramWatcher
> histogram_watcher_
;
441 // Computes NetworkChange signal from IPAddress and ConnectionType signals.
442 scoped_ptr
<NetworkChangeCalculator
> network_change_calculator_
;
444 // Set true to disable non-test notifications (to prevent flakes in tests).
445 bool test_notifications_only_
;
447 DISALLOW_COPY_AND_ASSIGN(NetworkChangeNotifier
);
452 #endif // NET_BASE_NETWORK_CHANGE_NOTIFIER_H_