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