FileDocCategorySizeDatePackage
NetworkCapabilities.javaAPI DocAndroid 5.1 API25187Thu Mar 12 22:22:10 GMT 2015android.net

NetworkCapabilities

public final class NetworkCapabilities extends Object implements android.os.Parcelable
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 obsolescence 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.

Fields Summary
private long
mNetworkCapabilities
Represents the network's capabilities. If any are specified they will be satisfied by any Network that matches all of them.
public static final int
NET_CAPABILITY_MMS
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_SUPL
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_DUN
Indicates this is a network that has the ability to reach the carrier's DUN or tethering gateway.
public static final int
NET_CAPABILITY_FOTA
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_IMS
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_CBS
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_WIFI_P2P
Indicates this is a network that has the ability to reach a Wi-Fi direct peer.
public static final int
NET_CAPABILITY_IA
Indicates this is a network that has the ability to reach a carrier's Initial Attach servers.
public static final int
NET_CAPABILITY_RCS
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_XCAP
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_EIMS
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_NOT_METERED
Indicates that this network is unmetered.
public static final int
NET_CAPABILITY_INTERNET
Indicates that this network should be able to reach the internet.
public static final int
NET_CAPABILITY_NOT_RESTRICTED
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_TRUSTED
Indicates that the user has indicated implicit trust of this network. This generally means it's a sim-selected carrier, a plugged in ethernet, a paired BT device or a wifi the user asked to connect to. Untrusted networks are probably limited to unknown wifi AP. Set by default.
public static final int
NET_CAPABILITY_NOT_VPN
public static final int
NET_CAPABILITY_VALIDATED
Indicates that connectivity on this network was successfully validated. For example, for a network with NET_CAPABILITY_INTERNET, it means that Internet connectivity was successfully detected.
private static final int
MIN_NET_CAPABILITY
private static final int
MAX_NET_CAPABILITY
private long
mTransportTypes
Representing the transport type. Apps should generally not care about transport. A request for a fast internet connection could be satisfied by a number of different transports. If any are specified here it will be satisfied a Network that matches any of them. If a caller doesn't care about the transport it should not specify any.
public static final int
TRANSPORT_CELLULAR
Indicates this network uses a Cellular transport.
public static final int
TRANSPORT_WIFI
Indicates this network uses a Wi-Fi transport.
public static final int
TRANSPORT_BLUETOOTH
Indicates this network uses a Bluetooth transport.
public static final int
TRANSPORT_ETHERNET
Indicates this network uses an Ethernet transport.
public static final int
TRANSPORT_VPN
Indicates this network uses a VPN transport.
private static final int
MIN_TRANSPORT
private static final int
MAX_TRANSPORT
private int
mLinkUpBandwidthKbps
Passive link bandwidth. This is a rough guide of the expected peak bandwidth for the first hop on the given transport. It is not measured, but may take into account link parameters (Radio technology, allocated channels, etc).
private int
mLinkDownBandwidthKbps
private String
mNetworkSpecifier
public static final Creator
CREATOR
Constructors Summary
public NetworkCapabilities()

hide
public NetworkCapabilities(NetworkCapabilities nc)

        if (nc != null) {
            mNetworkCapabilities = nc.mNetworkCapabilities;
            mTransportTypes = nc.mTransportTypes;
            mLinkUpBandwidthKbps = nc.mLinkUpBandwidthKbps;
            mLinkDownBandwidthKbps = nc.mLinkDownBandwidthKbps;
            mNetworkSpecifier = nc.mNetworkSpecifier;
        }
Methods Summary
public android.net.NetworkCapabilitiesaddCapability(int capability)
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
capability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be added.
return
This NetworkCapability to facilitate chaining.
hide


                                                         
        
        if (capability < MIN_NET_CAPABILITY || capability > MAX_NET_CAPABILITY) {
            throw new IllegalArgumentException("NetworkCapability out of range");
        }
        mNetworkCapabilities |= 1 << capability;
        return this;
public android.net.NetworkCapabilitiesaddTransportType(int transportType)
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.
return
This NetworkCapability to facilitate chaining.
hide


                                                                                                
        
        if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) {
            throw new IllegalArgumentException("TransportType out of range");
        }
        mTransportTypes |= 1 << transportType;
        setNetworkSpecifier(mNetworkSpecifier); // used for exception checking
        return this;
public voidcombineCapabilities(android.net.NetworkCapabilities nc)
Combine a set of Capabilities to this one. Useful for coming up with the complete set {@hide}

        combineNetCapabilities(nc);
        combineTransportTypes(nc);
        combineLinkBandwidths(nc);
        combineSpecifiers(nc);
private voidcombineLinkBandwidths(android.net.NetworkCapabilities nc)

        this.mLinkUpBandwidthKbps =
                Math.max(this.mLinkUpBandwidthKbps, nc.mLinkUpBandwidthKbps);
        this.mLinkDownBandwidthKbps =
                Math.max(this.mLinkDownBandwidthKbps, nc.mLinkDownBandwidthKbps);
private voidcombineNetCapabilities(android.net.NetworkCapabilities nc)

        this.mNetworkCapabilities |= nc.mNetworkCapabilities;
private voidcombineSpecifiers(android.net.NetworkCapabilities nc)

        String otherSpecifier = nc.getNetworkSpecifier();
        if (TextUtils.isEmpty(otherSpecifier)) return;
        if (TextUtils.isEmpty(mNetworkSpecifier) == false) {
            throw new IllegalStateException("Can't combine two networkSpecifiers");
        }
        setNetworkSpecifier(otherSpecifier);
private voidcombineTransportTypes(android.net.NetworkCapabilities nc)

        this.mTransportTypes |= nc.mTransportTypes;
public intdescribeContents()

        return 0;
private int[]enumerateBits(long val)

        int size = Long.bitCount(val);
        int[] result = new int[size];
        int index = 0;
        int resource = 0;
        while (val > 0) {
            if ((val & 1) == 1) result[index++] = resource;
            val = val >> 1;
            resource++;
        }
        return result;
public booleanequals(java.lang.Object obj)

        if (obj == null || (obj instanceof NetworkCapabilities == false)) return false;
        NetworkCapabilities that = (NetworkCapabilities)obj;
        return (equalsNetCapabilities(that) &&
                equalsTransportTypes(that) &&
                equalsLinkBandwidths(that) &&
                equalsSpecifier(that));
private booleanequalsLinkBandwidths(android.net.NetworkCapabilities nc)

        return (this.mLinkUpBandwidthKbps == nc.mLinkUpBandwidthKbps &&
                this.mLinkDownBandwidthKbps == nc.mLinkDownBandwidthKbps);
public booleanequalsNetCapabilities(android.net.NetworkCapabilities nc)

hide

        return (nc.mNetworkCapabilities == this.mNetworkCapabilities);
private booleanequalsSpecifier(android.net.NetworkCapabilities nc)

        if (TextUtils.isEmpty(mNetworkSpecifier)) {
            return TextUtils.isEmpty(nc.mNetworkSpecifier);
        } else {
            return mNetworkSpecifier.equals(nc.mNetworkSpecifier);
        }
public booleanequalsTransportTypes(android.net.NetworkCapabilities nc)

hide

        return (nc.mTransportTypes == this.mTransportTypes);
public int[]getCapabilities()
Gets all the capabilities set on this {@code NetworkCapability} instance.

return
an array of {@code NetworkCapabilities.NET_CAPABILITY_*} values for this instance.
hide

        return enumerateBits(mNetworkCapabilities);
public intgetLinkDownstreamBandwidthKbps()
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.

        return mLinkDownBandwidthKbps;
public intgetLinkUpstreamBandwidthKbps()
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.

        return mLinkUpBandwidthKbps;
public java.lang.StringgetNetworkSpecifier()
Gets the optional bearer specific network specifier.

return
The optional {@code String} specifying the bearer specific network specifier. See {@link #setNetworkSpecifier}.
hide

        return mNetworkSpecifier;
public int[]getTransportTypes()
Gets all the transports set on this {@code NetworkCapability} instance.

return
an array of {@code NetworkCapabilities.TRANSPORT_*} values for this instance.
hide

        return enumerateBits(mTransportTypes);
public booleanhasCapability(int capability)
Tests for the presence of a capabilitity on this instance.

param
capability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be tested for.
return
{@code true} if set on this instance.

        if (capability < MIN_NET_CAPABILITY || capability > MAX_NET_CAPABILITY) {
            return false;
        }
        return ((mNetworkCapabilities & (1 << capability)) != 0);
public booleanhasTransport(int transportType)
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.

        if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) {
            return false;
        }
        return ((mTransportTypes & (1 << transportType)) != 0);
public inthashCode()

        return ((int)(mNetworkCapabilities & 0xFFFFFFFF) +
                ((int)(mNetworkCapabilities >> 32) * 3) +
                ((int)(mTransportTypes & 0xFFFFFFFF) * 5) +
                ((int)(mTransportTypes >> 32) * 7) +
                (mLinkUpBandwidthKbps * 11) +
                (mLinkDownBandwidthKbps * 13) +
                (TextUtils.isEmpty(mNetworkSpecifier) ? 0 : mNetworkSpecifier.hashCode() * 17));
public android.net.NetworkCapabilitiesremoveCapability(int capability)
Removes (if found) the given capability from this {@code NetworkCapability} instance.

param
capability the {@code NetworkCapabilities.NET_CAPABILTIY_*} to be removed.
return
This NetworkCapability to facilitate chaining.
hide

        if (capability < MIN_NET_CAPABILITY || capability > MAX_NET_CAPABILITY) {
            throw new IllegalArgumentException("NetworkCapability out of range");
        }
        mNetworkCapabilities &= ~(1 << capability);
        return this;
public android.net.NetworkCapabilitiesremoveTransportType(int transportType)
Removes (if found) the given transport from this {@code NetworkCapability} instance.

param
transportType the {@code NetworkCapabilities.TRANSPORT_*} to be removed.
return
This NetworkCapability to facilitate chaining.
hide

        if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) {
            throw new IllegalArgumentException("TransportType out of range");
        }
        mTransportTypes &= ~(1 << transportType);
        setNetworkSpecifier(mNetworkSpecifier); // used for exception checking
        return this;
private booleansatisfiedByLinkBandwidths(android.net.NetworkCapabilities nc)

        return !(this.mLinkUpBandwidthKbps > nc.mLinkUpBandwidthKbps ||
                this.mLinkDownBandwidthKbps > nc.mLinkDownBandwidthKbps);
private booleansatisfiedByNetCapabilities(android.net.NetworkCapabilities nc)

        return ((nc.mNetworkCapabilities & this.mNetworkCapabilities) == this.mNetworkCapabilities);
public booleansatisfiedByNetworkCapabilities(android.net.NetworkCapabilities nc)
Check if our requirements are satisfied by the given Capabilities. {@hide}

        return (nc != null &&
                satisfiedByNetCapabilities(nc) &&
                satisfiedByTransportTypes(nc) &&
                satisfiedByLinkBandwidths(nc) &&
                satisfiedBySpecifier(nc));
private booleansatisfiedBySpecifier(android.net.NetworkCapabilities nc)

        return (TextUtils.isEmpty(mNetworkSpecifier) ||
                mNetworkSpecifier.equals(nc.mNetworkSpecifier));
private booleansatisfiedByTransportTypes(android.net.NetworkCapabilities nc)

        return ((this.mTransportTypes == 0) ||
                ((this.mTransportTypes & nc.mTransportTypes) != 0));
public voidsetLinkDownstreamBandwidthKbps(int downKbps)
Sets the downstream bandwidth for this network in Kbps. This always only refers to the estimated first hop transport bandwidth.

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.
hide

        mLinkDownBandwidthKbps = downKbps;
public voidsetLinkUpstreamBandwidthKbps(int upKbps)
Sets the upstream bandwidth for this network in Kbps. This always only refers to the estimated first hop transport bandwidth.

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.
hide

        mLinkUpBandwidthKbps = upKbps;
public voidsetNetworkSpecifier(java.lang.String networkSpecifier)
Sets the optional bearer specific network specifier. This has no meaning if a single transport is also not specified, so calling this without a single transport set will generate an exception, as will subsequently adding or removing transports after this is set.

The interpretation of this {@code String} is bearer specific and bearers that use it should document their particulars. For example, Bluetooth may use some sort of device id while WiFi could used SSID and/or BSSID. Cellular may use carrier SPN (name) or Subscription ID.

param
networkSpecifier An {@code String} of opaque format used to specify the bearer specific network specifier where the bearer has a choice of networks.
hide

        if (TextUtils.isEmpty(networkSpecifier) == false && Long.bitCount(mTransportTypes) != 1) {
            throw new IllegalStateException("Must have a single transport specified to use " +
                    "setNetworkSpecifier");
        }
        mNetworkSpecifier = networkSpecifier;
public java.lang.StringtoString()


    
       
        int[] types = getTransportTypes();
        String transports = (types.length > 0 ? " Transports: " : "");
        for (int i = 0; i < types.length;) {
            switch (types[i]) {
                case TRANSPORT_CELLULAR:    transports += "CELLULAR"; break;
                case TRANSPORT_WIFI:        transports += "WIFI"; break;
                case TRANSPORT_BLUETOOTH:   transports += "BLUETOOTH"; break;
                case TRANSPORT_ETHERNET:    transports += "ETHERNET"; break;
                case TRANSPORT_VPN:         transports += "VPN"; break;
            }
            if (++i < types.length) transports += "|";
        }

        types = getCapabilities();
        String capabilities = (types.length > 0 ? " Capabilities: " : "");
        for (int i = 0; i < types.length; ) {
            switch (types[i]) {
                case NET_CAPABILITY_MMS:            capabilities += "MMS"; break;
                case NET_CAPABILITY_SUPL:           capabilities += "SUPL"; break;
                case NET_CAPABILITY_DUN:            capabilities += "DUN"; break;
                case NET_CAPABILITY_FOTA:           capabilities += "FOTA"; break;
                case NET_CAPABILITY_IMS:            capabilities += "IMS"; break;
                case NET_CAPABILITY_CBS:            capabilities += "CBS"; break;
                case NET_CAPABILITY_WIFI_P2P:       capabilities += "WIFI_P2P"; break;
                case NET_CAPABILITY_IA:             capabilities += "IA"; break;
                case NET_CAPABILITY_RCS:            capabilities += "RCS"; break;
                case NET_CAPABILITY_XCAP:           capabilities += "XCAP"; break;
                case NET_CAPABILITY_EIMS:           capabilities += "EIMS"; break;
                case NET_CAPABILITY_NOT_METERED:    capabilities += "NOT_METERED"; break;
                case NET_CAPABILITY_INTERNET:       capabilities += "INTERNET"; break;
                case NET_CAPABILITY_NOT_RESTRICTED: capabilities += "NOT_RESTRICTED"; break;
                case NET_CAPABILITY_TRUSTED:        capabilities += "TRUSTED"; break;
                case NET_CAPABILITY_NOT_VPN:        capabilities += "NOT_VPN"; break;
            }
            if (++i < types.length) capabilities += "&";
        }

        String upBand = ((mLinkUpBandwidthKbps > 0) ? " LinkUpBandwidth>=" +
                mLinkUpBandwidthKbps + "Kbps" : "");
        String dnBand = ((mLinkDownBandwidthKbps > 0) ? " LinkDnBandwidth>=" +
                mLinkDownBandwidthKbps + "Kbps" : "");

        String specifier = (mNetworkSpecifier == null ?
                "" : " Specifier: <" + mNetworkSpecifier + ">");

        return "[" + transports + capabilities + upBand + dnBand + specifier + "]";
public voidwriteToParcel(android.os.Parcel dest, int flags)

        dest.writeLong(mNetworkCapabilities);
        dest.writeLong(mTransportTypes);
        dest.writeInt(mLinkUpBandwidthKbps);
        dest.writeInt(mLinkDownBandwidthKbps);
        dest.writeString(mNetworkSpecifier);