Android APIs
public class

ConnectivityManager

extends Object
java.lang.Object
   ↳ android.net.ConnectivityManager

Class Overview

Class that answers queries about the state of network connectivity. It also notifies applications when network connectivity changes. Get an instance of this class by calling Context.getSystemService(Context.CONNECTIVITY_SERVICE).

The primary responsibilities of this class are to:

  1. Monitor network connections (Wi-Fi, GPRS, UMTS, etc.)
  2. Send broadcast intents when network connectivity changes
  3. Attempt to "fail over" to another network when connectivity to a network is lost
  4. Provide an API that allows applications to query the coarse-grained or fine-grained state of the available networks
  5. Provide an API that allows applications to request and select networks for their data traffic

Summary

Nested Classes
class ConnectivityManager.NetworkCallback Base class for NetworkRequest callbacks. 
interface ConnectivityManager.OnNetworkActiveListener Callback for use with registerDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener) to find out when the system default network has gone in to a high power state. 
Constants
String ACTION_BACKGROUND_DATA_SETTING_CHANGED This constant was deprecated in API level 16. As of ICE_CREAM_SANDWICH, availability of background data depends on several combined factors, and this broadcast is no longer sent. Instead, when background data is unavailable, getActiveNetworkInfo() will now appear disconnected. During first boot after a platform upgrade, this broadcast will be sent once if getBackgroundDataSetting() was false before the upgrade.
String CONNECTIVITY_ACTION A change in network connectivity has occurred.
int DEFAULT_NETWORK_PREFERENCE This constant was deprecated in API level 18. Since we support so many more networks now, the single network default network preference can't really express the hierarchy. Instead, the default is defined by the networkAttributes in config.xml. You can determine the current value by calling getNetworkPreference() from an App.
String EXTRA_EXTRA_INFO The lookup key for a string that provides optionally supplied extra information about the network state.
String EXTRA_IS_FAILOVER The lookup key for a boolean that indicates whether a connect event is for a network to which the connectivity manager was failing over following a disconnect on another network.
String EXTRA_NETWORK_INFO This constant was deprecated in API level 14. Since NetworkInfo can vary based on UID, applications should always obtain network information through getActiveNetworkInfo() or getAllNetworkInfo().
String EXTRA_NETWORK_TYPE Network type which triggered a CONNECTIVITY_ACTION broadcast.
String EXTRA_NO_CONNECTIVITY The lookup key for a boolean that indicates whether there is a complete lack of connectivity, i.e., no network is available.
String EXTRA_OTHER_NETWORK_INFO The lookup key for a NetworkInfo object.
String EXTRA_REASON The lookup key for a string that indicates why an attempt to connect to a network failed.
int TYPE_BLUETOOTH The Bluetooth data connection.
int TYPE_DUMMY Dummy data connection.
int TYPE_ETHERNET The Ethernet data connection.
int TYPE_MOBILE The Mobile data connection.
int TYPE_MOBILE_DUN A DUN-specific Mobile data connection.
int TYPE_MOBILE_HIPRI A High Priority Mobile data connection.
int TYPE_MOBILE_MMS An MMS-specific Mobile data connection.
int TYPE_MOBILE_SUPL A SUPL-specific Mobile data connection.
int TYPE_WIFI The WIFI data connection.
int TYPE_WIMAX The WiMAX data connection.
Public Methods
NetworkInfo getActiveNetworkInfo()
Returns details about the currently active default data network.
NetworkInfo[] getAllNetworkInfo()
Returns connection status information about all network types supported by the device.
boolean getBackgroundDataSetting()
This method was deprecated in API level 14. As of ICE_CREAM_SANDWICH, availability of background data depends on several combined factors, and this method will always return true. Instead, when background data is unavailable, getActiveNetworkInfo() will now appear disconnected.
LinkProperties getLinkProperties(Network network)
Get the LinkProperties for the given Network.
NetworkCapabilities getNetworkCapabilities(Network network)
Get the NetworkCapabilities for the given Network.
NetworkInfo getNetworkInfo(int networkType)
Returns connection status information about a particular network type.
int getNetworkPreference()
This method is deprecated. Functionality has been removed as it no longer makes sense, with many more than two networks - we'd need an array to express preference. Instead we use dynamic network properties of the networks to describe their precedence.
static Network getProcessDefaultNetwork()
Returns the Network currently bound to this process via setProcessDefaultNetwork(Network), or null if no Network is explicitly bound.
boolean isActiveNetworkMetered()
Returns if the currently active data network is metered.
boolean isDefaultNetworkActive()
Return whether the data network is currently active.
static boolean isNetworkTypeValid(int networkType)
Tests if a given integer represents a valid network type.
void registerDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener l)
Start listening to reports when the system's default data network is active, meaning it is a good time to perform network traffic.
void registerNetworkCallback(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)
Registers to receive notifications about all networks which satisfy the given NetworkRequest.
void reportBadNetwork(Network network)
Report a problem network to the framework.
void requestNetwork(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)
Request a network to satisfy a set of NetworkCapabilities.
boolean requestRouteToHost(int networkType, int hostAddress)
void setNetworkPreference(int preference)
This method is deprecated. Functionality has been removed as it no longer makes sense, with many more than two networks - we'd need an array to express preference. Instead we use dynamic network properties of the networks to describe their precedence.
static boolean setProcessDefaultNetwork(Network network)
Binds the current process to network.
int startUsingNetworkFeature(int networkType, String feature)
This method is deprecated. Deprecated in favor of the cleaner requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) api.
int stopUsingNetworkFeature(int networkType, String feature)
This method is deprecated. Deprecated in favor of the cleaner requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) api.
void unregisterDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener l)
Remove network active listener previously registered with registerDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener).
void unregisterNetworkCallback(ConnectivityManager.NetworkCallback networkCallback)
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_BACKGROUND_DATA_SETTING_CHANGED

Added in API level 3

This constant was deprecated in API level 16.
As of ICE_CREAM_SANDWICH, availability of background data depends on several combined factors, and this broadcast is no longer sent. Instead, when background data is unavailable, getActiveNetworkInfo() will now appear disconnected. During first boot after a platform upgrade, this broadcast will be sent once if getBackgroundDataSetting() was false before the upgrade.

Broadcast Action: The setting for background data usage has changed values. Use getBackgroundDataSetting() to get the current value.

If an application uses the network in the background, it should listen for this broadcast and stop using the background data if the value is false.

Constant Value: "android.net.conn.BACKGROUND_DATA_SETTING_CHANGED"

public static final String CONNECTIVITY_ACTION

Added in API level 1

A change in network connectivity has occurred. A default connection has either been established or lost. The NetworkInfo for the affected network is sent as an extra; it should be consulted to see what kind of connectivity event occurred.

If this is a connection that was the result of failing over from a disconnected network, then the FAILOVER_CONNECTION boolean extra is set to true.

For a loss of connectivity, if the connectivity manager is attempting to connect (or has already connected) to another network, the NetworkInfo for the new network is also passed as an extra. This lets any receivers of the broadcast know that they should not necessarily tell the user that no data traffic will be possible. Instead, the receiver should expect another broadcast soon, indicating either that the failover attempt succeeded (and so there is still overall data connectivity), or that the failover attempt failed, meaning that all connectivity has been lost.

For a disconnect event, the boolean extra EXTRA_NO_CONNECTIVITY is set to true if there are no connected networks at all.

Constant Value: "android.net.conn.CONNECTIVITY_CHANGE"

public static final int DEFAULT_NETWORK_PREFERENCE

Added in API level 1

This constant was deprecated in API level 18.
Since we support so many more networks now, the single network default network preference can't really express the hierarchy. Instead, the default is defined by the networkAttributes in config.xml. You can determine the current value by calling getNetworkPreference() from an App.

If you want to set the default network preference,you can directly change the networkAttributes array in framework's config.xml.

Constant Value: 1 (0x00000001)

public static final String EXTRA_EXTRA_INFO

Added in API level 1

The lookup key for a string that provides optionally supplied extra information about the network state. The information may be passed up from the lower networking layers, and its meaning may be specific to a particular network type. Retrieve it with getStringExtra(String).

Constant Value: "extraInfo"

public static final String EXTRA_IS_FAILOVER

Added in API level 1

The lookup key for a boolean that indicates whether a connect event is for a network to which the connectivity manager was failing over following a disconnect on another network. Retrieve it with getBooleanExtra(String, boolean).

Constant Value: "isFailover"

public static final String EXTRA_NETWORK_INFO

Added in API level 1

This constant was deprecated in API level 14.
Since NetworkInfo can vary based on UID, applications should always obtain network information through getActiveNetworkInfo() or getAllNetworkInfo().

The lookup key for a NetworkInfo object. Retrieve with getParcelableExtra(String).

Constant Value: "networkInfo"

public static final String EXTRA_NETWORK_TYPE

Added in API level 17

Network type which triggered a CONNECTIVITY_ACTION broadcast. Can be used with getNetworkInfo(int) to get NetworkInfo state based on the calling application.

Constant Value: "networkType"

public static final String EXTRA_NO_CONNECTIVITY

Added in API level 1

The lookup key for a boolean that indicates whether there is a complete lack of connectivity, i.e., no network is available. Retrieve it with getBooleanExtra(String, boolean).

Constant Value: "noConnectivity"

public static final String EXTRA_OTHER_NETWORK_INFO

Added in API level 1

The lookup key for a NetworkInfo object. This is supplied when there is another network that it may be possible to connect to. Retrieve with getParcelableExtra(String).

Constant Value: "otherNetwork"

public static final String EXTRA_REASON

Added in API level 1

The lookup key for a string that indicates why an attempt to connect to a network failed. The string has no particular structure. It is intended to be used in notifications presented to users. Retrieve it with getStringExtra(String).

Constant Value: "reason"

public static final int TYPE_BLUETOOTH

Added in API level 13

The Bluetooth data connection. When active, all data traffic will use this network type's interface by default (it has a default route).

Constant Value: 7 (0x00000007)

public static final int TYPE_DUMMY

Added in API level 14

Dummy data connection. This should not be used on shipping devices.

Constant Value: 8 (0x00000008)

public static final int TYPE_ETHERNET

Added in API level 13

The Ethernet data connection. When active, all data traffic will use this network type's interface by default (it has a default route).

Constant Value: 9 (0x00000009)

public static final int TYPE_MOBILE

Added in API level 1

The Mobile data connection. When active, all data traffic will use this network type's interface by default (it has a default route)

Constant Value: 0 (0x00000000)

public static final int TYPE_MOBILE_DUN

Added in API level 8

A DUN-specific Mobile data connection. This network type may use the same network interface as TYPE_MOBILE or it may use a different one. This is sometimes by the system when setting up an upstream connection for tethering so that the carrier is aware of DUN traffic.

Constant Value: 4 (0x00000004)

public static final int TYPE_MOBILE_HIPRI

Added in API level 8

A High Priority Mobile data connection. This network type uses the same network interface as TYPE_MOBILE but the routing setup is different. Only requesting processes will have access to the Mobile DNS servers and only IP's explicitly requested via requestRouteToHost(int, int) will route over this interface if no default route exists.

Constant Value: 5 (0x00000005)

public static final int TYPE_MOBILE_MMS

Added in API level 8

An MMS-specific Mobile data connection. This network type may use the same network interface as TYPE_MOBILE or it may use a different one. This is used by applications needing to talk to the carrier's Multimedia Messaging Service servers.

Constant Value: 2 (0x00000002)

public static final int TYPE_MOBILE_SUPL

Added in API level 8

A SUPL-specific Mobile data connection. This network type may use the same network interface as TYPE_MOBILE or it may use a different one. This is used by applications needing to talk to the carrier's Secure User Plane Location servers for help locating the device.

Constant Value: 3 (0x00000003)

public static final int TYPE_WIFI

Added in API level 1

The WIFI data connection. When active, all data traffic will use this network type's interface by default (it has a default route).

Constant Value: 1 (0x00000001)

public static final int TYPE_WIMAX

Added in API level 8

The WiMAX data connection. When active, all data traffic will use this network type's interface by default (it has a default route).

Constant Value: 6 (0x00000006)

Public Methods

public NetworkInfo getActiveNetworkInfo ()

Added in API level 1

Returns details about the currently active default data network. When connected, this network is the default route for outgoing connections. You should always check isConnected() before initiating network traffic. This may return null when there is no default network.

Returns
  • a NetworkInfo object for the current default network or null if no network default network is currently active

    This method requires the call to hold the permission ACCESS_NETWORK_STATE.

public NetworkInfo[] getAllNetworkInfo ()

Added in API level 1

Returns connection status information about all network types supported by the device.

Returns

public boolean getBackgroundDataSetting ()

Added in API level 3

This method was deprecated in API level 14.
As of ICE_CREAM_SANDWICH, availability of background data depends on several combined factors, and this method will always return true. Instead, when background data is unavailable, getActiveNetworkInfo() will now appear disconnected.

Returns the value of the setting for background data usage. If false, applications should not use the network if the application is not in the foreground. Developers should respect this setting, and check the value of this before performing any background data operations.

All applications that have background services that use the network should listen to ACTION_BACKGROUND_DATA_SETTING_CHANGED.

Returns
  • Whether background data usage is allowed.

public LinkProperties getLinkProperties (Network network)

Get the LinkProperties for the given Network. This will return null if the network is unknown.

Parameters
network The Network object identifying the network in question.
Returns

public NetworkCapabilities getNetworkCapabilities (Network network)

Get the NetworkCapabilities for the given Network. This will return null if the network is unknown.

Parameters
network The Network object identifying the network in question.
Returns

public NetworkInfo getNetworkInfo (int networkType)

Added in API level 1

Returns connection status information about a particular network type.

Parameters
networkType integer specifying which networkType in which you're interested.
Returns
  • a NetworkInfo object for the requested network type or null if the type is not supported by the device.

    This method requires the call to hold the permission ACCESS_NETWORK_STATE.

public int getNetworkPreference ()

Added in API level 1

This method is deprecated.
Functionality has been removed as it no longer makes sense, with many more than two networks - we'd need an array to express preference. Instead we use dynamic network properties of the networks to describe their precedence.

Retrieves the current preferred network type.

Returns
  • an integer representing the preferred network type

    This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

public static Network getProcessDefaultNetwork ()

Returns the Network currently bound to this process via setProcessDefaultNetwork(Network), or null if no Network is explicitly bound.

Returns
  • Network to which this process is bound, or null.

public boolean isActiveNetworkMetered ()

Added in API level 16

Returns if the currently active data network is metered. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues. You should check this before doing large data transfers, and warn the user or delay the operation until another network is available.

Returns
  • true if large transfers should be avoided, otherwise false.

    This method requires the call to hold the permission ACCESS_NETWORK_STATE.

public boolean isDefaultNetworkActive ()

Return whether the data network is currently active. An active network means that it is currently in a high power state for performing data transmission. On some types of networks, it may be expensive to move and stay in such a state, so it is more power efficient to batch network traffic together when the radio is already in this state. This method tells you whether right now is currently a good time to initiate network traffic, as the network is already active.

public static boolean isNetworkTypeValid (int networkType)

Added in API level 1

Tests if a given integer represents a valid network type.

Parameters
networkType the type to be tested
Returns
  • a boolean. true if the type is valid, else false

public void registerDefaultNetworkActiveListener (ConnectivityManager.OnNetworkActiveListener l)

Start listening to reports when the system's default data network is active, meaning it is a good time to perform network traffic. Use isDefaultNetworkActive() to determine the current state of the system's default network after registering the listener.

If the process default network has been set with setProcessDefaultNetwork(Network) this function will not reflect the process's default, but the system default.

Parameters
l The listener to be told when the network is active.

public void registerNetworkCallback (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)

Registers to receive notifications about all networks which satisfy the given NetworkRequest. The callbacks will continue to be called until either the application exits or unregisterNetworkCallback(ConnectivityManager.NetworkCallback) is called

Parameters
request NetworkRequest describing this request.
networkCallback The ConnectivityManager.NetworkCallback that the system will call as suitable networks change state.

public void reportBadNetwork (Network network)

Report a problem network to the framework. This provides a hint to the system that there might be connectivity problems on this network and may cause the framework to re-evaluate network connectivity and/or switch to another network.

Parameters
network The Network the application was attempting to use or null to indicate the current default network.

public void requestNetwork (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)

Request a network to satisfy a set of NetworkCapabilities. This NetworkRequest will live until released via unregisterNetworkCallback(ConnectivityManager.NetworkCallback) or the calling application exits. Status of the request can be followed by listening to the various callbacks described in ConnectivityManager.NetworkCallback. The Network can be used to direct traffic to the network.

Parameters
request NetworkRequest describing this request.
networkCallback The ConnectivityManager.NetworkCallback to be utilized for this request. Note the callback must not be shared - they uniquely specify this request.

public boolean requestRouteToHost (int networkType, int hostAddress)

Added in API level 1

This method is deprecated.
Deprecated in favor of the requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback), setProcessDefaultNetwork(Network) and getSocketFactory() api.

Ensure that a network route exists to deliver traffic to the specified host via the specified network interface. An attempt to add a route that already exists is ignored, but treated as successful.

This method requires the caller to hold the permission CHANGE_NETWORK_STATE.

Parameters
networkType the type of the network over which traffic to the specified host is to be routed
hostAddress the IP address of the host to which the route is desired
Returns
  • true on success, false on failure

public void setNetworkPreference (int preference)

Added in API level 1

This method is deprecated.
Functionality has been removed as it no longer makes sense, with many more than two networks - we'd need an array to express preference. Instead we use dynamic network properties of the networks to describe their precedence.

Specifies the preferred network type. When the device has more than one type available the preferred network type will be used.

Parameters
preference the network type to prefer over all others. It is unspecified what happens to the old preferred network in the overall ordering.

public static boolean setProcessDefaultNetwork (Network network)

Binds the current process to network. All Sockets created in the future (and not explicitly bound via a bound SocketFactory from Network.getSocketFactory()) will be bound to network. All host name resolutions will be limited to network as well. Note that if network ever disconnects, all Sockets created in this way will cease to work and all host name resolutions will fail. This is by design so an application doesn't accidentally use Sockets it thinks are still bound to a particular Network. To clear binding pass null for network. Using individually bound Sockets created by Network.getSocketFactory().createSocket() and performing network-specific host name resolutions via Network.getAllByName is preferred to calling setProcessDefaultNetwork.

Parameters
network The Network to bind the current process to, or null to clear the current binding.
Returns
  • true on success, false if the Network is no longer valid.

public int startUsingNetworkFeature (int networkType, String feature)

Added in API level 1

This method is deprecated.
Deprecated in favor of the cleaner requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) api.

Tells the underlying networking system that the caller wants to begin using the named feature. The interpretation of feature is completely up to each networking implementation.

This method requires the caller to hold the permission CHANGE_NETWORK_STATE.

Parameters
networkType specifies which network the request pertains to
feature the name of the feature to be used
Returns
  • an integer value representing the outcome of the request. The interpretation of this value is specific to each networking implementation+feature combination, except that the value -1 always indicates failure.

public int stopUsingNetworkFeature (int networkType, String feature)

Added in API level 1

This method is deprecated.
Deprecated in favor of the cleaner requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) api.

Tells the underlying networking system that the caller is finished using the named feature. The interpretation of feature is completely up to each networking implementation.

This method requires the caller to hold the permission CHANGE_NETWORK_STATE.

Parameters
networkType specifies which network the request pertains to
feature the name of the feature that is no longer needed
Returns
  • an integer value representing the outcome of the request. The interpretation of this value is specific to each networking implementation+feature combination, except that the value -1 always indicates failure.

public void unregisterDefaultNetworkActiveListener (ConnectivityManager.OnNetworkActiveListener l)

Remove network active listener previously registered with registerDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener).

Parameters
l Previously registered listener.

public void unregisterNetworkCallback (ConnectivityManager.NetworkCallback networkCallback)

Unregisters callbacks about and possibly releases networks originating from requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) and registerNetworkCallback(NetworkRequest, ConnectivityManager.NetworkCallback) calls. If the given NetworkCallback had previosuly been used with #requestNetwork, any networks that had been connected to only to satisfy that request will be disconnected.

Parameters
networkCallback The ConnectivityManager.NetworkCallback used when making the request.