Most visited

Recently visited

Added in API level 1

ConnectivityManager

public class ConnectivityManager
extends Object

java.lang.Object
   ↳ android.net.ConnectivityManager


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 addDefaultNetworkActiveListener(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 ACTION_CAPTIVE_PORTAL_SIGN_IN

The device has connected to a network that has presented a captive portal, which is blocking Internet connectivity.

String ACTION_RESTRICT_BACKGROUND_CHANGED

A change in the background metered network activity restriction has occurred.

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_CAPTIVE_PORTAL

The lookup key for a CaptivePortal object included with the ACTION_CAPTIVE_PORTAL_SIGN_IN intent.

String EXTRA_CAPTIVE_PORTAL_URL

Key for passing a URL to the captive portal login activity.

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

The lookup key for a Network object included with the intent after successfully finding a network for the applications request.

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().

String EXTRA_NETWORK_REQUEST

The lookup key for a NetworkRequest object included with the intent after successfully finding a network for the applications request.

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 RESTRICT_BACKGROUND_STATUS_DISABLED

Device is not restricting metered network activity while application is running on background.

int RESTRICT_BACKGROUND_STATUS_ENABLED

Device is restricting metered network activity while application is running on background.

int RESTRICT_BACKGROUND_STATUS_WHITELISTED

Device is restricting metered network activity while application is running on background, but application is allowed to bypass it.

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

This constant was deprecated in API level 23. Applications should instead use requestNetwork(NetworkRequest, NetworkCallback) to request a network that uses the TRANSPORT_CELLULAR transport.

int TYPE_MOBILE_MMS

This constant was deprecated in API level 23. Applications should instead use requestNetwork(NetworkRequest, NetworkCallback) to request a network that provides the NET_CAPABILITY_MMS capability.

int TYPE_MOBILE_SUPL

This constant was deprecated in API level 23. Applications should instead use requestNetwork(NetworkRequest, NetworkCallback) to request a network that provides the NET_CAPABILITY_SUPL capability.

int TYPE_VPN

A virtual network using one or more native bearers.

int TYPE_WIFI

The WIFI data connection.

int TYPE_WIMAX

The WiMAX data connection.

Public methods

void addDefaultNetworkActiveListener(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.

boolean bindProcessToNetwork(Network network)

Binds the current process to network.

Network getActiveNetwork()

Returns a Network object corresponding to the currently active default data network.

NetworkInfo getActiveNetworkInfo()

Returns details about the currently active default data network.

NetworkInfo[] getAllNetworkInfo()

This method was deprecated in API level 23. This method does not support multiple connected networks of the same type. Use getAllNetworks() and getNetworkInfo(android.net.Network) instead.

Network[] getAllNetworks()

Returns an array of all Network currently tracked by the framework.

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.

Network getBoundNetworkForProcess()

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

ProxyInfo getDefaultProxy()

Get the current default HTTP proxy settings.

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)

This method was deprecated in API level 23. This method does not support multiple connected networks of the same type. Use getAllNetworks() and getNetworkInfo(android.net.Network) instead.

NetworkInfo getNetworkInfo(Network network)

Returns connection status information about a particular Network.

int getNetworkPreference()

This method was deprecated in API level 21. 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()

This method was deprecated in API level 23. Using this function can lead to other functions throwing IllegalStateException. Use getBoundNetworkForProcess() instead. getBoundNetworkForProcess is a direct replacement.

int getRestrictBackgroundStatus()

Determines if the calling application is subject to metered network restrictions while running on background.

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)

This method was deprecated in API level 23. All APIs accepting a network type are deprecated. There should be no need to validate a network type.

void registerDefaultNetworkCallback(ConnectivityManager.NetworkCallback networkCallback)

Registers to receive notifications about changes in the system default network.

void registerNetworkCallback(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)

Registers to receive notifications about all networks which satisfy the given NetworkRequest.

void registerNetworkCallback(NetworkRequest request, PendingIntent operation)

Registers a PendingIntent to be sent when a network is available which satisfies the given NetworkRequest.

void releaseNetworkRequest(PendingIntent operation)

Removes a request made via requestNetwork(NetworkRequest, android.app.PendingIntent)

This method has the same behavior as unregisterNetworkCallback(android.app.PendingIntent) with respect to releasing network resources and disconnecting.

void removeDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener l)

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

void reportBadNetwork(Network network)

This method was deprecated in API level 23. Use reportNetworkConnectivity(Network, boolean) which allows reporting both working and non-working connectivity.

void reportNetworkConnectivity(Network network, boolean hasConnectivity)

Report to the framework whether a network has working connectivity.

boolean requestBandwidthUpdate(Network network)

Requests bandwidth update for a given Network and returns whether the update request is accepted by ConnectivityService.

void requestNetwork(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)

Request a network to satisfy a set of NetworkCapabilities.

void requestNetwork(NetworkRequest request, PendingIntent operation)

Request a network to satisfy a set of NetworkCapabilities.

boolean requestRouteToHost(int networkType, int hostAddress)

This method was deprecated in API level 21. Deprecated in favor of the requestNetwork(NetworkRequest, NetworkCallback), bindProcessToNetwork(Network) and getSocketFactory() API. In M, and above, this method is unsupported and will throw UnsupportedOperationException if called.

void setNetworkPreference(int preference)

This method was deprecated in API level 21. 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)

This method was deprecated in API level 23. This function can throw IllegalStateException. Use bindProcessToNetwork(Network) instead. bindProcessToNetwork is a direct replacement.

int startUsingNetworkFeature(int networkType, String feature)

This method was deprecated in API level 21. Deprecated in favor of the cleaner requestNetwork(NetworkRequest, NetworkCallback) API. In M, and above, this method is unsupported and will throw UnsupportedOperationException if called.

int stopUsingNetworkFeature(int networkType, String feature)

This method was deprecated in API level 21. Deprecated in favor of the cleaner unregisterNetworkCallback(NetworkCallback) API. In M, and above, this method is unsupported and will throw UnsupportedOperationException if called.

void unregisterNetworkCallback(ConnectivityManager.NetworkCallback networkCallback)

Unregisters callbacks about and possibly releases networks originating from requestNetwork(NetworkRequest, NetworkCallback) and registerNetworkCallback(NetworkRequest, NetworkCallback) calls.

void unregisterNetworkCallback(PendingIntent operation)

Unregisters a callback previously registered via registerNetworkCallback(NetworkRequest, android.app.PendingIntent).

Inherited methods

From class java.lang.Object

Constants

ACTION_BACKGROUND_DATA_SETTING_CHANGED

Added in API level 3
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.

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"

ACTION_CAPTIVE_PORTAL_SIGN_IN

Added in API level 23
String ACTION_CAPTIVE_PORTAL_SIGN_IN

The device has connected to a network that has presented a captive portal, which is blocking Internet connectivity. The user was presented with a notification that network sign in is required, and the user invoked the notification's action indicating they desire to sign in to the network. Apps handling this activity should facilitate signing in to the network. This action includes a Network typed extra called EXTRA_NETWORK that represents the network presenting the captive portal; all communication with the captive portal must be done using this Network object.

This activity includes a CaptivePortal extra named EXTRA_CAPTIVE_PORTAL that can be used to indicate different outcomes of the captive portal sign in to the system:

  • When the app handling this action believes the user has signed in to the network and the captive portal has been dismissed, the app should call reportCaptivePortalDismissed() so the system can reevaluate the network. If reevaluation finds the network no longer subject to a captive portal, the network may become the default active data network.
  • When the app handling this action believes the user explicitly wants to ignore the captive portal and the network, the app should call ignoreNetwork().

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

ACTION_RESTRICT_BACKGROUND_CHANGED

Added in API level 24
String ACTION_RESTRICT_BACKGROUND_CHANGED

A change in the background metered network activity restriction has occurred.

Applications should call getRestrictBackgroundStatus() to check if the restriction applies to them.

This is only sent to registered receivers, not manifest receivers.

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

CONNECTIVITY_ACTION

Added in API level 1
String CONNECTIVITY_ACTION

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"

DEFAULT_NETWORK_PREFERENCE

Added in API level 1
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.

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)

EXTRA_CAPTIVE_PORTAL

Added in API level 23
String EXTRA_CAPTIVE_PORTAL

The lookup key for a CaptivePortal object included with the ACTION_CAPTIVE_PORTAL_SIGN_IN intent. The CaptivePortal object can be used to either indicate to the system that the captive portal has been dismissed or that the user does not want to pursue signing in to captive portal. Retrieve it with getParcelableExtra(String).

Constant Value: "android.net.extra.CAPTIVE_PORTAL"

EXTRA_CAPTIVE_PORTAL_URL

Added in API level 24
String EXTRA_CAPTIVE_PORTAL_URL

Key for passing a URL to the captive portal login activity.

Constant Value: "android.net.extra.CAPTIVE_PORTAL_URL"

EXTRA_EXTRA_INFO

Added in API level 1
String EXTRA_EXTRA_INFO

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"

EXTRA_IS_FAILOVER

Added in API level 1
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. Retrieve it with getBooleanExtra(String, boolean).

Constant Value: "isFailover"

EXTRA_NETWORK

Added in API level 22
String EXTRA_NETWORK

The lookup key for a Network object included with the intent after successfully finding a network for the applications request. Retrieve it with getParcelableExtra(String).

Note that if you intend to invoke openConnection(java.net.URL) then you must get a ConnectivityManager instance before doing so.

Constant Value: "android.net.extra.NETWORK"

EXTRA_NETWORK_INFO

Added in API level 1
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().

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

See also:

Constant Value: "networkInfo"

EXTRA_NETWORK_REQUEST

Added in API level 22
String EXTRA_NETWORK_REQUEST

The lookup key for a NetworkRequest object included with the intent after successfully finding a network for the applications request. Retrieve it with getParcelableExtra(String).

Constant Value: "android.net.extra.NETWORK_REQUEST"

EXTRA_NETWORK_TYPE

Added in API level 17
String EXTRA_NETWORK_TYPE

Network type which triggered a CONNECTIVITY_ACTION broadcast.

See also:

Constant Value: "networkType"

EXTRA_NO_CONNECTIVITY

Added in API level 1
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. Retrieve it with getBooleanExtra(String, boolean).

Constant Value: "noConnectivity"

EXTRA_OTHER_NETWORK_INFO

Added in API level 1
String EXTRA_OTHER_NETWORK_INFO

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"

EXTRA_REASON

Added in API level 1
String EXTRA_REASON

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"

RESTRICT_BACKGROUND_STATUS_DISABLED

Added in API level 24
int RESTRICT_BACKGROUND_STATUS_DISABLED

Device is not restricting metered network activity while application is running on background.

Constant Value: 1 (0x00000001)

RESTRICT_BACKGROUND_STATUS_ENABLED

Added in API level 24
int RESTRICT_BACKGROUND_STATUS_ENABLED

Device is restricting metered network activity while application is running on background.

In this state, application should not try to use the network while running on background, because it would be denied.

Constant Value: 3 (0x00000003)

RESTRICT_BACKGROUND_STATUS_WHITELISTED

Added in API level 24
int RESTRICT_BACKGROUND_STATUS_WHITELISTED

Device is restricting metered network activity while application is running on background, but application is allowed to bypass it.

In this state, application should take action to mitigate metered network access. For example, a music streaming application should switch to a low-bandwidth bitrate.

Constant Value: 2 (0x00000002)

TYPE_BLUETOOTH

Added in API level 13
int TYPE_BLUETOOTH

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)

TYPE_DUMMY

Added in API level 14
int TYPE_DUMMY

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

Constant Value: 8 (0x00000008)

TYPE_ETHERNET

Added in API level 13
int TYPE_ETHERNET

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)

TYPE_MOBILE

Added in API level 1
int TYPE_MOBILE

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)

TYPE_MOBILE_DUN

Added in API level 8
int TYPE_MOBILE_DUN

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)

TYPE_MOBILE_HIPRI

Added in API level 8
int TYPE_MOBILE_HIPRI

This constant was deprecated in API level 23.
Applications should instead use requestNetwork(NetworkRequest, NetworkCallback) to request a network that uses the TRANSPORT_CELLULAR transport.

A High Priority Mobile data connection. This network type uses the same network interface as TYPE_MOBILE but the routing setup is different.

Constant Value: 5 (0x00000005)

TYPE_MOBILE_MMS

Added in API level 8
int TYPE_MOBILE_MMS

This constant was deprecated in API level 23.
Applications should instead use requestNetwork(NetworkRequest, NetworkCallback) to request a network that provides the NET_CAPABILITY_MMS capability.

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)

TYPE_MOBILE_SUPL

Added in API level 8
int TYPE_MOBILE_SUPL

This constant was deprecated in API level 23.
Applications should instead use requestNetwork(NetworkRequest, NetworkCallback) to request a network that provides the NET_CAPABILITY_SUPL capability.

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)

TYPE_VPN

Added in API level 21
int TYPE_VPN

A virtual network using one or more native bearers. It may or may not be providing security services.

Constant Value: 17 (0x00000011)

TYPE_WIFI

Added in API level 1
int TYPE_WIFI

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)

TYPE_WIMAX

Added in API level 8
int TYPE_WIMAX

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

addDefaultNetworkActiveListener

Added in API level 21
void addDefaultNetworkActiveListener (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 bindProcessToNetwork(Network) this function will not reflect the process's default, but the system default.

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

bindProcessToNetwork

Added in API level 23
boolean bindProcessToNetwork (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 bindProcessToNetwork.

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

getActiveNetwork

Added in API level 23
Network getActiveNetwork ()

Returns a Network object corresponding to the currently active default data network. In the event that the current active default data network disconnects, the returned Network object will no longer be usable. This will return null when there is no default network.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

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

getActiveNetworkInfo

Added in API level 1
NetworkInfo getActiveNetworkInfo ()

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.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

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

getAllNetworkInfo

Added in API level 1
NetworkInfo[] getAllNetworkInfo ()

This method was deprecated in API level 23.
This method does not support multiple connected networks of the same type. Use getAllNetworks() and getNetworkInfo(android.net.Network) instead.

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

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

Returns
NetworkInfo[] an array of NetworkInfo objects. Check each getType() for which type each applies.

getAllNetworks

Added in API level 21
Network[] getAllNetworks ()

Returns an array of all Network currently tracked by the framework.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

Returns
Network[] an array of Network objects.

getBackgroundDataSetting

Added in API level 3
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.

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
boolean Whether background data usage is allowed.

getBoundNetworkForProcess

Added in API level 23
Network getBoundNetworkForProcess ()

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

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

getDefaultProxy

Added in API level 23
ProxyInfo getDefaultProxy ()

Get the current default HTTP proxy settings. If a global proxy is set it will be returned, otherwise if this process is bound to a Network using bindProcessToNetwork(Network) then that Network's proxy is returned, otherwise the default network's proxy is returned.

Returns
ProxyInfo the ProxyInfo for the current HTTP proxy, or null if no HTTP proxy is active.

getLinkProperties

Added in API level 21
LinkProperties getLinkProperties (Network network)

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

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

Parameters
network Network: The Network object identifying the network in question.
Returns
LinkProperties The LinkProperties for the network, or null.

getNetworkCapabilities

Added in API level 21
NetworkCapabilities getNetworkCapabilities (Network network)

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

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

Parameters
network Network: The Network object identifying the network in question.
Returns
NetworkCapabilities The NetworkCapabilities for the network, or null.

getNetworkInfo

Added in API level 1
NetworkInfo getNetworkInfo (int networkType)

This method was deprecated in API level 23.
This method does not support multiple connected networks of the same type. Use getAllNetworks() and getNetworkInfo(android.net.Network) instead.

Returns connection status information about a particular network type.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

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

getNetworkInfo

Added in API level 21
NetworkInfo getNetworkInfo (Network network)

Returns connection status information about a particular Network.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

Parameters
network Network: Network specifying which network in which you're interested.
Returns
NetworkInfo a NetworkInfo object for the requested network or null if the Network is not valid.

getNetworkPreference

Added in API level 1
int getNetworkPreference ()

This method was deprecated in API level 21.
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.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

Returns
int an integer representing the preferred network type

getProcessDefaultNetwork

Added in API level 21
Network getProcessDefaultNetwork ()

This method was deprecated in API level 23.
Using this function can lead to other functions throwing IllegalStateException. Use getBoundNetworkForProcess() instead. getBoundNetworkForProcess is a direct replacement.

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

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

getRestrictBackgroundStatus

Added in API level 24
int getRestrictBackgroundStatus ()

Determines if the calling application is subject to metered network restrictions while running on background.

Returns
int RESTRICT_BACKGROUND_STATUS_DISABLED, RESTRICT_BACKGROUND_STATUS_ENABLED, or RESTRICT_BACKGROUND_STATUS_WHITELISTED

isActiveNetworkMetered

Added in API level 16
boolean isActiveNetworkMetered ()

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.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

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

isDefaultNetworkActive

Added in API level 21
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.

Returns
boolean

isNetworkTypeValid

Added in API level 1
boolean isNetworkTypeValid (int networkType)

This method was deprecated in API level 23.
All APIs accepting a network type are deprecated. There should be no need to validate a network type.

Tests if a given integer represents a valid network type.

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

registerDefaultNetworkCallback

Added in API level 24
void registerDefaultNetworkCallback (ConnectivityManager.NetworkCallback networkCallback)

Registers to receive notifications about changes in the system default network. The callbacks will continue to be called until either the application exits or unregisterNetworkCallback(NetworkCallback) is called.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

Parameters
networkCallback ConnectivityManager.NetworkCallback: The ConnectivityManager.NetworkCallback that the system will call as the system default network changes.

registerNetworkCallback

Added in API level 21
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 link #unregisterNetworkCallback(NetworkCallback)} is called.

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

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

registerNetworkCallback

Added in API level 23
void registerNetworkCallback (NetworkRequest request, 
                PendingIntent operation)

Registers a PendingIntent to be sent when a network is available which satisfies the given NetworkRequest. This function behaves identically to the version that takes a NetworkCallback, but instead of ConnectivityManager.NetworkCallback a PendingIntent is used. This means the request may outlive the calling application and get called back when a suitable network is found.

The operation is an Intent broadcast that goes to a broadcast receiver that you registered with registerReceiver(BroadcastReceiver, IntentFilter) or through the <receiver> tag in an AndroidManifest.xml file

The operation Intent is delivered with two extras, a Network typed extra called EXTRA_NETWORK and a NetworkRequest typed extra called EXTRA_NETWORK_REQUEST containing the original requests parameters.

If there is already a request for this Intent registered (with the equality of two Intents defined by filterEquals(Intent)), then it will be removed and replaced by this one, effectively releasing the previous NetworkRequest.

The request may be released normally by calling unregisterNetworkCallback(android.app.PendingIntent).

This method requires the caller to hold the permission ACCESS_NETWORK_STATE.

Parameters
request NetworkRequest: NetworkRequest describing this request.
operation PendingIntent: Action to perform when the network is available (corresponds to the onAvailable(Network) call. Typically comes from getBroadcast(Context, int, Intent, int). Cannot be null.

releaseNetworkRequest

Added in API level 22
void releaseNetworkRequest (PendingIntent operation)

Removes a request made via requestNetwork(NetworkRequest, android.app.PendingIntent)

This method has the same behavior as unregisterNetworkCallback(android.app.PendingIntent) with respect to releasing network resources and disconnecting.

Parameters
operation PendingIntent: A PendingIntent equal (as defined by filterEquals(Intent)) to the PendingIntent passed to requestNetwork(NetworkRequest, android.app.PendingIntent) with the corresponding NetworkRequest you'd like to remove. Cannot be null.

removeDefaultNetworkActiveListener

Added in API level 21
void removeDefaultNetworkActiveListener (ConnectivityManager.OnNetworkActiveListener l)

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

Parameters
l ConnectivityManager.OnNetworkActiveListener: Previously registered listener.

reportBadNetwork

Added in API level 21
void reportBadNetwork (Network network)

This method was deprecated in API level 23.
Use reportNetworkConnectivity(Network, boolean) which allows reporting both working and non-working connectivity.

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 Network: The Network the application was attempting to use or null to indicate the current default network.

reportNetworkConnectivity

Added in API level 23
void reportNetworkConnectivity (Network network, 
                boolean hasConnectivity)

Report to the framework whether a network has working connectivity. This provides a hint to the system that a particular network is providing working connectivity or not. In response the framework may re-evaluate the network's connectivity and might take further action thereafter.

Parameters
network Network: The Network the application was attempting to use or null to indicate the current default network.
hasConnectivity boolean: true if the application was able to successfully access the Internet using network or false if not.

requestBandwidthUpdate

Added in API level 23
boolean requestBandwidthUpdate (Network network)

Requests bandwidth update for a given Network and returns whether the update request is accepted by ConnectivityService. Once accepted, ConnectivityService will poll underlying network connection for updated bandwidth information. The caller will be notified via ConnectivityManager.NetworkCallback if there is an update. Notice that this method assumes that the caller has previously called registerNetworkCallback(NetworkRequest, NetworkCallback) to listen for network changes.

Parameters
network Network: Network specifying which network you're interested.
Returns
boolean true on success, false if the Network is no longer valid.

requestNetwork

Added in API level 21
void requestNetwork (NetworkRequest request, 
                ConnectivityManager.NetworkCallback networkCallback)

Request a network to satisfy a set of NetworkCapabilities. This NetworkRequest will live until released via unregisterNetworkCallback(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.

It is presently unsupported to request a network with mutable NetworkCapabilities such as NET_CAPABILITY_VALIDATED or NET_CAPABILITY_CAPTIVE_PORTAL as these NetworkCapabilities represent states that a particular network may never attain, and whether a network will attain these states is unknown prior to bringing up the network so the framework does not know how to go about satisfing a request with these capabilities.

This method requires the caller to hold either the CHANGE_NETWORK_STATE permission or the ability to modify system settings as determined by canWrite(Context).

Parameters
request NetworkRequest: NetworkRequest describing this request.
networkCallback ConnectivityManager.NetworkCallback: The ConnectivityManager.NetworkCallback to be utilized for this request. Note the callback must not be shared - they uniquely specify this request.
Throws
IllegalArgumentException if request specifies any mutable NetworkCapabilities.

requestNetwork

Added in API level 22
void requestNetwork (NetworkRequest request, 
                PendingIntent operation)

Request a network to satisfy a set of NetworkCapabilities. This function behaves identically to the version that takes a NetworkCallback, but instead of ConnectivityManager.NetworkCallback a PendingIntent is used. This means the request may outlive the calling application and get called back when a suitable network is found.

The operation is an Intent broadcast that goes to a broadcast receiver that you registered with registerReceiver(BroadcastReceiver, IntentFilter) or through the <receiver> tag in an AndroidManifest.xml file

The operation Intent is delivered with two extras, a Network typed extra called EXTRA_NETWORK and a NetworkRequest typed extra called EXTRA_NETWORK_REQUEST containing the original requests parameters. It is important to create a new, ConnectivityManager.NetworkCallback based request before completing the processing of the Intent to reserve the network or it will be released shortly after the Intent is processed.

If there is already a request for this Intent registered (with the equality of two Intents defined by filterEquals(Intent)), then it will be removed and replaced by this one, effectively releasing the previous NetworkRequest.

The request may be released normally by calling releaseNetworkRequest(android.app.PendingIntent).

It is presently unsupported to request a network with either NET_CAPABILITY_VALIDATED or NET_CAPABILITY_CAPTIVE_PORTAL as these NetworkCapabilities represent states that a particular network may never attain, and whether a network will attain these states is unknown prior to bringing up the network so the framework does not know how to go about satisfing a request with these capabilities.

This method requires the caller to hold either the CHANGE_NETWORK_STATE permission or the ability to modify system settings as determined by canWrite(Context).

Parameters
request NetworkRequest: NetworkRequest describing this request.
operation PendingIntent: Action to perform when the network is available (corresponds to the onAvailable(Network) call. Typically comes from getBroadcast(Context, int, Intent, int). Cannot be null.
Throws
IllegalArgumentException if request contains either NET_CAPABILITY_VALIDATED or NET_CAPABILITY_CAPTIVE_PORTAL.

requestRouteToHost

Added in API level 1
boolean requestRouteToHost (int networkType, 
                int hostAddress)

This method was deprecated in API level 21.
Deprecated in favor of the requestNetwork(NetworkRequest, NetworkCallback), bindProcessToNetwork(Network) and getSocketFactory() API. In M, and above, this method is unsupported and will throw UnsupportedOperationException if called.

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 either the CHANGE_NETWORK_STATE permission or the ability to modify system settings as determined by canWrite(Context).

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

setNetworkPreference

Added in API level 1
void setNetworkPreference (int preference)

This method was deprecated in API level 21.
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 int: the network type to prefer over all others. It is unspecified what happens to the old preferred network in the overall ordering.

setProcessDefaultNetwork

Added in API level 21
boolean setProcessDefaultNetwork (Network network)

This method was deprecated in API level 23.
This function can throw IllegalStateException. Use bindProcessToNetwork(Network) instead. bindProcessToNetwork is a direct replacement.

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 Network: The Network to bind the current process to, or null to clear the current binding.
Returns
boolean true on success, false if the Network is no longer valid.

startUsingNetworkFeature

Added in API level 1
int startUsingNetworkFeature (int networkType, 
                String feature)

This method was deprecated in API level 21.
Deprecated in favor of the cleaner requestNetwork(NetworkRequest, NetworkCallback) API. In M, and above, this method is unsupported and will throw UnsupportedOperationException if called.

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 either the CHANGE_NETWORK_STATE permission or the ability to modify system settings as determined by canWrite(Context).

Parameters
networkType int: specifies which network the request pertains to
feature String: the name of the feature to be used
Returns
int 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.

stopUsingNetworkFeature

Added in API level 1
int stopUsingNetworkFeature (int networkType, 
                String feature)

This method was deprecated in API level 21.
Deprecated in favor of the cleaner unregisterNetworkCallback(NetworkCallback) API. In M, and above, this method is unsupported and will throw UnsupportedOperationException if called.

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 either the CHANGE_NETWORK_STATE permission or the ability to modify system settings as determined by canWrite(Context).

Parameters
networkType int: specifies which network the request pertains to
feature String: the name of the feature that is no longer needed
Returns
int 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.

unregisterNetworkCallback

Added in API level 21
void unregisterNetworkCallback (ConnectivityManager.NetworkCallback networkCallback)

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

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

unregisterNetworkCallback

Added in API level 23
void unregisterNetworkCallback (PendingIntent operation)

Unregisters a callback previously registered via registerNetworkCallback(NetworkRequest, android.app.PendingIntent).

Parameters
operation PendingIntent: A PendingIntent equal (as defined by filterEquals(Intent)) to the PendingIntent passed to registerNetworkCallback(NetworkRequest, android.app.PendingIntent). Cannot be null.

Hooray!