/*
|
* Copyright (C) 2014 The Android Open Source Project
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License.
|
*/
|
|
package android.net;
|
|
import android.annotation.IntDef;
|
import android.annotation.NonNull;
|
import android.annotation.Nullable;
|
import android.annotation.SystemApi;
|
import android.annotation.TestApi;
|
import android.annotation.UnsupportedAppUsage;
|
import android.net.ConnectivityManager.NetworkCallback;
|
import android.os.Build;
|
import android.os.Parcel;
|
import android.os.Parcelable;
|
import android.util.ArraySet;
|
import android.util.proto.ProtoOutputStream;
|
|
import com.android.internal.annotations.VisibleForTesting;
|
import com.android.internal.util.BitUtils;
|
import com.android.internal.util.Preconditions;
|
|
import java.lang.annotation.Retention;
|
import java.lang.annotation.RetentionPolicy;
|
import java.util.Objects;
|
import java.util.Set;
|
import java.util.StringJoiner;
|
|
/**
|
* Representation of the capabilities of an active network. Instances are
|
* typically obtained through
|
* {@link NetworkCallback#onCapabilitiesChanged(Network, NetworkCapabilities)}
|
* or {@link ConnectivityManager#getNetworkCapabilities(Network)}.
|
* <p>
|
* 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.
|
*/
|
public final class NetworkCapabilities implements Parcelable {
|
private static final String TAG = "NetworkCapabilities";
|
private static final int INVALID_UID = -1;
|
|
/**
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public NetworkCapabilities() {
|
clearAll();
|
mNetworkCapabilities = DEFAULT_CAPABILITIES;
|
}
|
|
public NetworkCapabilities(NetworkCapabilities nc) {
|
if (nc != null) {
|
set(nc);
|
}
|
}
|
|
/**
|
* Completely clears the contents of this object, removing even the capabilities that are set
|
* by default when the object is constructed.
|
* @hide
|
*/
|
public void clearAll() {
|
mNetworkCapabilities = mTransportTypes = mUnwantedNetworkCapabilities = 0;
|
mLinkUpBandwidthKbps = mLinkDownBandwidthKbps = LINK_BANDWIDTH_UNSPECIFIED;
|
mNetworkSpecifier = null;
|
mTransportInfo = null;
|
mSignalStrength = SIGNAL_STRENGTH_UNSPECIFIED;
|
mUids = null;
|
mEstablishingVpnAppUid = INVALID_UID;
|
mSSID = null;
|
}
|
|
/**
|
* Set all contents of this object to the contents of a NetworkCapabilities.
|
* @hide
|
*/
|
public void set(@NonNull NetworkCapabilities nc) {
|
mNetworkCapabilities = nc.mNetworkCapabilities;
|
mTransportTypes = nc.mTransportTypes;
|
mLinkUpBandwidthKbps = nc.mLinkUpBandwidthKbps;
|
mLinkDownBandwidthKbps = nc.mLinkDownBandwidthKbps;
|
mNetworkSpecifier = nc.mNetworkSpecifier;
|
mTransportInfo = nc.mTransportInfo;
|
mSignalStrength = nc.mSignalStrength;
|
setUids(nc.mUids); // Will make the defensive copy
|
mEstablishingVpnAppUid = nc.mEstablishingVpnAppUid;
|
mUnwantedNetworkCapabilities = nc.mUnwantedNetworkCapabilities;
|
mSSID = nc.mSSID;
|
}
|
|
/**
|
* Represents the network's capabilities. If any are specified they will be satisfied
|
* by any Network that matches all of them.
|
*/
|
@UnsupportedAppUsage
|
private long mNetworkCapabilities;
|
|
/**
|
* If any capabilities specified here they must not exist in the matching Network.
|
*/
|
private long mUnwantedNetworkCapabilities;
|
|
/** @hide */
|
@Retention(RetentionPolicy.SOURCE)
|
@IntDef(prefix = { "NET_CAPABILITY_" }, value = {
|
NET_CAPABILITY_MMS,
|
NET_CAPABILITY_SUPL,
|
NET_CAPABILITY_DUN,
|
NET_CAPABILITY_FOTA,
|
NET_CAPABILITY_IMS,
|
NET_CAPABILITY_CBS,
|
NET_CAPABILITY_WIFI_P2P,
|
NET_CAPABILITY_IA,
|
NET_CAPABILITY_RCS,
|
NET_CAPABILITY_XCAP,
|
NET_CAPABILITY_EIMS,
|
NET_CAPABILITY_NOT_METERED,
|
NET_CAPABILITY_INTERNET,
|
NET_CAPABILITY_NOT_RESTRICTED,
|
NET_CAPABILITY_TRUSTED,
|
NET_CAPABILITY_NOT_VPN,
|
NET_CAPABILITY_VALIDATED,
|
NET_CAPABILITY_CAPTIVE_PORTAL,
|
NET_CAPABILITY_NOT_ROAMING,
|
NET_CAPABILITY_FOREGROUND,
|
NET_CAPABILITY_NOT_CONGESTED,
|
NET_CAPABILITY_NOT_SUSPENDED,
|
NET_CAPABILITY_OEM_PAID,
|
NET_CAPABILITY_MCX,
|
NET_CAPABILITY_PARTIAL_CONNECTIVITY,
|
})
|
public @interface NetCapability { }
|
|
/**
|
* 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 or other services, 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;
|
|
/**
|
* 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;
|
|
/**
|
* 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_TRUSTED = 14;
|
|
/**
|
* Indicates that this network is not a VPN. This capability is set by default and should be
|
* explicitly cleared for VPN networks.
|
*/
|
public static final int NET_CAPABILITY_NOT_VPN = 15;
|
|
/**
|
* 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.
|
*/
|
public static final int NET_CAPABILITY_VALIDATED = 16;
|
|
/**
|
* Indicates that this network was found to have a captive portal in place last time it was
|
* probed.
|
*/
|
public static final int NET_CAPABILITY_CAPTIVE_PORTAL = 17;
|
|
/**
|
* Indicates that this network is not roaming.
|
*/
|
public static final int NET_CAPABILITY_NOT_ROAMING = 18;
|
|
/**
|
* Indicates that this network is available for use by apps, and not a network that is being
|
* kept up in the background to facilitate fast network switching.
|
*/
|
public static final int NET_CAPABILITY_FOREGROUND = 19;
|
|
/**
|
* Indicates that this network is not congested.
|
* <p>
|
* When a network is congested, applications should defer network traffic
|
* that can be done at a later time, such as uploading analytics.
|
*/
|
public static final int NET_CAPABILITY_NOT_CONGESTED = 20;
|
|
/**
|
* Indicates that this network is not currently suspended.
|
* <p>
|
* When a network is suspended, the network's IP addresses and any connections
|
* established on the network remain valid, but the network is temporarily unable
|
* to transfer data. This can happen, for example, if a cellular network experiences
|
* a temporary loss of signal, such as when driving through a tunnel, etc.
|
* A network with this capability is not suspended, so is expected to be able to
|
* transfer data.
|
*/
|
public static final int NET_CAPABILITY_NOT_SUSPENDED = 21;
|
|
/**
|
* Indicates that traffic that goes through this network is paid by oem. For example,
|
* this network can be used by system apps to upload telemetry data.
|
* @hide
|
*/
|
@SystemApi
|
public static final int NET_CAPABILITY_OEM_PAID = 22;
|
|
/**
|
* Indicates this is a network that has the ability to reach a carrier's Mission Critical
|
* servers.
|
*/
|
public static final int NET_CAPABILITY_MCX = 23;
|
|
/**
|
* Indicates that this network was tested to only provide partial connectivity.
|
* @hide
|
*/
|
@SystemApi
|
public static final int NET_CAPABILITY_PARTIAL_CONNECTIVITY = 24;
|
|
private static final int MIN_NET_CAPABILITY = NET_CAPABILITY_MMS;
|
private static final int MAX_NET_CAPABILITY = NET_CAPABILITY_PARTIAL_CONNECTIVITY;
|
|
/**
|
* Network capabilities that are expected to be mutable, i.e., can change while a particular
|
* network is connected.
|
*/
|
private static final long MUTABLE_CAPABILITIES =
|
// TRUSTED can change when user explicitly connects to an untrusted network in Settings.
|
// http://b/18206275
|
(1 << NET_CAPABILITY_TRUSTED)
|
| (1 << NET_CAPABILITY_VALIDATED)
|
| (1 << NET_CAPABILITY_CAPTIVE_PORTAL)
|
| (1 << NET_CAPABILITY_NOT_ROAMING)
|
| (1 << NET_CAPABILITY_FOREGROUND)
|
| (1 << NET_CAPABILITY_NOT_CONGESTED)
|
| (1 << NET_CAPABILITY_NOT_SUSPENDED)
|
| (1 << NET_CAPABILITY_PARTIAL_CONNECTIVITY);
|
|
/**
|
* Network capabilities that are not allowed in NetworkRequests. This exists because the
|
* NetworkFactory / NetworkAgent model does not deal well with the situation where a
|
* capability's presence cannot be known in advance. If such a capability is requested, then we
|
* can get into a cycle where the NetworkFactory endlessly churns out NetworkAgents that then
|
* get immediately torn down because they do not have the requested capability.
|
*/
|
private static final long NON_REQUESTABLE_CAPABILITIES =
|
MUTABLE_CAPABILITIES & ~(1 << NET_CAPABILITY_TRUSTED);
|
|
/**
|
* Capabilities that are set by default when the object is constructed.
|
*/
|
private static final long DEFAULT_CAPABILITIES =
|
(1 << NET_CAPABILITY_NOT_RESTRICTED) |
|
(1 << NET_CAPABILITY_TRUSTED) |
|
(1 << NET_CAPABILITY_NOT_VPN);
|
|
/**
|
* Capabilities that suggest that a network is restricted.
|
* {@see #maybeMarkCapabilitiesRestricted}, {@see #FORCE_RESTRICTED_CAPABILITIES}
|
*/
|
@VisibleForTesting
|
/* package */ static final long RESTRICTED_CAPABILITIES =
|
(1 << NET_CAPABILITY_CBS) |
|
(1 << NET_CAPABILITY_DUN) |
|
(1 << NET_CAPABILITY_EIMS) |
|
(1 << NET_CAPABILITY_FOTA) |
|
(1 << NET_CAPABILITY_IA) |
|
(1 << NET_CAPABILITY_IMS) |
|
(1 << NET_CAPABILITY_RCS) |
|
(1 << NET_CAPABILITY_XCAP) |
|
(1 << NET_CAPABILITY_MCX);
|
|
/**
|
* Capabilities that force network to be restricted.
|
* {@see #maybeMarkCapabilitiesRestricted}.
|
*/
|
private static final long FORCE_RESTRICTED_CAPABILITIES =
|
(1 << NET_CAPABILITY_OEM_PAID);
|
|
/**
|
* Capabilities that suggest that a network is unrestricted.
|
* {@see #maybeMarkCapabilitiesRestricted}.
|
*/
|
@VisibleForTesting
|
/* package */ static final long UNRESTRICTED_CAPABILITIES =
|
(1 << NET_CAPABILITY_INTERNET) |
|
(1 << NET_CAPABILITY_MMS) |
|
(1 << NET_CAPABILITY_SUPL) |
|
(1 << NET_CAPABILITY_WIFI_P2P);
|
|
/**
|
* Capabilities that are managed by ConnectivityService.
|
*/
|
private static final long CONNECTIVITY_MANAGED_CAPABILITIES =
|
(1 << NET_CAPABILITY_VALIDATED)
|
| (1 << NET_CAPABILITY_CAPTIVE_PORTAL)
|
| (1 << NET_CAPABILITY_FOREGROUND)
|
| (1 << NET_CAPABILITY_PARTIAL_CONNECTIVITY);
|
|
/**
|
* 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.
|
* <p>
|
* If the given capability was previously added to the list of unwanted capabilities
|
* then the capability will also be removed from the list of unwanted capabilities.
|
*
|
* @param capability the capability to be added.
|
* @return This NetworkCapabilities instance, to facilitate chaining.
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public @NonNull NetworkCapabilities addCapability(@NetCapability int capability) {
|
checkValidCapability(capability);
|
mNetworkCapabilities |= 1 << capability;
|
mUnwantedNetworkCapabilities &= ~(1 << capability); // remove from unwanted capability list
|
return this;
|
}
|
|
/**
|
* Adds the given capability to the list of unwanted capabilities of this
|
* {@code NetworkCapability} instance. Multiple unwanted capabilities may be applied
|
* sequentially. Note that when searching for a network to satisfy a request, the network
|
* must not contain any capability from unwanted capability list.
|
* <p>
|
* If the capability was previously added to the list of required capabilities (for
|
* example, it was there by default or added using {@link #addCapability(int)} method), then
|
* it will be removed from the list of required capabilities as well.
|
*
|
* @see #addCapability(int)
|
* @hide
|
*/
|
public void addUnwantedCapability(@NetCapability int capability) {
|
checkValidCapability(capability);
|
mUnwantedNetworkCapabilities |= 1 << capability;
|
mNetworkCapabilities &= ~(1 << capability); // remove from requested capabilities
|
}
|
|
/**
|
* Removes (if found) the given capability from this {@code NetworkCapability} instance.
|
* <p>
|
* Note that this method removes capabilities that were added via {@link #addCapability(int)},
|
* {@link #addUnwantedCapability(int)} or {@link #setCapabilities(int[], int[])} .
|
*
|
* @param capability the capability to be removed.
|
* @return This NetworkCapabilities instance, to facilitate chaining.
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public @NonNull NetworkCapabilities removeCapability(@NetCapability int capability) {
|
checkValidCapability(capability);
|
final long mask = ~(1 << capability);
|
mNetworkCapabilities &= mask;
|
mUnwantedNetworkCapabilities &= mask;
|
return this;
|
}
|
|
/**
|
* Sets (or clears) the given capability on this {@link NetworkCapabilities}
|
* instance.
|
*
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setCapability(@NetCapability int capability,
|
boolean value) {
|
if (value) {
|
addCapability(capability);
|
} else {
|
removeCapability(capability);
|
}
|
return this;
|
}
|
|
/**
|
* Gets all the capabilities set on this {@code NetworkCapability} instance.
|
*
|
* @return an array of capability values for this instance.
|
* @hide
|
*/
|
@TestApi
|
public @NetCapability int[] getCapabilities() {
|
return BitUtils.unpackBits(mNetworkCapabilities);
|
}
|
|
/**
|
* Gets all the unwanted capabilities set on this {@code NetworkCapability} instance.
|
*
|
* @return an array of unwanted capability values for this instance.
|
* @hide
|
*/
|
public @NetCapability int[] getUnwantedCapabilities() {
|
return BitUtils.unpackBits(mUnwantedNetworkCapabilities);
|
}
|
|
|
/**
|
* Sets all the capabilities set on this {@code NetworkCapability} instance.
|
* This overwrites any existing capabilities.
|
*
|
* @hide
|
*/
|
public void setCapabilities(@NetCapability int[] capabilities,
|
@NetCapability int[] unwantedCapabilities) {
|
mNetworkCapabilities = BitUtils.packBits(capabilities);
|
mUnwantedNetworkCapabilities = BitUtils.packBits(unwantedCapabilities);
|
}
|
|
/**
|
* @deprecated use {@link #setCapabilities(int[], int[])}
|
* @hide
|
*/
|
@Deprecated
|
public void setCapabilities(@NetCapability int[] capabilities) {
|
setCapabilities(capabilities, new int[] {});
|
}
|
|
/**
|
* Tests for the presence of a capability on this instance.
|
*
|
* @param capability the capabilities to be tested for.
|
* @return {@code true} if set on this instance.
|
*/
|
public boolean hasCapability(@NetCapability int capability) {
|
return isValidCapability(capability)
|
&& ((mNetworkCapabilities & (1 << capability)) != 0);
|
}
|
|
/** @hide */
|
public boolean hasUnwantedCapability(@NetCapability int capability) {
|
return isValidCapability(capability)
|
&& ((mUnwantedNetworkCapabilities & (1 << capability)) != 0);
|
}
|
|
/**
|
* Check if this NetworkCapabilities has system managed capabilities or not.
|
* @hide
|
*/
|
public boolean hasConnectivityManagedCapability() {
|
return ((mNetworkCapabilities & CONNECTIVITY_MANAGED_CAPABILITIES) != 0);
|
}
|
|
/** Note this method may result in having the same capability in wanted and unwanted lists. */
|
private void combineNetCapabilities(@NonNull NetworkCapabilities nc) {
|
this.mNetworkCapabilities |= nc.mNetworkCapabilities;
|
this.mUnwantedNetworkCapabilities |= nc.mUnwantedNetworkCapabilities;
|
}
|
|
/**
|
* Convenience function that returns a human-readable description of the first mutable
|
* capability we find. Used to present an error message to apps that request mutable
|
* capabilities.
|
*
|
* @hide
|
*/
|
public @Nullable String describeFirstNonRequestableCapability() {
|
final long nonRequestable = (mNetworkCapabilities | mUnwantedNetworkCapabilities)
|
& NON_REQUESTABLE_CAPABILITIES;
|
|
if (nonRequestable != 0) {
|
return capabilityNameOf(BitUtils.unpackBits(nonRequestable)[0]);
|
}
|
if (mLinkUpBandwidthKbps != 0 || mLinkDownBandwidthKbps != 0) return "link bandwidth";
|
if (hasSignalStrength()) return "signalStrength";
|
return null;
|
}
|
|
private boolean satisfiedByNetCapabilities(@NonNull NetworkCapabilities nc,
|
boolean onlyImmutable) {
|
long requestedCapabilities = mNetworkCapabilities;
|
long requestedUnwantedCapabilities = mUnwantedNetworkCapabilities;
|
long providedCapabilities = nc.mNetworkCapabilities;
|
|
if (onlyImmutable) {
|
requestedCapabilities &= ~MUTABLE_CAPABILITIES;
|
requestedUnwantedCapabilities &= ~MUTABLE_CAPABILITIES;
|
}
|
return ((providedCapabilities & requestedCapabilities) == requestedCapabilities)
|
&& ((requestedUnwantedCapabilities & providedCapabilities) == 0);
|
}
|
|
/** @hide */
|
public boolean equalsNetCapabilities(@NonNull NetworkCapabilities nc) {
|
return (nc.mNetworkCapabilities == this.mNetworkCapabilities)
|
&& (nc.mUnwantedNetworkCapabilities == this.mUnwantedNetworkCapabilities);
|
}
|
|
private boolean equalsNetCapabilitiesRequestable(@NonNull NetworkCapabilities that) {
|
return ((this.mNetworkCapabilities & ~NON_REQUESTABLE_CAPABILITIES) ==
|
(that.mNetworkCapabilities & ~NON_REQUESTABLE_CAPABILITIES))
|
&& ((this.mUnwantedNetworkCapabilities & ~NON_REQUESTABLE_CAPABILITIES) ==
|
(that.mUnwantedNetworkCapabilities & ~NON_REQUESTABLE_CAPABILITIES));
|
}
|
|
/**
|
* Removes the NET_CAPABILITY_NOT_RESTRICTED capability if all the capabilities it provides are
|
* typically provided by restricted networks.
|
*
|
* TODO: consider:
|
* - Renaming it to guessRestrictedCapability and make it set the
|
* restricted capability bit in addition to clearing it.
|
* @hide
|
*/
|
public void maybeMarkCapabilitiesRestricted() {
|
// Check if we have any capability that forces the network to be restricted.
|
final boolean forceRestrictedCapability =
|
(mNetworkCapabilities & FORCE_RESTRICTED_CAPABILITIES) != 0;
|
|
// Verify there aren't any unrestricted capabilities. If there are we say
|
// the whole thing is unrestricted unless it is forced to be restricted.
|
final boolean hasUnrestrictedCapabilities =
|
(mNetworkCapabilities & UNRESTRICTED_CAPABILITIES) != 0;
|
|
// Must have at least some restricted capabilities.
|
final boolean hasRestrictedCapabilities =
|
(mNetworkCapabilities & RESTRICTED_CAPABILITIES) != 0;
|
|
if (forceRestrictedCapability
|
|| (hasRestrictedCapabilities && !hasUnrestrictedCapabilities)) {
|
removeCapability(NET_CAPABILITY_NOT_RESTRICTED);
|
}
|
}
|
|
/**
|
* 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.
|
*/
|
private long mTransportTypes;
|
|
/** @hide */
|
@Retention(RetentionPolicy.SOURCE)
|
@IntDef(prefix = { "TRANSPORT_" }, value = {
|
TRANSPORT_CELLULAR,
|
TRANSPORT_WIFI,
|
TRANSPORT_BLUETOOTH,
|
TRANSPORT_ETHERNET,
|
TRANSPORT_VPN,
|
TRANSPORT_WIFI_AWARE,
|
TRANSPORT_LOWPAN,
|
TRANSPORT_TEST,
|
TRANSPORT_PPPOE,
|
})
|
public @interface Transport { }
|
|
/**
|
* 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;
|
|
/**
|
* Indicates this network uses a VPN transport.
|
*/
|
public static final int TRANSPORT_VPN = 4;
|
|
/**
|
* Indicates this network uses a Wi-Fi Aware transport.
|
*/
|
public static final int TRANSPORT_WIFI_AWARE = 5;
|
|
/**
|
* Indicates this network uses a LoWPAN transport.
|
*/
|
public static final int TRANSPORT_LOWPAN = 6;
|
|
/**
|
* Indicates this network uses a Test-only virtual interface as a transport.
|
*
|
* @hide
|
*/
|
@TestApi
|
public static final int TRANSPORT_TEST = 7;
|
|
/**
|
* Indicates this network uses a PPPOE transport.
|
*/
|
public static final int TRANSPORT_PPPOE = 8;
|
|
/** @hide */
|
public static final int MIN_TRANSPORT = TRANSPORT_CELLULAR;
|
/** @hide */
|
public static final int MAX_TRANSPORT = TRANSPORT_PPPOE;
|
|
/** @hide */
|
public static boolean isValidTransport(@Transport int transportType) {
|
return (MIN_TRANSPORT <= transportType) && (transportType <= MAX_TRANSPORT);
|
}
|
|
private static final String[] TRANSPORT_NAMES = {
|
"CELLULAR",
|
"WIFI",
|
"BLUETOOTH",
|
"ETHERNET",
|
"VPN",
|
"WIFI_AWARE",
|
"LOWPAN",
|
"TEST" ,
|
"PPPOE"
|
};
|
|
/**
|
* 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 transport type to be added.
|
* @return This NetworkCapabilities instance, to facilitate chaining.
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public @NonNull NetworkCapabilities addTransportType(@Transport int transportType) {
|
checkValidTransportType(transportType);
|
mTransportTypes |= 1 << transportType;
|
setNetworkSpecifier(mNetworkSpecifier); // used for exception checking
|
return this;
|
}
|
|
/**
|
* Removes (if found) the given transport from this {@code NetworkCapability} instance.
|
*
|
* @param transportType the transport type to be removed.
|
* @return This NetworkCapabilities instance, to facilitate chaining.
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities removeTransportType(@Transport int transportType) {
|
checkValidTransportType(transportType);
|
mTransportTypes &= ~(1 << transportType);
|
setNetworkSpecifier(mNetworkSpecifier); // used for exception checking
|
return this;
|
}
|
|
/**
|
* Sets (or clears) the given transport on this {@link NetworkCapabilities}
|
* instance.
|
*
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setTransportType(@Transport int transportType,
|
boolean value) {
|
if (value) {
|
addTransportType(transportType);
|
} else {
|
removeTransportType(transportType);
|
}
|
return this;
|
}
|
|
/**
|
* Gets all the transports set on this {@code NetworkCapability} instance.
|
*
|
* @return an array of transport type values for this instance.
|
* @hide
|
*/
|
@TestApi
|
@SystemApi
|
@NonNull public @Transport int[] getTransportTypes() {
|
return BitUtils.unpackBits(mTransportTypes);
|
}
|
|
/**
|
* Sets all the transports set on this {@code NetworkCapability} instance.
|
* This overwrites any existing transports.
|
*
|
* @hide
|
*/
|
public void setTransportTypes(@Transport int[] transportTypes) {
|
mTransportTypes = BitUtils.packBits(transportTypes);
|
}
|
|
/**
|
* Tests for the presence of a transport on this instance.
|
*
|
* @param transportType the transport type to be tested for.
|
* @return {@code true} if set on this instance.
|
*/
|
public boolean hasTransport(@Transport int transportType) {
|
return isValidTransport(transportType) && ((mTransportTypes & (1 << transportType)) != 0);
|
}
|
|
private void combineTransportTypes(NetworkCapabilities nc) {
|
this.mTransportTypes |= nc.mTransportTypes;
|
}
|
|
private boolean satisfiedByTransportTypes(NetworkCapabilities nc) {
|
return ((this.mTransportTypes == 0) ||
|
((this.mTransportTypes & nc.mTransportTypes) != 0));
|
}
|
|
/** @hide */
|
public boolean equalsTransportTypes(NetworkCapabilities nc) {
|
return (nc.mTransportTypes == this.mTransportTypes);
|
}
|
|
/**
|
* UID of the app that manages this network, or INVALID_UID if none/unknown.
|
*
|
* This field keeps track of the UID of the app that created this network and is in charge
|
* of managing it. In the practice, it is used to store the UID of VPN apps so it is named
|
* accordingly, but it may be renamed if other mechanisms are offered for third party apps
|
* to create networks.
|
*
|
* Because this field is only used in the services side (and to avoid apps being able to
|
* set this to whatever they want), this field is not parcelled and will not be conserved
|
* across the IPC boundary.
|
* @hide
|
*/
|
private int mEstablishingVpnAppUid = INVALID_UID;
|
|
/**
|
* Set the UID of the managing app.
|
* @hide
|
*/
|
public void setEstablishingVpnAppUid(final int uid) {
|
mEstablishingVpnAppUid = uid;
|
}
|
|
/** @hide */
|
public int getEstablishingVpnAppUid() {
|
return mEstablishingVpnAppUid;
|
}
|
|
/**
|
* Value indicating that link bandwidth is unspecified.
|
* @hide
|
*/
|
public static final int LINK_BANDWIDTH_UNSPECIFIED = 0;
|
|
/**
|
* 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 mLinkUpBandwidthKbps = LINK_BANDWIDTH_UNSPECIFIED;
|
private int mLinkDownBandwidthKbps = LINK_BANDWIDTH_UNSPECIFIED;
|
|
/**
|
* 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.
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setLinkUpstreamBandwidthKbps(int upKbps) {
|
mLinkUpBandwidthKbps = upKbps;
|
return this;
|
}
|
|
/**
|
* 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.
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setLinkDownstreamBandwidthKbps(int downKbps) {
|
mLinkDownBandwidthKbps = downKbps;
|
return this;
|
}
|
|
/**
|
* 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;
|
}
|
|
private void combineLinkBandwidths(NetworkCapabilities nc) {
|
this.mLinkUpBandwidthKbps =
|
Math.max(this.mLinkUpBandwidthKbps, nc.mLinkUpBandwidthKbps);
|
this.mLinkDownBandwidthKbps =
|
Math.max(this.mLinkDownBandwidthKbps, nc.mLinkDownBandwidthKbps);
|
}
|
private boolean satisfiedByLinkBandwidths(NetworkCapabilities nc) {
|
return !(this.mLinkUpBandwidthKbps > nc.mLinkUpBandwidthKbps ||
|
this.mLinkDownBandwidthKbps > nc.mLinkDownBandwidthKbps);
|
}
|
private boolean equalsLinkBandwidths(NetworkCapabilities nc) {
|
return (this.mLinkUpBandwidthKbps == nc.mLinkUpBandwidthKbps &&
|
this.mLinkDownBandwidthKbps == nc.mLinkDownBandwidthKbps);
|
}
|
/** @hide */
|
public static int minBandwidth(int a, int b) {
|
if (a == LINK_BANDWIDTH_UNSPECIFIED) {
|
return b;
|
} else if (b == LINK_BANDWIDTH_UNSPECIFIED) {
|
return a;
|
} else {
|
return Math.min(a, b);
|
}
|
}
|
/** @hide */
|
public static int maxBandwidth(int a, int b) {
|
return Math.max(a, b);
|
}
|
|
private NetworkSpecifier mNetworkSpecifier = null;
|
private TransportInfo mTransportInfo = null;
|
|
/**
|
* 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.
|
* </p>
|
*
|
* @param networkSpecifier A concrete, parcelable framework class that extends
|
* NetworkSpecifier.
|
* @return This NetworkCapabilities instance, to facilitate chaining.
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setNetworkSpecifier(NetworkSpecifier networkSpecifier) {
|
if (networkSpecifier != null && Long.bitCount(mTransportTypes) != 1) {
|
throw new IllegalStateException("Must have a single transport specified to use " +
|
"setNetworkSpecifier");
|
}
|
|
mNetworkSpecifier = networkSpecifier;
|
|
return this;
|
}
|
|
/**
|
* Sets the optional transport specific information.
|
*
|
* @param transportInfo A concrete, parcelable framework class that extends
|
* {@link TransportInfo}.
|
* @return This NetworkCapabilities instance, to facilitate chaining.
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setTransportInfo(TransportInfo transportInfo) {
|
mTransportInfo = transportInfo;
|
return this;
|
}
|
|
/**
|
* Gets the optional bearer specific network specifier. May be {@code null} if not set.
|
*
|
* @return The optional {@link NetworkSpecifier} specifying the bearer specific network
|
* specifier or {@code null}. See {@link #setNetworkSpecifier}.
|
* @hide
|
*/
|
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023)
|
public @Nullable NetworkSpecifier getNetworkSpecifier() {
|
return mNetworkSpecifier;
|
}
|
|
/**
|
* Returns a transport-specific information container. The application may cast this
|
* container to a concrete sub-class based on its knowledge of the network request. The
|
* application should be able to deal with a {@code null} return value or an invalid case,
|
* e.g. use {@code instanceof} operator to verify expected type.
|
*
|
* @return A concrete implementation of the {@link TransportInfo} class or null if not
|
* available for the network.
|
*/
|
@Nullable public TransportInfo getTransportInfo() {
|
return mTransportInfo;
|
}
|
|
private void combineSpecifiers(NetworkCapabilities nc) {
|
if (mNetworkSpecifier != null && !mNetworkSpecifier.equals(nc.mNetworkSpecifier)) {
|
throw new IllegalStateException("Can't combine two networkSpecifiers");
|
}
|
setNetworkSpecifier(nc.mNetworkSpecifier);
|
}
|
|
private boolean satisfiedBySpecifier(NetworkCapabilities nc) {
|
return mNetworkSpecifier == null || mNetworkSpecifier.satisfiedBy(nc.mNetworkSpecifier)
|
|| nc.mNetworkSpecifier instanceof MatchAllNetworkSpecifier;
|
}
|
|
private boolean equalsSpecifier(NetworkCapabilities nc) {
|
return Objects.equals(mNetworkSpecifier, nc.mNetworkSpecifier);
|
}
|
|
private void combineTransportInfos(NetworkCapabilities nc) {
|
if (mTransportInfo != null && !mTransportInfo.equals(nc.mTransportInfo)) {
|
throw new IllegalStateException("Can't combine two TransportInfos");
|
}
|
setTransportInfo(nc.mTransportInfo);
|
}
|
|
private boolean equalsTransportInfo(NetworkCapabilities nc) {
|
return Objects.equals(mTransportInfo, nc.mTransportInfo);
|
}
|
|
/**
|
* Magic value that indicates no signal strength provided. A request specifying this value is
|
* always satisfied.
|
*/
|
public static final int SIGNAL_STRENGTH_UNSPECIFIED = Integer.MIN_VALUE;
|
|
/**
|
* Signal strength. This is a signed integer, and higher values indicate better signal.
|
* The exact units are bearer-dependent. For example, Wi-Fi uses RSSI.
|
*/
|
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P)
|
private int mSignalStrength = SIGNAL_STRENGTH_UNSPECIFIED;
|
|
/**
|
* Sets the signal strength. This is a signed integer, with higher values indicating a stronger
|
* signal. The exact units are bearer-dependent. For example, Wi-Fi uses the same RSSI units
|
* reported by wifi code.
|
* <p>
|
* Note that when used to register a network callback, this specifies the minimum acceptable
|
* signal strength. When received as the state of an existing network it specifies the current
|
* value. A value of code SIGNAL_STRENGTH_UNSPECIFIED} means no value when received and has no
|
* effect when requesting a callback.
|
*
|
* @param signalStrength the bearer-specific signal strength.
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public @NonNull NetworkCapabilities setSignalStrength(int signalStrength) {
|
mSignalStrength = signalStrength;
|
return this;
|
}
|
|
/**
|
* Returns {@code true} if this object specifies a signal strength.
|
*
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public boolean hasSignalStrength() {
|
return mSignalStrength > SIGNAL_STRENGTH_UNSPECIFIED;
|
}
|
|
/**
|
* Retrieves the signal strength.
|
*
|
* @return The bearer-specific signal strength.
|
*/
|
public int getSignalStrength() {
|
return mSignalStrength;
|
}
|
|
private void combineSignalStrength(NetworkCapabilities nc) {
|
this.mSignalStrength = Math.max(this.mSignalStrength, nc.mSignalStrength);
|
}
|
|
private boolean satisfiedBySignalStrength(NetworkCapabilities nc) {
|
return this.mSignalStrength <= nc.mSignalStrength;
|
}
|
|
private boolean equalsSignalStrength(NetworkCapabilities nc) {
|
return this.mSignalStrength == nc.mSignalStrength;
|
}
|
|
/**
|
* List of UIDs this network applies to. No restriction if null.
|
* <p>
|
* For networks, mUids represent the list of network this applies to, and null means this
|
* network applies to all UIDs.
|
* For requests, mUids is the list of UIDs this network MUST apply to to match ; ALL UIDs
|
* must be included in a network so that they match. As an exception to the general rule,
|
* a null mUids field for requests mean "no requirements" rather than what the general rule
|
* would suggest ("must apply to all UIDs") : this is because this has shown to be what users
|
* of this API expect in practice. A network that must match all UIDs can still be
|
* expressed with a set ranging the entire set of possible UIDs.
|
* <p>
|
* mUids is typically (and at this time, only) used by VPN. This network is only available to
|
* the UIDs in this list, and it is their default network. Apps in this list that wish to
|
* bypass the VPN can do so iff the VPN app allows them to or if they are privileged. If this
|
* member is null, then the network is not restricted by app UID. If it's an empty list, then
|
* it means nobody can use it.
|
* As a special exception, the app managing this network (as identified by its UID stored in
|
* mEstablishingVpnAppUid) can always see this network. This is embodied by a special check in
|
* satisfiedByUids. That still does not mean the network necessarily <strong>applies</strong>
|
* to the app that manages it as determined by #appliesToUid.
|
* <p>
|
* Please note that in principle a single app can be associated with multiple UIDs because
|
* each app will have a different UID when it's run as a different (macro-)user. A single
|
* macro user can only have a single active VPN app at any given time however.
|
* <p>
|
* Also please be aware this class does not try to enforce any normalization on this. Callers
|
* can only alter the UIDs by setting them wholesale : this class does not provide any utility
|
* to add or remove individual UIDs or ranges. If callers have any normalization needs on
|
* their own (like requiring sortedness or no overlap) they need to enforce it
|
* themselves. Some of the internal methods also assume this is normalized as in no adjacent
|
* or overlapping ranges are present.
|
*
|
* @hide
|
*/
|
private ArraySet<UidRange> mUids = null;
|
|
/**
|
* Convenience method to set the UIDs this network applies to to a single UID.
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setSingleUid(int uid) {
|
final ArraySet<UidRange> identity = new ArraySet<>(1);
|
identity.add(new UidRange(uid, uid));
|
setUids(identity);
|
return this;
|
}
|
|
/**
|
* Set the list of UIDs this network applies to.
|
* This makes a copy of the set so that callers can't modify it after the call.
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setUids(Set<UidRange> uids) {
|
if (null == uids) {
|
mUids = null;
|
} else {
|
mUids = new ArraySet<>(uids);
|
}
|
return this;
|
}
|
|
/**
|
* Get the list of UIDs this network applies to.
|
* This returns a copy of the set so that callers can't modify the original object.
|
* @hide
|
*/
|
public @Nullable Set<UidRange> getUids() {
|
return null == mUids ? null : new ArraySet<>(mUids);
|
}
|
|
/**
|
* Test whether this network applies to this UID.
|
* @hide
|
*/
|
public boolean appliesToUid(int uid) {
|
if (null == mUids) return true;
|
for (UidRange range : mUids) {
|
if (range.contains(uid)) {
|
return true;
|
}
|
}
|
return false;
|
}
|
|
/**
|
* Tests if the set of UIDs that this network applies to is the same as the passed network.
|
* <p>
|
* This test only checks whether equal range objects are in both sets. It will
|
* return false if the ranges are not exactly the same, even if the covered UIDs
|
* are for an equivalent result.
|
* <p>
|
* Note that this method is not very optimized, which is fine as long as it's not used very
|
* often.
|
* <p>
|
* nc is assumed nonnull.
|
*
|
* @hide
|
*/
|
@VisibleForTesting
|
public boolean equalsUids(@NonNull NetworkCapabilities nc) {
|
Set<UidRange> comparedUids = nc.mUids;
|
if (null == comparedUids) return null == mUids;
|
if (null == mUids) return false;
|
// Make a copy so it can be mutated to check that all ranges in mUids
|
// also are in uids.
|
final Set<UidRange> uids = new ArraySet<>(mUids);
|
for (UidRange range : comparedUids) {
|
if (!uids.contains(range)) {
|
return false;
|
}
|
uids.remove(range);
|
}
|
return uids.isEmpty();
|
}
|
|
/**
|
* Test whether the passed NetworkCapabilities satisfies the UIDs this capabilities require.
|
*
|
* This method is called on the NetworkCapabilities embedded in a request with the
|
* capabilities of an available network. It checks whether all the UIDs from this listen
|
* (representing the UIDs that must have access to the network) are satisfied by the UIDs
|
* in the passed nc (representing the UIDs that this network is available to).
|
* <p>
|
* As a special exception, the UID that created the passed network (as represented by its
|
* mEstablishingVpnAppUid field) always satisfies a NetworkRequest requiring it (of LISTEN
|
* or REQUEST types alike), even if the network does not apply to it. That is so a VPN app
|
* can see its own network when it listens for it.
|
* <p>
|
* nc is assumed nonnull. Else, NPE.
|
* @see #appliesToUid
|
* @hide
|
*/
|
public boolean satisfiedByUids(@NonNull NetworkCapabilities nc) {
|
if (null == nc.mUids || null == mUids) return true; // The network satisfies everything.
|
for (UidRange requiredRange : mUids) {
|
if (requiredRange.contains(nc.mEstablishingVpnAppUid)) return true;
|
if (!nc.appliesToUidRange(requiredRange)) {
|
return false;
|
}
|
}
|
return true;
|
}
|
|
/**
|
* Returns whether this network applies to the passed ranges.
|
* This assumes that to apply, the passed range has to be entirely contained
|
* within one of the ranges this network applies to. If the ranges are not normalized,
|
* this method may return false even though all required UIDs are covered because no
|
* single range contained them all.
|
* @hide
|
*/
|
@VisibleForTesting
|
public boolean appliesToUidRange(@Nullable UidRange requiredRange) {
|
if (null == mUids) return true;
|
for (UidRange uidRange : mUids) {
|
if (uidRange.containsRange(requiredRange)) {
|
return true;
|
}
|
}
|
return false;
|
}
|
|
/**
|
* Combine the UIDs this network currently applies to with the UIDs the passed
|
* NetworkCapabilities apply to.
|
* nc is assumed nonnull.
|
*/
|
private void combineUids(@NonNull NetworkCapabilities nc) {
|
if (null == nc.mUids || null == mUids) {
|
mUids = null;
|
return;
|
}
|
mUids.addAll(nc.mUids);
|
}
|
|
|
/**
|
* The SSID of the network, or null if not applicable or unknown.
|
* <p>
|
* This is filled in by wifi code.
|
* @hide
|
*/
|
private String mSSID;
|
|
/**
|
* Sets the SSID of this network.
|
* @hide
|
*/
|
public @NonNull NetworkCapabilities setSSID(@Nullable String ssid) {
|
mSSID = ssid;
|
return this;
|
}
|
|
/**
|
* Gets the SSID of this network, or null if none or unknown.
|
* @hide
|
*/
|
public @Nullable String getSSID() {
|
return mSSID;
|
}
|
|
/**
|
* Tests if the SSID of this network is the same as the SSID of the passed network.
|
* @hide
|
*/
|
public boolean equalsSSID(@NonNull NetworkCapabilities nc) {
|
return Objects.equals(mSSID, nc.mSSID);
|
}
|
|
/**
|
* Check if the SSID requirements of this object are matched by the passed object.
|
* @hide
|
*/
|
public boolean satisfiedBySSID(@NonNull NetworkCapabilities nc) {
|
return mSSID == null || mSSID.equals(nc.mSSID);
|
}
|
|
/**
|
* Combine SSIDs of the capabilities.
|
* <p>
|
* This is only legal if either the SSID of this object is null, or both SSIDs are
|
* equal.
|
* @hide
|
*/
|
private void combineSSIDs(@NonNull NetworkCapabilities nc) {
|
if (mSSID != null && !mSSID.equals(nc.mSSID)) {
|
throw new IllegalStateException("Can't combine two SSIDs");
|
}
|
setSSID(nc.mSSID);
|
}
|
|
/**
|
* Combine a set of Capabilities to this one. Useful for coming up with the complete set.
|
* <p>
|
* Note that this method may break an invariant of having a particular capability in either
|
* wanted or unwanted lists but never in both. Requests that have the same capability in
|
* both lists will never be satisfied.
|
* @hide
|
*/
|
public void combineCapabilities(@NonNull NetworkCapabilities nc) {
|
combineNetCapabilities(nc);
|
combineTransportTypes(nc);
|
combineLinkBandwidths(nc);
|
combineSpecifiers(nc);
|
combineTransportInfos(nc);
|
combineSignalStrength(nc);
|
combineUids(nc);
|
combineSSIDs(nc);
|
}
|
|
/**
|
* Check if our requirements are satisfied by the given {@code NetworkCapabilities}.
|
*
|
* @param nc the {@code NetworkCapabilities} that may or may not satisfy our requirements.
|
* @param onlyImmutable if {@code true}, do not consider mutable requirements such as link
|
* bandwidth, signal strength, or validation / captive portal status.
|
*
|
* @hide
|
*/
|
private boolean satisfiedByNetworkCapabilities(NetworkCapabilities nc, boolean onlyImmutable) {
|
return (nc != null
|
&& satisfiedByNetCapabilities(nc, onlyImmutable)
|
&& satisfiedByTransportTypes(nc)
|
&& (onlyImmutable || satisfiedByLinkBandwidths(nc))
|
&& satisfiedBySpecifier(nc)
|
&& (onlyImmutable || satisfiedBySignalStrength(nc))
|
&& (onlyImmutable || satisfiedByUids(nc))
|
&& (onlyImmutable || satisfiedBySSID(nc)));
|
}
|
|
/**
|
* Check if our requirements are satisfied by the given {@code NetworkCapabilities}.
|
*
|
* @param nc the {@code NetworkCapabilities} that may or may not satisfy our requirements.
|
*
|
* @hide
|
*/
|
@TestApi
|
@SystemApi
|
public boolean satisfiedByNetworkCapabilities(@Nullable NetworkCapabilities nc) {
|
return satisfiedByNetworkCapabilities(nc, false);
|
}
|
|
/**
|
* Check if our immutable requirements are satisfied by the given {@code NetworkCapabilities}.
|
*
|
* @param nc the {@code NetworkCapabilities} that may or may not satisfy our requirements.
|
*
|
* @hide
|
*/
|
public boolean satisfiedByImmutableNetworkCapabilities(@Nullable NetworkCapabilities nc) {
|
return satisfiedByNetworkCapabilities(nc, true);
|
}
|
|
/**
|
* Checks that our immutable capabilities are the same as those of the given
|
* {@code NetworkCapabilities} and return a String describing any difference.
|
* The returned String is empty if there is no difference.
|
*
|
* @hide
|
*/
|
public String describeImmutableDifferences(@Nullable NetworkCapabilities that) {
|
if (that == null) {
|
return "other NetworkCapabilities was null";
|
}
|
|
StringJoiner joiner = new StringJoiner(", ");
|
|
// Ignore NOT_METERED being added or removed as it is effectively dynamic. http://b/63326103
|
// TODO: properly support NOT_METERED as a mutable and requestable capability.
|
final long mask = ~MUTABLE_CAPABILITIES & ~(1 << NET_CAPABILITY_NOT_METERED);
|
long oldImmutableCapabilities = this.mNetworkCapabilities & mask;
|
long newImmutableCapabilities = that.mNetworkCapabilities & mask;
|
if (oldImmutableCapabilities != newImmutableCapabilities) {
|
String before = capabilityNamesOf(BitUtils.unpackBits(oldImmutableCapabilities));
|
String after = capabilityNamesOf(BitUtils.unpackBits(newImmutableCapabilities));
|
joiner.add(String.format("immutable capabilities changed: %s -> %s", before, after));
|
}
|
|
if (!equalsSpecifier(that)) {
|
NetworkSpecifier before = this.getNetworkSpecifier();
|
NetworkSpecifier after = that.getNetworkSpecifier();
|
joiner.add(String.format("specifier changed: %s -> %s", before, after));
|
}
|
|
if (!equalsTransportTypes(that)) {
|
String before = transportNamesOf(this.getTransportTypes());
|
String after = transportNamesOf(that.getTransportTypes());
|
joiner.add(String.format("transports changed: %s -> %s", before, after));
|
}
|
|
return joiner.toString();
|
}
|
|
/**
|
* Checks that our requestable capabilities are the same as those of the given
|
* {@code NetworkCapabilities}.
|
*
|
* @hide
|
*/
|
public boolean equalRequestableCapabilities(@Nullable NetworkCapabilities nc) {
|
if (nc == null) return false;
|
return (equalsNetCapabilitiesRequestable(nc) &&
|
equalsTransportTypes(nc) &&
|
equalsSpecifier(nc));
|
}
|
|
@Override
|
public boolean equals(@Nullable Object obj) {
|
if (obj == null || (obj instanceof NetworkCapabilities == false)) return false;
|
NetworkCapabilities that = (NetworkCapabilities) obj;
|
return (equalsNetCapabilities(that)
|
&& equalsTransportTypes(that)
|
&& equalsLinkBandwidths(that)
|
&& equalsSignalStrength(that)
|
&& equalsSpecifier(that)
|
&& equalsTransportInfo(that)
|
&& equalsUids(that)
|
&& equalsSSID(that));
|
}
|
|
@Override
|
public int hashCode() {
|
return (int) (mNetworkCapabilities & 0xFFFFFFFF)
|
+ ((int) (mNetworkCapabilities >> 32) * 3)
|
+ ((int) (mUnwantedNetworkCapabilities & 0xFFFFFFFF) * 5)
|
+ ((int) (mUnwantedNetworkCapabilities >> 32) * 7)
|
+ ((int) (mTransportTypes & 0xFFFFFFFF) * 11)
|
+ ((int) (mTransportTypes >> 32) * 13)
|
+ (mLinkUpBandwidthKbps * 17)
|
+ (mLinkDownBandwidthKbps * 19)
|
+ Objects.hashCode(mNetworkSpecifier) * 23
|
+ (mSignalStrength * 29)
|
+ Objects.hashCode(mUids) * 31
|
+ Objects.hashCode(mSSID) * 37
|
+ Objects.hashCode(mTransportInfo) * 41;
|
}
|
|
@Override
|
public int describeContents() {
|
return 0;
|
}
|
@Override
|
public void writeToParcel(Parcel dest, int flags) {
|
dest.writeLong(mNetworkCapabilities);
|
dest.writeLong(mUnwantedNetworkCapabilities);
|
dest.writeLong(mTransportTypes);
|
dest.writeInt(mLinkUpBandwidthKbps);
|
dest.writeInt(mLinkDownBandwidthKbps);
|
dest.writeParcelable((Parcelable) mNetworkSpecifier, flags);
|
dest.writeParcelable((Parcelable) mTransportInfo, flags);
|
dest.writeInt(mSignalStrength);
|
dest.writeArraySet(mUids);
|
dest.writeString(mSSID);
|
}
|
|
public static final @android.annotation.NonNull Creator<NetworkCapabilities> CREATOR =
|
new Creator<NetworkCapabilities>() {
|
@Override
|
public NetworkCapabilities createFromParcel(Parcel in) {
|
NetworkCapabilities netCap = new NetworkCapabilities();
|
|
netCap.mNetworkCapabilities = in.readLong();
|
netCap.mUnwantedNetworkCapabilities = in.readLong();
|
netCap.mTransportTypes = in.readLong();
|
netCap.mLinkUpBandwidthKbps = in.readInt();
|
netCap.mLinkDownBandwidthKbps = in.readInt();
|
netCap.mNetworkSpecifier = in.readParcelable(null);
|
netCap.mTransportInfo = in.readParcelable(null);
|
netCap.mSignalStrength = in.readInt();
|
netCap.mUids = (ArraySet<UidRange>) in.readArraySet(
|
null /* ClassLoader, null for default */);
|
netCap.mSSID = in.readString();
|
return netCap;
|
}
|
@Override
|
public NetworkCapabilities[] newArray(int size) {
|
return new NetworkCapabilities[size];
|
}
|
};
|
|
@Override
|
public @NonNull String toString() {
|
final StringBuilder sb = new StringBuilder("[");
|
if (0 != mTransportTypes) {
|
sb.append(" Transports: ");
|
appendStringRepresentationOfBitMaskToStringBuilder(sb, mTransportTypes,
|
NetworkCapabilities::transportNameOf, "|");
|
}
|
if (0 != mNetworkCapabilities) {
|
sb.append(" Capabilities: ");
|
appendStringRepresentationOfBitMaskToStringBuilder(sb, mNetworkCapabilities,
|
NetworkCapabilities::capabilityNameOf, "&");
|
}
|
if (0 != mUnwantedNetworkCapabilities) {
|
sb.append(" Unwanted: ");
|
appendStringRepresentationOfBitMaskToStringBuilder(sb, mUnwantedNetworkCapabilities,
|
NetworkCapabilities::capabilityNameOf, "&");
|
}
|
if (mLinkUpBandwidthKbps > 0) {
|
sb.append(" LinkUpBandwidth>=").append(mLinkUpBandwidthKbps).append("Kbps");
|
}
|
if (mLinkDownBandwidthKbps > 0) {
|
sb.append(" LinkDnBandwidth>=").append(mLinkDownBandwidthKbps).append("Kbps");
|
}
|
if (mNetworkSpecifier != null) {
|
sb.append(" Specifier: <").append(mNetworkSpecifier).append(">");
|
}
|
if (mTransportInfo != null) {
|
sb.append(" TransportInfo: <").append(mTransportInfo).append(">");
|
}
|
if (hasSignalStrength()) {
|
sb.append(" SignalStrength: ").append(mSignalStrength);
|
}
|
|
if (null != mUids) {
|
if ((1 == mUids.size()) && (mUids.valueAt(0).count() == 1)) {
|
sb.append(" Uid: ").append(mUids.valueAt(0).start);
|
} else {
|
sb.append(" Uids: <").append(mUids).append(">");
|
}
|
}
|
if (mEstablishingVpnAppUid != INVALID_UID) {
|
sb.append(" EstablishingAppUid: ").append(mEstablishingVpnAppUid);
|
}
|
|
if (null != mSSID) {
|
sb.append(" SSID: ").append(mSSID);
|
}
|
|
sb.append("]");
|
return sb.toString();
|
}
|
|
|
private interface NameOf {
|
String nameOf(int value);
|
}
|
/**
|
* @hide
|
*/
|
public static void appendStringRepresentationOfBitMaskToStringBuilder(@NonNull StringBuilder sb,
|
long bitMask, @NonNull NameOf nameFetcher, @NonNull String separator) {
|
int bitPos = 0;
|
boolean firstElementAdded = false;
|
while (bitMask != 0) {
|
if ((bitMask & 1) != 0) {
|
if (firstElementAdded) {
|
sb.append(separator);
|
} else {
|
firstElementAdded = true;
|
}
|
sb.append(nameFetcher.nameOf(bitPos));
|
}
|
bitMask >>= 1;
|
++bitPos;
|
}
|
}
|
|
/** @hide */
|
public void writeToProto(@NonNull ProtoOutputStream proto, long fieldId) {
|
final long token = proto.start(fieldId);
|
|
for (int transport : getTransportTypes()) {
|
proto.write(NetworkCapabilitiesProto.TRANSPORTS, transport);
|
}
|
|
for (int capability : getCapabilities()) {
|
proto.write(NetworkCapabilitiesProto.CAPABILITIES, capability);
|
}
|
|
proto.write(NetworkCapabilitiesProto.LINK_UP_BANDWIDTH_KBPS, mLinkUpBandwidthKbps);
|
proto.write(NetworkCapabilitiesProto.LINK_DOWN_BANDWIDTH_KBPS, mLinkDownBandwidthKbps);
|
|
if (mNetworkSpecifier != null) {
|
proto.write(NetworkCapabilitiesProto.NETWORK_SPECIFIER, mNetworkSpecifier.toString());
|
}
|
if (mTransportInfo != null) {
|
// TODO b/120653863: write transport-specific info to proto?
|
}
|
|
proto.write(NetworkCapabilitiesProto.CAN_REPORT_SIGNAL_STRENGTH, hasSignalStrength());
|
proto.write(NetworkCapabilitiesProto.SIGNAL_STRENGTH, mSignalStrength);
|
|
proto.end(token);
|
}
|
|
/**
|
* @hide
|
*/
|
public static @NonNull String capabilityNamesOf(@Nullable @NetCapability int[] capabilities) {
|
StringJoiner joiner = new StringJoiner("|");
|
if (capabilities != null) {
|
for (int c : capabilities) {
|
joiner.add(capabilityNameOf(c));
|
}
|
}
|
return joiner.toString();
|
}
|
|
/**
|
* @hide
|
*/
|
public static @NonNull String capabilityNameOf(@NetCapability int capability) {
|
switch (capability) {
|
case NET_CAPABILITY_MMS: return "MMS";
|
case NET_CAPABILITY_SUPL: return "SUPL";
|
case NET_CAPABILITY_DUN: return "DUN";
|
case NET_CAPABILITY_FOTA: return "FOTA";
|
case NET_CAPABILITY_IMS: return "IMS";
|
case NET_CAPABILITY_CBS: return "CBS";
|
case NET_CAPABILITY_WIFI_P2P: return "WIFI_P2P";
|
case NET_CAPABILITY_IA: return "IA";
|
case NET_CAPABILITY_RCS: return "RCS";
|
case NET_CAPABILITY_XCAP: return "XCAP";
|
case NET_CAPABILITY_EIMS: return "EIMS";
|
case NET_CAPABILITY_NOT_METERED: return "NOT_METERED";
|
case NET_CAPABILITY_INTERNET: return "INTERNET";
|
case NET_CAPABILITY_NOT_RESTRICTED: return "NOT_RESTRICTED";
|
case NET_CAPABILITY_TRUSTED: return "TRUSTED";
|
case NET_CAPABILITY_NOT_VPN: return "NOT_VPN";
|
case NET_CAPABILITY_VALIDATED: return "VALIDATED";
|
case NET_CAPABILITY_CAPTIVE_PORTAL: return "CAPTIVE_PORTAL";
|
case NET_CAPABILITY_NOT_ROAMING: return "NOT_ROAMING";
|
case NET_CAPABILITY_FOREGROUND: return "FOREGROUND";
|
case NET_CAPABILITY_NOT_CONGESTED: return "NOT_CONGESTED";
|
case NET_CAPABILITY_NOT_SUSPENDED: return "NOT_SUSPENDED";
|
case NET_CAPABILITY_OEM_PAID: return "OEM_PAID";
|
case NET_CAPABILITY_MCX: return "MCX";
|
case NET_CAPABILITY_PARTIAL_CONNECTIVITY: return "PARTIAL_CONNECTIVITY";
|
default: return Integer.toString(capability);
|
}
|
}
|
|
/**
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public static @NonNull String transportNamesOf(@Nullable @Transport int[] types) {
|
StringJoiner joiner = new StringJoiner("|");
|
if (types != null) {
|
for (int t : types) {
|
joiner.add(transportNameOf(t));
|
}
|
}
|
return joiner.toString();
|
}
|
|
/**
|
* @hide
|
*/
|
public static @NonNull String transportNameOf(@Transport int transport) {
|
if (!isValidTransport(transport)) {
|
return "UNKNOWN";
|
}
|
return TRANSPORT_NAMES[transport];
|
}
|
|
private static void checkValidTransportType(@Transport int transport) {
|
Preconditions.checkArgument(
|
isValidTransport(transport), "Invalid TransportType " + transport);
|
}
|
|
private static boolean isValidCapability(@NetworkCapabilities.NetCapability int capability) {
|
return capability >= MIN_NET_CAPABILITY && capability <= MAX_NET_CAPABILITY;
|
}
|
|
private static void checkValidCapability(@NetworkCapabilities.NetCapability int capability) {
|
Preconditions.checkArgument(isValidCapability(capability),
|
"NetworkCapability " + capability + "out of range");
|
}
|
|
/**
|
* Check if this {@code NetworkCapability} instance is metered.
|
*
|
* @return {@code true} if {@code NET_CAPABILITY_NOT_METERED} is not set on this instance.
|
* @hide
|
*/
|
public boolean isMetered() {
|
return !hasCapability(NET_CAPABILITY_NOT_METERED);
|
}
|
}
|
