NetworkInfo.java revision d649c12815bcf944b2c97371f3f60716a42a1557
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.os.Parcelable; 20import android.os.Parcel; 21 22import java.util.EnumMap; 23 24/** 25 * Describes the status of a network interface of a given type 26 * (currently either Mobile or Wifi). 27 */ 28public class NetworkInfo implements Parcelable { 29 30 /** 31 * Coarse-grained network state. This is probably what most applications should 32 * use, rather than {@link android.net.NetworkInfo.DetailedState DetailedState}. 33 * The mapping between the two is as follows: 34 * <br/><br/> 35 * <table> 36 * <tr><td><b>Detailed state</b></td><td><b>Coarse-grained state</b></td></tr> 37 * <tr><td><code>IDLE</code></td><td><code>DISCONNECTED</code></td></tr> 38 * <tr><td><code>SCANNING</code></td><td><code>CONNECTING</code></td></tr> 39 * <tr><td><code>CONNECTING</code></td><td><code>CONNECTING</code></td></tr> 40 * <tr><td><code>AUTHENTICATING</code></td><td><code>CONNECTING</code></td></tr> 41 * <tr><td><code>CONNECTED</code></td><td<code>CONNECTED</code></td></tr> 42 * <tr><td><code>DISCONNECTING</code></td><td><code>DISCONNECTING</code></td></tr> 43 * <tr><td><code>DISCONNECTED</code></td><td><code>DISCONNECTED</code></td></tr> 44 * <tr><td><code>UNAVAILABLE</code></td><td><code>DISCONNECTED</code></td></tr> 45 * <tr><td><code>FAILED</code></td><td><code>DISCONNECTED</code></td></tr> 46 * </table> 47 */ 48 public enum State { 49 CONNECTING, CONNECTED, SUSPENDED, DISCONNECTING, DISCONNECTED, UNKNOWN 50 } 51 52 /** 53 * The fine-grained state of a network connection. This level of detail 54 * is probably of interest to few applications. Most should use 55 * {@link android.net.NetworkInfo.State State} instead. 56 */ 57 public enum DetailedState { 58 /** Ready to start data connection setup. */ 59 IDLE, 60 /** Searching for an available access point. */ 61 SCANNING, 62 /** Currently setting up data connection. */ 63 CONNECTING, 64 /** Network link established, performing authentication. */ 65 AUTHENTICATING, 66 /** Awaiting response from DHCP server in order to assign IP address information. */ 67 OBTAINING_IPADDR, 68 /** IP traffic should be available. */ 69 CONNECTED, 70 /** IP traffic is suspended */ 71 SUSPENDED, 72 /** Currently tearing down data connection. */ 73 DISCONNECTING, 74 /** IP traffic not available. */ 75 DISCONNECTED, 76 /** Attempt to connect failed. */ 77 FAILED 78 } 79 80 /** 81 * This is the map described in the Javadoc comment above. The positions 82 * of the elements of the array must correspond to the ordinal values 83 * of <code>DetailedState</code>. 84 */ 85 private static final EnumMap<DetailedState, State> stateMap = 86 new EnumMap<DetailedState, State>(DetailedState.class); 87 88 static { 89 stateMap.put(DetailedState.IDLE, State.DISCONNECTED); 90 stateMap.put(DetailedState.SCANNING, State.DISCONNECTED); 91 stateMap.put(DetailedState.CONNECTING, State.CONNECTING); 92 stateMap.put(DetailedState.AUTHENTICATING, State.CONNECTING); 93 stateMap.put(DetailedState.OBTAINING_IPADDR, State.CONNECTING); 94 stateMap.put(DetailedState.CONNECTED, State.CONNECTED); 95 stateMap.put(DetailedState.SUSPENDED, State.SUSPENDED); 96 stateMap.put(DetailedState.DISCONNECTING, State.DISCONNECTING); 97 stateMap.put(DetailedState.DISCONNECTED, State.DISCONNECTED); 98 stateMap.put(DetailedState.FAILED, State.DISCONNECTED); 99 } 100 101 private int mNetworkType; 102 private int mSubtype; 103 private String mTypeName; 104 private String mSubtypeName; 105 private State mState; 106 private DetailedState mDetailedState; 107 private String mReason; 108 private String mExtraInfo; 109 private boolean mIsFailover; 110 private boolean mIsRoaming; 111 /** 112 * Indicates whether network connectivity is possible: 113 */ 114 private boolean mIsAvailable; 115 116 /** 117 * @param type network type 118 * @deprecated 119 * @hide because this constructor was only meant for internal use (and 120 * has now been superseded by the package-private constructor below). 121 */ 122 public NetworkInfo(int type) {} 123 124 /** 125 * @hide 126 */ 127 public NetworkInfo(int type, int subtype, String typeName, String subtypeName) { 128 if (!ConnectivityManager.isNetworkTypeValid(type)) { 129 throw new IllegalArgumentException("Invalid network type: " + type); 130 } 131 mNetworkType = type; 132 mSubtype = subtype; 133 mTypeName = typeName; 134 mSubtypeName = subtypeName; 135 setDetailedState(DetailedState.IDLE, null, null); 136 mState = State.UNKNOWN; 137 mIsAvailable = false; // until we're told otherwise, assume unavailable 138 mIsRoaming = false; 139 } 140 141 /** 142 * Reports the type of network (currently mobile or Wi-Fi) to which the 143 * info in this object pertains. 144 * @return the network type 145 */ 146 public int getType() { 147 return mNetworkType; 148 } 149 150 /** 151 * Return a network-type-specific integer describing the subtype 152 * of the network. 153 * @return the network subtype 154 */ 155 public int getSubtype() { 156 return mSubtype; 157 } 158 159 void setSubtype(int subtype, String subtypeName) { 160 mSubtype = subtype; 161 mSubtypeName = subtypeName; 162 } 163 164 /** 165 * Return a human-readable name describe the type of the network, 166 * for example "WIFI" or "MOBILE". 167 * @return the name of the network type 168 */ 169 public String getTypeName() { 170 return mTypeName; 171 } 172 173 /** 174 * Return a human-readable name describing the subtype of the network. 175 * @return the name of the network subtype 176 */ 177 public String getSubtypeName() { 178 return mSubtypeName; 179 } 180 181 /** 182 * Indicates whether network connectivity exists or is in the process 183 * of being established. This is good for applications that need to 184 * do anything related to the network other than read or write data. 185 * For the latter, call {@link #isConnected()} instead, which guarantees 186 * that the network is fully usable. 187 * @return {@code true} if network connectivity exists or is in the process 188 * of being established, {@code false} otherwise. 189 */ 190 public boolean isConnectedOrConnecting() { 191 return mState == State.CONNECTED || mState == State.CONNECTING; 192 } 193 194 /** 195 * Indicates whether network connectivity exists and it is possible to establish 196 * connections and pass data. 197 * @return {@code true} if network connectivity exists, {@code false} otherwise. 198 */ 199 public boolean isConnected() { 200 return mState == State.CONNECTED; 201 } 202 203 /** 204 * Indicates whether network connectivity is possible. A network is unavailable 205 * when a persistent or semi-persistent condition prevents the possibility 206 * of connecting to that network. Examples include 207 * <ul> 208 * <li>The device is out of the coverage area for any network of this type.</li> 209 * <li>The device is on a network other than the home network (i.e., roaming), and 210 * data roaming has been disabled.</li> 211 * <li>The device's radio is turned off, e.g., because airplane mode is enabled.</li> 212 * </ul> 213 * @return {@code true} if the network is available, {@code false} otherwise 214 */ 215 public boolean isAvailable() { 216 return mIsAvailable; 217 } 218 219 /** 220 * Sets if the network is available, ie, if the connectivity is possible. 221 * @param isAvailable the new availability value. 222 * 223 * @hide 224 */ 225 public void setIsAvailable(boolean isAvailable) { 226 mIsAvailable = isAvailable; 227 } 228 229 /** 230 * Indicates whether the current attempt to connect to the network 231 * resulted from the ConnectivityManager trying to fail over to this 232 * network following a disconnect from another network. 233 * @return {@code true} if this is a failover attempt, {@code false} 234 * otherwise. 235 */ 236 public boolean isFailover() { 237 return mIsFailover; 238 } 239 240 /** 241 * Set the failover boolean. 242 * @param isFailover {@code true} to mark the current connection attempt 243 * as a failover. 244 * @hide 245 */ 246 public void setFailover(boolean isFailover) { 247 mIsFailover = isFailover; 248 } 249 250 /** 251 * Indicates whether the device is currently roaming on this network. 252 * When {@code true}, it suggests that use of data on this network 253 * may incur extra costs. 254 * @return {@code true} if roaming is in effect, {@code false} otherwise. 255 */ 256 public boolean isRoaming() { 257 return mIsRoaming; 258 } 259 260 void setRoaming(boolean isRoaming) { 261 mIsRoaming = isRoaming; 262 } 263 264 /** 265 * Reports the current coarse-grained state of the network. 266 * @return the coarse-grained state 267 */ 268 public State getState() { 269 return mState; 270 } 271 272 /** 273 * Reports the current fine-grained state of the network. 274 * @return the fine-grained state 275 */ 276 public DetailedState getDetailedState() { 277 return mDetailedState; 278 } 279 280 /** 281 * Sets the fine-grained state of the network. 282 * @param detailedState the {@link DetailedState}. 283 * @param reason a {@code String} indicating the reason for the state change, 284 * if one was supplied. May be {@code null}. 285 * @param extraInfo an optional {@code String} providing addditional network state 286 * information passed up from the lower networking layers. 287 * @hide 288 */ 289 public void setDetailedState(DetailedState detailedState, String reason, String extraInfo) { 290 this.mDetailedState = detailedState; 291 this.mState = stateMap.get(detailedState); 292 this.mReason = reason; 293 this.mExtraInfo = extraInfo; 294 } 295 296 /** 297 * Report the reason an attempt to establish connectivity failed, 298 * if one is available. 299 * @return the reason for failure, or null if not available 300 */ 301 public String getReason() { 302 return mReason; 303 } 304 305 /** 306 * Report the extra information about the network state, if any was 307 * provided by the lower networking layers., 308 * if one is available. 309 * @return the extra information, or null if not available 310 */ 311 public String getExtraInfo() { 312 return mExtraInfo; 313 } 314 315 @Override 316 public String toString() { 317 StringBuilder builder = new StringBuilder("NetworkInfo: "); 318 builder.append("type: ").append(getTypeName()).append("[").append(getSubtypeName()). 319 append("], state: ").append(mState).append("/").append(mDetailedState). 320 append(", reason: ").append(mReason == null ? "(unspecified)" : mReason). 321 append(", extra: ").append(mExtraInfo == null ? "(none)" : mExtraInfo). 322 append(", roaming: ").append(mIsRoaming). 323 append(", failover: ").append(mIsFailover). 324 append(", isAvailable: ").append(mIsAvailable); 325 return builder.toString(); 326 } 327 328 /** 329 * Implement the Parcelable interface 330 * @hide 331 */ 332 public int describeContents() { 333 return 0; 334 } 335 336 /** 337 * Implement the Parcelable interface. 338 * @hide 339 */ 340 public void writeToParcel(Parcel dest, int flags) { 341 dest.writeInt(mNetworkType); 342 dest.writeInt(mSubtype); 343 dest.writeString(mTypeName); 344 dest.writeString(mSubtypeName); 345 dest.writeString(mState.name()); 346 dest.writeString(mDetailedState.name()); 347 dest.writeInt(mIsFailover ? 1 : 0); 348 dest.writeInt(mIsAvailable ? 1 : 0); 349 dest.writeInt(mIsRoaming ? 1 : 0); 350 dest.writeString(mReason); 351 dest.writeString(mExtraInfo); 352 } 353 354 /** 355 * Implement the Parcelable interface. 356 * @hide 357 */ 358 public static final Creator<NetworkInfo> CREATOR = 359 new Creator<NetworkInfo>() { 360 public NetworkInfo createFromParcel(Parcel in) { 361 int netType = in.readInt(); 362 int subtype = in.readInt(); 363 String typeName = in.readString(); 364 String subtypeName = in.readString(); 365 NetworkInfo netInfo = new NetworkInfo(netType, subtype, typeName, subtypeName); 366 netInfo.mState = State.valueOf(in.readString()); 367 netInfo.mDetailedState = DetailedState.valueOf(in.readString()); 368 netInfo.mIsFailover = in.readInt() != 0; 369 netInfo.mIsAvailable = in.readInt() != 0; 370 netInfo.mIsRoaming = in.readInt() != 0; 371 netInfo.mReason = in.readString(); 372 netInfo.mExtraInfo = in.readString(); 373 return netInfo; 374 } 375 376 public NetworkInfo[] newArray(int size) { 377 return new NetworkInfo[size]; 378 } 379 }; 380} 381