ConnectivityManager.java revision 9066cfe9886ac131c34d59ed0e2d287b0e3c0087
1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.net; 18 19import android.annotation.SdkConstant; 20import android.annotation.SdkConstant.SdkConstantType; 21import android.os.RemoteException; 22 23/** 24 * Class that answers queries about the state of network connectivity. It also 25 * notifies applications when network connectivity changes. Get an instance 26 * of this class by calling 27 * {@link android.content.Context#getSystemService(String) Context.getSystemService(Context.CONNECTIVITY_SERVICE)}. 28 * <p> 29 * The primary responsibilities of this class are to: 30 * <ol> 31 * <li>Monitor network connections (Wi-Fi, GPRS, UMTS, etc.)</li> 32 * <li>Send broadcast intents when network connectivity changes</li> 33 * <li>Attempt to "fail over" to another network when connectivity to a network 34 * is lost</li> 35 * <li>Provide an API that allows applications to query the coarse-grained or fine-grained 36 * state of the available networks</li> 37 * </ol> 38 */ 39public class ConnectivityManager 40{ 41 /** 42 * A change in network connectivity has occurred. A connection has either 43 * been established or lost. The NetworkInfo for the affected network is 44 * sent as an extra; it should be consulted to see what kind of 45 * connectivity event occurred. 46 * <p/> 47 * If this is a connection that was the result of failing over from a 48 * disconnected network, then the FAILOVER_CONNECTION boolean extra is 49 * set to true. 50 * <p/> 51 * For a loss of connectivity, if the connectivity manager is attempting 52 * to connect (or has already connected) to another network, the 53 * NetworkInfo for the new network is also passed as an extra. This lets 54 * any receivers of the broadcast know that they should not necessarily 55 * tell the user that no data traffic will be possible. Instead, the 56 * reciever should expect another broadcast soon, indicating either that 57 * the failover attempt succeeded (and so there is still overall data 58 * connectivity), or that the failover attempt failed, meaning that all 59 * connectivity has been lost. 60 * <p/> 61 * For a disconnect event, the boolean extra EXTRA_NO_CONNECTIVITY 62 * is set to {@code true} if there are no connected networks at all. 63 */ 64 public static final String CONNECTIVITY_ACTION = "android.net.conn.CONNECTIVITY_CHANGE"; 65 /** 66 * The lookup key for a {@link NetworkInfo} object. Retrieve with 67 * {@link android.content.Intent#getParcelableExtra(String)}. 68 */ 69 public static final String EXTRA_NETWORK_INFO = "networkInfo"; 70 /** 71 * The lookup key for a boolean that indicates whether a connect event 72 * is for a network to which the connectivity manager was failing over 73 * following a disconnect on another network. 74 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 75 */ 76 public static final String EXTRA_IS_FAILOVER = "isFailover"; 77 /** 78 * The lookup key for a {@link NetworkInfo} object. This is supplied when 79 * there is another network that it may be possible to connect to. Retrieve with 80 * {@link android.content.Intent#getParcelableExtra(String)}. 81 */ 82 public static final String EXTRA_OTHER_NETWORK_INFO = "otherNetwork"; 83 /** 84 * The lookup key for a boolean that indicates whether there is a 85 * complete lack of connectivity, i.e., no network is available. 86 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 87 */ 88 public static final String EXTRA_NO_CONNECTIVITY = "noConnectivity"; 89 /** 90 * The lookup key for a string that indicates why an attempt to connect 91 * to a network failed. The string has no particular structure. It is 92 * intended to be used in notifications presented to users. Retrieve 93 * it with {@link android.content.Intent#getStringExtra(String)}. 94 */ 95 public static final String EXTRA_REASON = "reason"; 96 /** 97 * The lookup key for a string that provides optionally supplied 98 * extra information about the network state. The information 99 * may be passed up from the lower networking layers, and its 100 * meaning may be specific to a particular network type. Retrieve 101 * it with {@link android.content.Intent#getStringExtra(String)}. 102 */ 103 public static final String EXTRA_EXTRA_INFO = "extraInfo"; 104 105 /** 106 * Broadcast Action: The setting for background data usage has changed 107 * values. Use {@link #getBackgroundDataSetting()} to get the current value. 108 * <p> 109 * If an application uses the network in the background, it should listen 110 * for this broadcast and stop using the background data if the value is 111 * false. 112 */ 113 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 114 public static final String ACTION_BACKGROUND_DATA_SETTING_CHANGED = 115 "android.net.conn.BACKGROUND_DATA_SETTING_CHANGED"; 116 117 public static final int TYPE_MOBILE = 0; 118 public static final int TYPE_WIFI = 1; 119 120 public static final int DEFAULT_NETWORK_PREFERENCE = TYPE_WIFI; 121 122 private IConnectivityManager mService; 123 124 static public boolean isNetworkTypeValid(int networkType) { 125 return networkType == TYPE_WIFI || networkType == TYPE_MOBILE; 126 } 127 128 public void setNetworkPreference(int preference) { 129 try { 130 mService.setNetworkPreference(preference); 131 } catch (RemoteException e) { 132 } 133 } 134 135 public int getNetworkPreference() { 136 try { 137 return mService.getNetworkPreference(); 138 } catch (RemoteException e) { 139 return -1; 140 } 141 } 142 143 public NetworkInfo getActiveNetworkInfo() { 144 try { 145 return mService.getActiveNetworkInfo(); 146 } catch (RemoteException e) { 147 return null; 148 } 149 } 150 151 public NetworkInfo getNetworkInfo(int networkType) { 152 try { 153 return mService.getNetworkInfo(networkType); 154 } catch (RemoteException e) { 155 return null; 156 } 157 } 158 159 public NetworkInfo[] getAllNetworkInfo() { 160 try { 161 return mService.getAllNetworkInfo(); 162 } catch (RemoteException e) { 163 return null; 164 } 165 } 166 167 /** {@hide} */ 168 public boolean setRadios(boolean turnOn) { 169 try { 170 return mService.setRadios(turnOn); 171 } catch (RemoteException e) { 172 return false; 173 } 174 } 175 176 /** {@hide} */ 177 public boolean setRadio(int networkType, boolean turnOn) { 178 try { 179 return mService.setRadio(networkType, turnOn); 180 } catch (RemoteException e) { 181 return false; 182 } 183 } 184 185 /** 186 * Tells the underlying networking system that the caller wants to 187 * begin using the named feature. The interpretation of {@code feature} 188 * is completely up to each networking implementation. 189 * @param networkType specifies which network the request pertains to 190 * @param feature the name of the feature to be used 191 * @return an integer value representing the outcome of the request. 192 * The interpretation of this value is specific to each networking 193 * implementation+feature combination, except that the value {@code -1} 194 * always indicates failure. 195 */ 196 public int startUsingNetworkFeature(int networkType, String feature) { 197 try { 198 return mService.startUsingNetworkFeature(networkType, feature); 199 } catch (RemoteException e) { 200 return -1; 201 } 202 } 203 204 /** 205 * Tells the underlying networking system that the caller is finished 206 * using the named feature. The interpretation of {@code feature} 207 * is completely up to each networking implementation. 208 * @param networkType specifies which network the request pertains to 209 * @param feature the name of the feature that is no longer needed 210 * @return an integer value representing the outcome of the request. 211 * The interpretation of this value is specific to each networking 212 * implementation+feature combination, except that the value {@code -1} 213 * always indicates failure. 214 */ 215 public int stopUsingNetworkFeature(int networkType, String feature) { 216 try { 217 return mService.stopUsingNetworkFeature(networkType, feature); 218 } catch (RemoteException e) { 219 return -1; 220 } 221 } 222 223 /** 224 * Ensure that a network route exists to deliver traffic to the specified 225 * host via the specified network interface. An attempt to add a route that 226 * already exists is ignored, but treated as successful. 227 * @param networkType the type of the network over which traffic to the specified 228 * host is to be routed 229 * @param hostAddress the IP address of the host to which the route is desired 230 * @return {@code true} on success, {@code false} on failure 231 */ 232 public boolean requestRouteToHost(int networkType, int hostAddress) { 233 try { 234 return mService.requestRouteToHost(networkType, hostAddress); 235 } catch (RemoteException e) { 236 return false; 237 } 238 } 239 240 /** 241 * Returns the value of the setting for background data usage. If false, 242 * applications should not use the network if the application is not in the 243 * foreground. Developers should respect this setting, and check the value 244 * of this before performing any background data operations. 245 * <p> 246 * All applications that have background services that use the network 247 * should listen to {@link #ACTION_BACKGROUND_DATA_SETTING_CHANGED}. 248 * 249 * @return Whether background data usage is allowed. 250 */ 251 public boolean getBackgroundDataSetting() { 252 try { 253 return mService.getBackgroundDataSetting(); 254 } catch (RemoteException e) { 255 // Err on the side of safety 256 return false; 257 } 258 } 259 260 /** 261 * Sets the value of the setting for background data usage. 262 * 263 * @param allowBackgroundData Whether an application should use data while 264 * it is in the background. 265 * 266 * @attr ref android.Manifest.permission#CHANGE_BACKGROUND_DATA_SETTING 267 * @see #getBackgroundDataSetting() 268 * @hide 269 */ 270 public void setBackgroundDataSetting(boolean allowBackgroundData) { 271 try { 272 mService.setBackgroundDataSetting(allowBackgroundData); 273 } catch (RemoteException e) { 274 } 275 } 276 277 /** 278 * Don't allow use of default constructor. 279 */ 280 @SuppressWarnings({"UnusedDeclaration"}) 281 private ConnectivityManager() { 282 } 283 284 /** 285 * {@hide} 286 */ 287 public ConnectivityManager(IConnectivityManager service) { 288 if (service == null) { 289 throw new IllegalArgumentException( 290 "ConnectivityManager() cannot be constructed with null service"); 291 } 292 mService = service; 293 } 294} 295