LineageOS/android_packages_modules_Connectivity
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update the docs for NetworkCapabilities

Browse Source 
Preparing for ConnectivityService API update

Change-Id: I397e375b9254d4271183cf34c4a689deea1e198e
This commit is contained in:
Robert Greenwalt
2014-05-18 15:24:21 -07:00
parent 1aacd72db2
commit 05d3bc2fd5
1 changed files with 201 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

220
core/java/android/net/NetworkCapabilities.java
View File

@@ -30,13 +30,31 @@ import java.util.Map.Entry;
import java.util.Set;
/**
* A class representing the capabilities of a network
* @hide
* This class represents the capabilities of a network. This is used both to specify
* needs to {@link ConnectivityManager} and when inspecting a network.
*
* Note that this replaces the old {@link ConnectivityManager#TYPE_MOBILE} method
* of network selection. Rather than indicate a need for Wi-Fi because an application
* needs high bandwidth and risk obselence when a new, fast network appears (like LTE),
* the application should specify it needs high bandwidth. Similarly if an application
* needs an unmetered network for a bulk transfer it can specify that rather than assuming
* all cellular based connections are metered and all Wi-Fi based connections are not.
*/
public final class NetworkCapabilities implements Parcelable {
private static final String TAG = "NetworkCapabilities";
private static final boolean DBG = false;
public NetworkCapabilities() {
}
public NetworkCapabilities(NetworkCapabilities nc) {
if (nc != null) {
mNetworkCapabilities = nc.mNetworkCapabilities;
mTransportTypes = nc.mTransportTypes;
mLinkUpBandwidthKbps = nc.mLinkUpBandwidthKbps;
mLinkDownBandwidthKbps = nc.mLinkDownBandwidthKbps;
}
}
/**
* Represents the network's capabilities. If any are specified they will be satisfied
@@ -45,28 +63,99 @@ public final class NetworkCapabilities implements Parcelable {
private long mNetworkCapabilities = (1 << NET_CAPABILITY_NOT_RESTRICTED);
/**
* Values for NetworkCapabilities. Roughly matches/extends deprecated
* ConnectivityManager TYPE_*
* Indicates this is a network that has the ability to reach the
* carrier's MMSC for sending and receiving MMS messages.
*/
public static final int NET_CAPABILITY_MMS = 0;
/**
* Indicates this is a network that has the ability to reach the carrier's
* SUPL server, used to retrieve GPS information.
*/
public static final int NET_CAPABILITY_SUPL = 1;
/**
* Indicates this is a network that has the ability to reach the carrier's
* DUN or tethering gateway.
*/
public static final int NET_CAPABILITY_DUN = 2;
/**
* Indicates this is a network that has the ability to reach the carrier's
* FOTA portal, used for over the air updates.
*/
public static final int NET_CAPABILITY_FOTA = 3;
/**
* Indicates this is a network that has the ability to reach the carrier's
* IMS servers, used for network registration and signaling.
*/
public static final int NET_CAPABILITY_IMS = 4;
/**
* Indicates this is a network that has the ability to reach the carrier's
* CBS servers, used for carrier specific services.
*/
public static final int NET_CAPABILITY_CBS = 5;
/**
* Indicates this is a network that has the ability to reach a Wi-Fi direct
* peer.
*/
public static final int NET_CAPABILITY_WIFI_P2P = 6;
/**
* Indicates this is a network that has the ability to reach a carrier's
* Initial Attach servers.
*/
public static final int NET_CAPABILITY_IA = 7;
/**
* Indicates this is a network that has the ability to reach a carrier's
* RCS servers, used for Rich Communication Services.
*/
public static final int NET_CAPABILITY_RCS = 8;
/**
* Indicates this is a network that has the ability to reach a carrier's
* XCAP servers, used for configuration and control.
*/
public static final int NET_CAPABILITY_XCAP = 9;
/**
* Indicates this is a network that has the ability to reach a carrier's
* Emergency IMS servers, used for network signaling during emergency calls.
*/
public static final int NET_CAPABILITY_EIMS = 10;
/**
* Indicates that this network is unmetered.
*/
public static final int NET_CAPABILITY_NOT_METERED = 11;
/**
* Indicates that this network should be able to reach the internet.
*/
public static final int NET_CAPABILITY_INTERNET = 12;
/** Set by default */
/**
* Indicates that this network is available for general use. If this is not set
* applications should not attempt to communicate on this network. Note that this
* is simply informative and not enforcement - enforcement is handled via other means.
* Set by default.
*/
public static final int NET_CAPABILITY_NOT_RESTRICTED = 13;
private static final int MIN_NET_CAPABILITY = NET_CAPABILITY_MMS;
private static final int MAX_NET_CAPABILITY = NET_CAPABILITY_NOT_RESTRICTED;
/**
* Adds the given capability to this {@code NetworkCapability} instance.
* Multiple capabilities may be applied sequentially. Note that when searching
* for a network to satisfy a request, all capabilities requested must be satisfied.
*
* @param networkCapability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be added.
*/
public void addNetworkCapability(int networkCapability) {
if (networkCapability < MIN_NET_CAPABILITY ||
networkCapability > MAX_NET_CAPABILITY) {
@@ -74,6 +163,12 @@ public final class NetworkCapabilities implements Parcelable {
}
mNetworkCapabilities |= 1 << networkCapability;
}
/**
* Removes (if found) the given capability from this {@code NetworkCapability} instance.
*
* @param networkCapability the {@code NetworkCapabilities.NET_CAPABILTIY_*} to be removed.
*/
public void removeNetworkCapability(int networkCapability) {
if (networkCapability < MIN_NET_CAPABILITY ||
networkCapability > MAX_NET_CAPABILITY) {
@@ -81,9 +176,23 @@ public final class NetworkCapabilities implements Parcelable {
}
mNetworkCapabilities &= ~(1 << networkCapability);
}
/**
* Gets all the capabilities set on this {@code NetworkCapability} instance.
*
* @return a {@link Collection} of {@code NetworkCapabilities.NET_CAPABILITY_*} values
* for this instance.
*/
public Collection<Integer> getNetworkCapabilities() {
return enumerateBits(mNetworkCapabilities);
}
/**
* Tests for the presence of a capabilitity on this instance.
*
* @param networkCapability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be tested for.
* @return {@code true} if set on this instance.
*/
public boolean hasCapability(int networkCapability) {
if (networkCapability < MIN_NET_CAPABILITY ||
networkCapability > MAX_NET_CAPABILITY) {
@@ -124,31 +233,74 @@ public final class NetworkCapabilities implements Parcelable {
private long mTransportTypes;
/**
* Values for TransportType
* Indicates this network uses a Cellular transport.
*/
public static final int TRANSPORT_CELLULAR = 0;
/**
* Indicates this network uses a Wi-Fi transport.
*/
public static final int TRANSPORT_WIFI = 1;
/**
* Indicates this network uses a Bluetooth transport.
*/
public static final int TRANSPORT_BLUETOOTH = 2;
/**
* Indicates this network uses an Ethernet transport.
*/
public static final int TRANSPORT_ETHERNET = 3;
private static final int MIN_TRANSPORT = TRANSPORT_CELLULAR;
private static final int MAX_TRANSPORT = TRANSPORT_ETHERNET;
/**
* Adds the given transport type to this {@code NetworkCapability} instance.
* Multiple transports may be applied sequentially. Note that when searching
* for a network to satisfy a request, any listed in the request will satisfy the request.
* For example {@code TRANSPORT_WIFI} and {@code TRANSPORT_ETHERNET} added to a
* {@code NetworkCapabilities} would cause either a Wi-Fi network or an Ethernet network
* to be selected. This is logically different than
* {@code NetworkCapabilities.NET_CAPABILITY_*} listed above.
*
* @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be added.
*/
public void addTransportType(int transportType) {
if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) {
throw new IllegalArgumentException("TransportType out of range");
}
mTransportTypes |= 1 << transportType;
}
/**
* Removes (if found) the given transport from this {@code NetworkCapability} instance.
*
* @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be removed.
*/
public void removeTransportType(int transportType) {
if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) {
throw new IllegalArgumentException("TransportType out of range");
}
mTransportTypes &= ~(1 << transportType);
}
/**
* Gets all the transports set on this {@code NetworkCapability} instance.
*
* @return a {@link Collection} of {@code NetworkCapabilities.TRANSPORT_*} values
* for this instance.
*/
public Collection<Integer> getTransportTypes() {
return enumerateBits(mTransportTypes);
}
/**
* Tests for the presence of a transport on this instance.
*
* @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be tested for.
* @return {@code true} if set on this instance.
*/
public boolean hasTransport(int transportType) {
if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) {
return false;
@@ -175,15 +327,58 @@ public final class NetworkCapabilities implements Parcelable {
private int mLinkUpBandwidthKbps;
private int mLinkDownBandwidthKbps;
/**
* Sets the upstream bandwidth for this network in Kbps. This always only refers to
* the estimated first hop transport bandwidth.
* <p>
* Note that when used to request a network, this specifies the minimum acceptable.
* When received as the state of an existing network this specifies the typical
* first hop bandwidth expected. This is never measured, but rather is inferred
* from technology type and other link parameters. It could be used to differentiate
* between very slow 1xRTT cellular links and other faster networks or even between
* 802.11b vs 802.11AC wifi technologies. It should not be used to differentiate between
* fast backhauls and slow backhauls.
*
* @param upKbps the estimated first hop upstream (device to network) bandwidth.
*/
public void setLinkUpstreamBandwidthKbps(int upKbps) {
mLinkUpBandwidthKbps = upKbps;
}
/**
* Retrieves the upstream bandwidth for this network in Kbps. This always only refers to
* the estimated first hop transport bandwidth.
*
* @return The estimated first hop upstream (device to network) bandwidth.
*/
public int getLinkUpstreamBandwidthKbps() {
return mLinkUpBandwidthKbps;
}
/**
* Sets the downstream bandwidth for this network in Kbps. This always only refers to
* the estimated first hop transport bandwidth.
* <p>
* Note that when used to request a network, this specifies the minimum acceptable.
* When received as the state of an existing network this specifies the typical
* first hop bandwidth expected. This is never measured, but rather is inferred
* from technology type and other link parameters. It could be used to differentiate
* between very slow 1xRTT cellular links and other faster networks or even between
* 802.11b vs 802.11AC wifi technologies. It should not be used to differentiate between
* fast backhauls and slow backhauls.
*
* @param downKbps the estimated first hop downstream (network to device) bandwidth.
*/
public void setLinkDownstreamBandwidthKbps(int downKbps) {
mLinkDownBandwidthKbps = downKbps;
}
/**
* Retrieves the downstream bandwidth for this network in Kbps. This always only refers to
* the estimated first hop transport bandwidth.
*
* @return The estimated first hop downstream (network to device) bandwidth.
*/
public int getLinkDownstreamBandwidthKbps() {
return mLinkDownBandwidthKbps;
}
@@ -243,19 +438,6 @@ public final class NetworkCapabilities implements Parcelable {
(mLinkDownBandwidthKbps * 13));
}
public NetworkCapabilities() {
}
public NetworkCapabilities(NetworkCapabilities nc) {
if (nc != null) {
mNetworkCapabilities = nc.mNetworkCapabilities;
mTransportTypes = nc.mTransportTypes;
mLinkUpBandwidthKbps = nc.mLinkUpBandwidthKbps;
mLinkDownBandwidthKbps = nc.mLinkDownBandwidthKbps;
}
}
// Parcelable
public int describeContents() {
return 0;
}