NetworkInfo.java revision f013e1afd1e68af5e3b868c26a653bbfb39538f8
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 * TODO This is going away as soon as API council review happens. 118 * @param type network type 119 */ 120 public NetworkInfo(int type) {} 121 122 NetworkInfo(int type, int subtype, String typeName, String subtypeName) { 123 if (!ConnectivityManager.isNetworkTypeValid(type)) { 124 throw new IllegalArgumentException("Invalid network type: " + type); 125 } 126 mNetworkType = type; 127 mSubtype = subtype; 128 mTypeName = typeName; 129 mSubtypeName = subtypeName; 130 setDetailedState(DetailedState.IDLE, null, null); 131 mState = State.UNKNOWN; 132 mIsAvailable = true; 133 mIsRoaming = false; 134 } 135 136 /** 137 * Reports the type of network (currently mobile or Wi-Fi) to which the 138 * info in this object pertains. 139 * @return the network type 140 */ 141 public int getType() { 142 return mNetworkType; 143 } 144 145 /** 146 * Return a network-type-specific integer describing the subtype 147 * of the network. 148 * @return the network subtype 149 * 150 * @hide pending API council review 151 */ 152 public int getSubtype() { 153 return mSubtype; 154 } 155 156 void setSubtype(int subtype, String subtypeName) { 157 mSubtype = subtype; 158 mSubtypeName = subtypeName; 159 } 160 161 /** 162 * Return a human-readable name describe the type of the network, 163 * for example "WIFI" or "MOBILE". 164 * @return the name of the network type 165 */ 166 public String getTypeName() { 167 return mTypeName; 168 } 169 170 /** 171 * Return a human-readable name describing the subtype of the network. 172 * @return the name of the network subtype 173 * 174 * @hide pending API council review 175 */ 176 public String getSubtypeName() { 177 return mSubtypeName; 178 } 179 180 /** 181 * Indicates whether network connectivity exists or is in the process 182 * of being established. This is good for applications that need to 183 * do anything related to the network other than read or write data. 184 * For the latter, call {@link #isConnected()} instead, which guarantees 185 * that the network is fully usable. 186 * @return {@code true} if network connectivity exists or is in the process 187 * of being established, {@code false} otherwise. 188 */ 189 public boolean isConnectedOrConnecting() { 190 return mState == State.CONNECTED || mState == State.CONNECTING; 191 } 192 193 /** 194 * Indicates whether network connectivity exists and it is possible to establish 195 * connections and pass data. 196 * @return {@code true} if network connectivity exists, {@code false} otherwise. 197 */ 198 public boolean isConnected() { 199 return mState == State.CONNECTED; 200 } 201 202 /** 203 * Indicates whether network connectivity is possible. A network is unavailable 204 * when a persistent or semi-persistent condition prevents the possibility 205 * of connecting to that network. Examples include 206 * <ul> 207 * <li>The device is out of the coverage area for any network of this type.</li> 208 * <li>The device is on a network other than the home network (i.e., roaming), and 209 * data roaming has been disabled.</li> 210 * <li>The device's radio is turned off, e.g., because airplane mode is enabled.</li> 211 * </ul> 212 * @return {@code true} if the network is available, {@code false} otherwise 213 */ 214 public boolean isAvailable() { 215 return mIsAvailable; 216 } 217 218 /** 219 * Sets if the network is available, ie, if the connectivity is possible. 220 * @param isAvailable the new availability value. 221 * 222 * @hide 223 */ 224 public void setIsAvailable(boolean isAvailable) { 225 mIsAvailable = isAvailable; 226 } 227 228 /** 229 * Indicates whether the current attempt to connect to the network 230 * resulted from the ConnectivityManager trying to fail over to this 231 * network following a disconnect from another network. 232 * @return {@code true} if this is a failover attempt, {@code false} 233 * otherwise. 234 */ 235 public boolean isFailover() { 236 return mIsFailover; 237 } 238 239 /** 240 * Set the failover boolean. 241 * @param isFailover {@code true} to mark the current connection attempt 242 * as a failover. 243 * @hide 244 */ 245 public void setFailover(boolean isFailover) { 246 mIsFailover = isFailover; 247 } 248 249 /** 250 * Indicates whether the device is currently roaming on this network. 251 * When {@code true}, it suggests that use of data on this network 252 * may incur extra costs. 253 * @return {@code true} if roaming is in effect, {@code false} otherwise. 254 * 255 * @hide pending API council 256 */ 257 public boolean isRoaming() { 258 return mIsRoaming; 259 } 260 261 void setRoaming(boolean isRoaming) { 262 mIsRoaming = isRoaming; 263 } 264 265 /** 266 * Reports the current coarse-grained state of the network. 267 * @return the coarse-grained state 268 */ 269 public State getState() { 270 return mState; 271 } 272 273 /** 274 * Reports the current fine-grained state of the network. 275 * @return the fine-grained state 276 */ 277 public DetailedState getDetailedState() { 278 return mDetailedState; 279 } 280 281 /** 282 * Sets the fine-grained state of the network. 283 * @param detailedState the {@link DetailedState}. 284 * @param reason a {@code String} indicating the reason for the state change, 285 * if one was supplied. May be {@code null}. 286 * @param extraInfo an optional {@code String} providing addditional network state 287 * information passed up from the lower networking layers. 288 */ 289 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