FileDocCategorySizeDatePackage
ConnectivityManager.javaAPI DocAndroid 1.5 API11459Wed May 06 22:41:54 BST 2009android.net

ConnectivityManager

public class ConnectivityManager extends Object
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 {@link android.content.Context#getSystemService(String) 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

Fields Summary
public static final String
CONNECTIVITY_ACTION
A change in network connectivity has occurred. A 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 reciever 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 {@code true} if there are no connected networks at all.

public static final String
EXTRA_NETWORK_INFO
The lookup key for a {@link NetworkInfo} object. Retrieve with {@link android.content.Intent#getParcelableExtra(String)}.
public static final 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 {@link android.content.Intent#getBooleanExtra(String,boolean)}.
public static final String
EXTRA_OTHER_NETWORK_INFO
The lookup key for a {@link NetworkInfo} object. This is supplied when there is another network that it may be possible to connect to. Retrieve with {@link android.content.Intent#getParcelableExtra(String)}.
public static final 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 {@link android.content.Intent#getBooleanExtra(String,boolean)}.
public static final 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 {@link android.content.Intent#getStringExtra(String)}.
public static final 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 {@link android.content.Intent#getStringExtra(String)}.
public static final String
ACTION_BACKGROUND_DATA_SETTING_CHANGED
Broadcast Action: The setting for background data usage has changed values. Use {@link #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.

public static final int
TYPE_MOBILE
public static final int
TYPE_WIFI
public static final int
DEFAULT_NETWORK_PREFERENCE
private IConnectivityManager
mService
Constructors Summary
private ConnectivityManager()
Don't allow use of default constructor.
public ConnectivityManager(IConnectivityManager service)
{@hide}

        if (service == null) {
            throw new IllegalArgumentException(
                "ConnectivityManager() cannot be constructed with null service");
        }
        mService = service;
Methods Summary
public NetworkInfogetActiveNetworkInfo()

        try {
            return mService.getActiveNetworkInfo();
        } catch (RemoteException e) {
            return null;
        }
public NetworkInfo[]getAllNetworkInfo()

        try {
            return mService.getAllNetworkInfo();
        } catch (RemoteException e) {
            return null;
        }
public booleangetBackgroundDataSetting()
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 {@link #ACTION_BACKGROUND_DATA_SETTING_CHANGED}.

return
Whether background data usage is allowed.

        try {
            return mService.getBackgroundDataSetting();
        } catch (RemoteException e) {
            // Err on the side of safety 
            return false;
        }
public NetworkInfogetNetworkInfo(int networkType)

        try {
            return mService.getNetworkInfo(networkType);
        } catch (RemoteException e) {
            return null;
        }
public intgetNetworkPreference()

        try {
            return mService.getNetworkPreference();
        } catch (RemoteException e) {
            return -1;
        }
public static booleanisNetworkTypeValid(int networkType)


         
        return networkType == TYPE_WIFI || networkType == TYPE_MOBILE;
public booleanrequestRouteToHost(int networkType, int hostAddress)
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.

param
networkType the type of the network over which traffic to the specified host is to be routed
param
hostAddress the IP address of the host to which the route is desired
return
{@code true} on success, {@code false} on failure

        try {
            return mService.requestRouteToHost(networkType, hostAddress);
        } catch (RemoteException e) {
            return false;
        }
public voidsetBackgroundDataSetting(boolean allowBackgroundData)
Sets the value of the setting for background data usage.

param
allowBackgroundData Whether an application should use data while it is in the background.
attr
ref android.Manifest.permission#CHANGE_BACKGROUND_DATA_SETTING
see
#getBackgroundDataSetting()
hide

        try {
            mService.setBackgroundDataSetting(allowBackgroundData);
        } catch (RemoteException e) {
        }
public voidsetNetworkPreference(int preference)

        try {
            mService.setNetworkPreference(preference);
        } catch (RemoteException e) {
        }
public booleansetRadio(int networkType, boolean turnOn)
{@hide}

        try {
            return mService.setRadio(networkType, turnOn);
        } catch (RemoteException e) {
            return false;
        }
public booleansetRadios(boolean turnOn)
{@hide}

        try {
            return mService.setRadios(turnOn);
        } catch (RemoteException e) {
            return false;
        }
public intstartUsingNetworkFeature(int networkType, java.lang.String feature)
Tells the underlying networking system that the caller wants to begin using the named feature. The interpretation of {@code feature} is completely up to each networking implementation.

param
networkType specifies which network the request pertains to
param
feature the name of the feature to be used
return
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 {@code -1} always indicates failure.

        try {
            return mService.startUsingNetworkFeature(networkType, feature);
        } catch (RemoteException e) {
            return -1;
        }
public intstopUsingNetworkFeature(int networkType, java.lang.String feature)
Tells the underlying networking system that the caller is finished using the named feature. The interpretation of {@code feature} is completely up to each networking implementation.

param
networkType specifies which network the request pertains to
param
feature the name of the feature that is no longer needed
return
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 {@code -1} always indicates failure.

        try {
            return mService.stopUsingNetworkFeature(networkType, feature);
        } catch (RemoteException e) {
            return -1;
        }