core/java/android/net/NetworkCapabilities.java

   1 /*
   2  * Copyright (C) 2014 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.Parcel;
  20 import android.os.Parcelable;
  21
  22 import com.android.internal.annotations.VisibleForTesting;
  23 import com.android.internal.util.BitUtils;
  24 import com.android.internal.util.Preconditions;
  25
  26 import java.util.Objects;
  27
  28 /**
  29  * This class represents the capabilities of a network.  This is used both to specify
  30  * needs to {@link ConnectivityManager} and when inspecting a network.
  31  *
  32  * Note that this replaces the old {@link ConnectivityManager#TYPE_MOBILE} method
  33  * of network selection.  Rather than indicate a need for Wi-Fi because an application
  34  * needs high bandwidth and risk obsolescence when a new, fast network appears (like LTE),
  35  * the application should specify it needs high bandwidth.  Similarly if an application
  36  * needs an unmetered network for a bulk transfer it can specify that rather than assuming
  37  * all cellular based connections are metered and all Wi-Fi based connections are not.
  38  */
  39 public final class NetworkCapabilities implements Parcelable {
  40     private static final String TAG = "NetworkCapabilities";
  41
  42     /**
  43      * @hide
  44      */
  45     public NetworkCapabilities() {
  46         clearAll();
  47         mNetworkCapabilities = DEFAULT_CAPABILITIES;
  48     }
  49
  50     public NetworkCapabilities(NetworkCapabilities nc) {
  51         if (nc != null) {
  52             mNetworkCapabilities = nc.mNetworkCapabilities;
  53             mTransportTypes = nc.mTransportTypes;
  54             mLinkUpBandwidthKbps = nc.mLinkUpBandwidthKbps;
  55             mLinkDownBandwidthKbps = nc.mLinkDownBandwidthKbps;
  56             mNetworkSpecifier = nc.mNetworkSpecifier;
  57             mSignalStrength = nc.mSignalStrength;
  58         }
  59     }
  60
  61     /**
  62      * Completely clears the contents of this object, removing even the capabilities that are set
  63      * by default when the object is constructed.
  64      * @hide
  65      */
  66     public void clearAll() {
  67         mNetworkCapabilities = mTransportTypes = 0;
  68         mLinkUpBandwidthKbps = mLinkDownBandwidthKbps = 0;
  69         mNetworkSpecifier = null;
  70         mSignalStrength = SIGNAL_STRENGTH_UNSPECIFIED;
  71     }
  72
  73     /**
  74      * Represents the network's capabilities.  If any are specified they will be satisfied
  75      * by any Network that matches all of them.
  76      */
  77     private long mNetworkCapabilities;
  78
  79     /**
  80      * Indicates this is a network that has the ability to reach the
  81      * carrier's MMSC for sending and receiving MMS messages.
  82      */
  83     public static final int NET_CAPABILITY_MMS            = 0;
  84
  85     /**
  86      * Indicates this is a network that has the ability to reach the carrier's
  87      * SUPL server, used to retrieve GPS information.
  88      */
  89     public static final int NET_CAPABILITY_SUPL           = 1;
  90
  91     /**
  92      * Indicates this is a network that has the ability to reach the carrier's
  93      * DUN or tethering gateway.
  94      */
  95     public static final int NET_CAPABILITY_DUN            = 2;
  96
  97     /**
  98      * Indicates this is a network that has the ability to reach the carrier's
  99      * FOTA portal, used for over the air updates.
 100      */
 101     public static final int NET_CAPABILITY_FOTA           = 3;
 102
 103     /**
 104      * Indicates this is a network that has the ability to reach the carrier's
 105      * IMS servers, used for network registration and signaling.
 106      */
 107     public static final int NET_CAPABILITY_IMS            = 4;
 108
 109     /**
 110      * Indicates this is a network that has the ability to reach the carrier's
 111      * CBS servers, used for carrier specific services.
 112      */
 113     public static final int NET_CAPABILITY_CBS            = 5;
 114
 115     /**
 116      * Indicates this is a network that has the ability to reach a Wi-Fi direct
 117      * peer.
 118      */
 119     public static final int NET_CAPABILITY_WIFI_P2P       = 6;
 120
 121     /**
 122      * Indicates this is a network that has the ability to reach a carrier's
 123      * Initial Attach servers.
 124      */
 125     public static final int NET_CAPABILITY_IA             = 7;
 126
 127     /**
 128      * Indicates this is a network that has the ability to reach a carrier's
 129      * RCS servers, used for Rich Communication Services.
 130      */
 131     public static final int NET_CAPABILITY_RCS            = 8;
 132
 133     /**
 134      * Indicates this is a network that has the ability to reach a carrier's
 135      * XCAP servers, used for configuration and control.
 136      */
 137     public static final int NET_CAPABILITY_XCAP           = 9;
 138
 139     /**
 140      * Indicates this is a network that has the ability to reach a carrier's
 141      * Emergency IMS servers or other services, used for network signaling
 142      * during emergency calls.
 143      */
 144     public static final int NET_CAPABILITY_EIMS           = 10;
 145
 146     /**
 147      * Indicates that this network is unmetered.
 148      */
 149     public static final int NET_CAPABILITY_NOT_METERED    = 11;
 150
 151     /**
 152      * Indicates that this network should be able to reach the internet.
 153      */
 154     public static final int NET_CAPABILITY_INTERNET       = 12;
 155
 156     /**
 157      * Indicates that this network is available for general use.  If this is not set
 158      * applications should not attempt to communicate on this network.  Note that this
 159      * is simply informative and not enforcement - enforcement is handled via other means.
 160      * Set by default.
 161      */
 162     public static final int NET_CAPABILITY_NOT_RESTRICTED = 13;
 163
 164     /**
 165      * Indicates that the user has indicated implicit trust of this network.  This
 166      * generally means it's a sim-selected carrier, a plugged in ethernet, a paired
 167      * BT device or a wifi the user asked to connect to.  Untrusted networks
 168      * are probably limited to unknown wifi AP.  Set by default.
 169      */
 170     public static final int NET_CAPABILITY_TRUSTED        = 14;
 171
 172     /**
 173      * Indicates that this network is not a VPN.  This capability is set by default and should be
 174      * explicitly cleared for VPN networks.
 175      */
 176     public static final int NET_CAPABILITY_NOT_VPN        = 15;
 177
 178     /**
 179      * Indicates that connectivity on this network was successfully validated. For example, for a
 180      * network with NET_CAPABILITY_INTERNET, it means that Internet connectivity was successfully
 181      * detected.
 182      */
 183     public static final int NET_CAPABILITY_VALIDATED      = 16;
 184
 185     /**
 186      * Indicates that this network was found to have a captive portal in place last time it was
 187      * probed.
 188      */
 189     public static final int NET_CAPABILITY_CAPTIVE_PORTAL = 17;
 190
 191     /**
 192      * Indicates that this network is available for use by apps, and not a network that is being
 193      * kept up in the background to facilitate fast network switching.
 194      * @hide
 195      */
 196     public static final int NET_CAPABILITY_FOREGROUND = 18;
 197
 198     private static final int MIN_NET_CAPABILITY = NET_CAPABILITY_MMS;
 199     private static final int MAX_NET_CAPABILITY = NET_CAPABILITY_FOREGROUND;
 200
 201     /**
 202      * Network capabilities that are expected to be mutable, i.e., can change while a particular
 203      * network is connected.
 204      */
 205     private static final long MUTABLE_CAPABILITIES =
 206             // TRUSTED can change when user explicitly connects to an untrusted network in Settings.
 207             // http://b/18206275
 208             (1 << NET_CAPABILITY_TRUSTED) |
 209             (1 << NET_CAPABILITY_VALIDATED) |
 210             (1 << NET_CAPABILITY_CAPTIVE_PORTAL) |
 211             (1 << NET_CAPABILITY_FOREGROUND);
 212
 213     /**
 214      * Network capabilities that are not allowed in NetworkRequests. This exists because the
 215      * NetworkFactory / NetworkAgent model does not deal well with the situation where a
 216      * capability's presence cannot be known in advance. If such a capability is requested, then we
 217      * can get into a cycle where the NetworkFactory endlessly churns out NetworkAgents that then
 218      * get immediately torn down because they do not have the requested capability.
 219      */
 220     private static final long NON_REQUESTABLE_CAPABILITIES =
 221             MUTABLE_CAPABILITIES & ~(1 << NET_CAPABILITY_TRUSTED);
 222
 223     /**
 224      * Capabilities that are set by default when the object is constructed.
 225      */
 226     private static final long DEFAULT_CAPABILITIES =
 227             (1 << NET_CAPABILITY_NOT_RESTRICTED) |
 228             (1 << NET_CAPABILITY_TRUSTED) |
 229             (1 << NET_CAPABILITY_NOT_VPN);
 230
 231     /**
 232      * Capabilities that suggest that a network is restricted.
 233      * {@see #maybeMarkCapabilitiesRestricted}.
 234      */
 235     @VisibleForTesting
 236     /* package */ static final long RESTRICTED_CAPABILITIES =
 237             (1 << NET_CAPABILITY_CBS) |
 238             (1 << NET_CAPABILITY_DUN) |
 239             (1 << NET_CAPABILITY_EIMS) |
 240             (1 << NET_CAPABILITY_FOTA) |
 241             (1 << NET_CAPABILITY_IA) |
 242             (1 << NET_CAPABILITY_IMS) |
 243             (1 << NET_CAPABILITY_RCS) |
 244             (1 << NET_CAPABILITY_XCAP);
 245
 246     /**
 247      * Capabilities that suggest that a network is unrestricted.
 248      * {@see #maybeMarkCapabilitiesRestricted}.
 249      */
 250     @VisibleForTesting
 251     /* package */ static final long UNRESTRICTED_CAPABILITIES =
 252             (1 << NET_CAPABILITY_INTERNET) |
 253             (1 << NET_CAPABILITY_MMS) |
 254             (1 << NET_CAPABILITY_SUPL) |
 255             (1 << NET_CAPABILITY_WIFI_P2P);
 256
 257     /**
 258      * Adds the given capability to this {@code NetworkCapability} instance.
 259      * Multiple capabilities may be applied sequentially.  Note that when searching
 260      * for a network to satisfy a request, all capabilities requested must be satisfied.
 261      *
 262      * @param capability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be added.
 263      * @return This NetworkCapabilities instance, to facilitate chaining.
 264      * @hide
 265      */
 266     public NetworkCapabilities addCapability(int capability) {
 267         if (capability < MIN_NET_CAPABILITY || capability > MAX_NET_CAPABILITY) {
 268             throw new IllegalArgumentException("NetworkCapability out of range");
 269         }
 270         mNetworkCapabilities |= 1 << capability;
 271         return this;
 272     }
 273
 274     /**
 275      * Removes (if found) the given capability from this {@code NetworkCapability} instance.
 276      *
 277      * @param capability the {@code NetworkCapabilities.NET_CAPABILTIY_*} to be removed.
 278      * @return This NetworkCapabilities instance, to facilitate chaining.
 279      * @hide
 280      */
 281     public NetworkCapabilities removeCapability(int capability) {
 282         if (capability < MIN_NET_CAPABILITY || capability > MAX_NET_CAPABILITY) {
 283             throw new IllegalArgumentException("NetworkCapability out of range");
 284         }
 285         mNetworkCapabilities &= ~(1 << capability);
 286         return this;
 287     }
 288
 289     /**
 290      * Gets all the capabilities set on this {@code NetworkCapability} instance.
 291      *
 292      * @return an array of {@code NetworkCapabilities.NET_CAPABILITY_*} values
 293      *         for this instance.
 294      * @hide
 295      */
 296     public int[] getCapabilities() {
 297         return BitUtils.unpackBits(mNetworkCapabilities);
 298     }
 299
 300     /**
 301      * Tests for the presence of a capabilitity on this instance.
 302      *
 303      * @param capability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be tested for.
 304      * @return {@code true} if set on this instance.
 305      */
 306     public boolean hasCapability(int capability) {
 307         if (capability < MIN_NET_CAPABILITY || capability > MAX_NET_CAPABILITY) {
 308             return false;
 309         }
 310         return ((mNetworkCapabilities & (1 << capability)) != 0);
 311     }
 312
 313     private void combineNetCapabilities(NetworkCapabilities nc) {
 314         this.mNetworkCapabilities |= nc.mNetworkCapabilities;
 315     }
 316
 317     /**
 318      * Convenience function that returns a human-readable description of the first mutable
 319      * capability we find. Used to present an error message to apps that request mutable
 320      * capabilities.
 321      *
 322      * @hide
 323      */
 324     public String describeFirstNonRequestableCapability() {
 325         if (hasCapability(NET_CAPABILITY_VALIDATED)) return "NET_CAPABILITY_VALIDATED";
 326         if (hasCapability(NET_CAPABILITY_CAPTIVE_PORTAL)) return "NET_CAPABILITY_CAPTIVE_PORTAL";
 327         if (hasCapability(NET_CAPABILITY_FOREGROUND)) return "NET_CAPABILITY_FOREGROUND";
 328         // This cannot happen unless the preceding checks are incomplete.
 329         if ((mNetworkCapabilities & NON_REQUESTABLE_CAPABILITIES) != 0) {
 330             return "unknown non-requestable capabilities " + Long.toHexString(mNetworkCapabilities);
 331         }
 332         if (mLinkUpBandwidthKbps != 0 || mLinkDownBandwidthKbps != 0) return "link bandwidth";
 333         if (hasSignalStrength()) return "signalStrength";
 334         return null;
 335     }
 336
 337     private boolean satisfiedByNetCapabilities(NetworkCapabilities nc, boolean onlyImmutable) {
 338         long networkCapabilities = this.mNetworkCapabilities;
 339         if (onlyImmutable) {
 340             networkCapabilities = networkCapabilities & ~MUTABLE_CAPABILITIES;
 341         }
 342         return ((nc.mNetworkCapabilities & networkCapabilities) == networkCapabilities);
 343     }
 344
 345     /** @hide */
 346     public boolean equalsNetCapabilities(NetworkCapabilities nc) {
 347         return (nc.mNetworkCapabilities == this.mNetworkCapabilities);
 348     }
 349
 350     private boolean equalsNetCapabilitiesImmutable(NetworkCapabilities that) {
 351         return ((this.mNetworkCapabilities & ~MUTABLE_CAPABILITIES) ==
 352                 (that.mNetworkCapabilities & ~MUTABLE_CAPABILITIES));
 353     }
 354
 355     private boolean equalsNetCapabilitiesRequestable(NetworkCapabilities that) {
 356         return ((this.mNetworkCapabilities & ~NON_REQUESTABLE_CAPABILITIES) ==
 357                 (that.mNetworkCapabilities & ~NON_REQUESTABLE_CAPABILITIES));
 358     }
 359
 360     /**
 361      * Removes the NET_CAPABILITY_NOT_RESTRICTED capability if all the capabilities it provides are
 362      * typically provided by restricted networks.
 363      *
 364      * TODO: consider:
 365      * - Renaming it to guessRestrictedCapability and make it set the
 366      *   restricted capability bit in addition to clearing it.
 367      * @hide
 368      */
 369     public void maybeMarkCapabilitiesRestricted() {
 370         // Verify there aren't any unrestricted capabilities.  If there are we say
 371         // the whole thing is unrestricted.
 372         final boolean hasUnrestrictedCapabilities =
 373                 ((mNetworkCapabilities & UNRESTRICTED_CAPABILITIES) != 0);
 374
 375         // Must have at least some restricted capabilities.
 376         final boolean hasRestrictedCapabilities =
 377                 ((mNetworkCapabilities & RESTRICTED_CAPABILITIES) != 0);
 378
 379         if (hasRestrictedCapabilities && !hasUnrestrictedCapabilities) {
 380             removeCapability(NET_CAPABILITY_NOT_RESTRICTED);
 381         }
 382     }
 383
 384     /**
 385      * Representing the transport type.  Apps should generally not care about transport.  A
 386      * request for a fast internet connection could be satisfied by a number of different
 387      * transports.  If any are specified here it will be satisfied a Network that matches
 388      * any of them.  If a caller doesn't care about the transport it should not specify any.
 389      */
 390     private long mTransportTypes;
 391
 392     /**
 393      * Indicates this network uses a Cellular transport.
 394      */
 395     public static final int TRANSPORT_CELLULAR = 0;
 396
 397     /**
 398      * Indicates this network uses a Wi-Fi transport.
 399      */
 400     public static final int TRANSPORT_WIFI = 1;
 401
 402     /**
 403      * Indicates this network uses a Bluetooth transport.
 404      */
 405     public static final int TRANSPORT_BLUETOOTH = 2;
 406
 407     /**
 408      * Indicates this network uses an Ethernet transport.
 409      */
 410     public static final int TRANSPORT_ETHERNET = 3;
 411
 412     /**
 413      * Indicates this network uses a VPN transport.
 414      */
 415     public static final int TRANSPORT_VPN = 4;
 416
 417     /**
 418      * Indicates this network uses a Wi-Fi Aware transport.
 419      */
 420     public static final int TRANSPORT_WIFI_AWARE = 5;
 421
 422     /**
 423      * Indicates this network uses a LoWPAN transport.
 424      * @hide
 425      */
 426     public static final int TRANSPORT_LOWPAN = 6;
 427
 428     /** @hide */
 429     public static final int MIN_TRANSPORT = TRANSPORT_CELLULAR;
 430     /** @hide */
 431     public static final int MAX_TRANSPORT = TRANSPORT_LOWPAN;
 432
 433     /** @hide */
 434     public static boolean isValidTransport(int transportType) {
 435         return (MIN_TRANSPORT <= transportType) && (transportType <= MAX_TRANSPORT);
 436     }
 437
 438     private static final String[] TRANSPORT_NAMES = {
 439         "CELLULAR",
 440         "WIFI",
 441         "BLUETOOTH",
 442         "ETHERNET",
 443         "VPN",
 444         "WIFI_AWARE",
 445         "LOWPAN"
 446     };
 447
 448     /**
 449      * Adds the given transport type to this {@code NetworkCapability} instance.
 450      * Multiple transports may be applied sequentially.  Note that when searching
 451      * for a network to satisfy a request, any listed in the request will satisfy the request.
 452      * For example {@code TRANSPORT_WIFI} and {@code TRANSPORT_ETHERNET} added to a
 453      * {@code NetworkCapabilities} would cause either a Wi-Fi network or an Ethernet network
 454      * to be selected.  This is logically different than
 455      * {@code NetworkCapabilities.NET_CAPABILITY_*} listed above.
 456      *
 457      * @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be added.
 458      * @return This NetworkCapabilities instance, to facilitate chaining.
 459      * @hide
 460      */
 461     public NetworkCapabilities addTransportType(int transportType) {
 462         checkValidTransportType(transportType);
 463         mTransportTypes |= 1 << transportType;
 464         setNetworkSpecifier(mNetworkSpecifier); // used for exception checking
 465         return this;
 466     }
 467
 468     /**
 469      * Removes (if found) the given transport from this {@code NetworkCapability} instance.
 470      *
 471      * @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be removed.
 472      * @return This NetworkCapabilities instance, to facilitate chaining.
 473      * @hide
 474      */
 475     public NetworkCapabilities removeTransportType(int transportType) {
 476         checkValidTransportType(transportType);
 477         mTransportTypes &= ~(1 << transportType);
 478         setNetworkSpecifier(mNetworkSpecifier); // used for exception checking
 479         return this;
 480     }
 481
 482     /**
 483      * Gets all the transports set on this {@code NetworkCapability} instance.
 484      *
 485      * @return an array of {@code NetworkCapabilities.TRANSPORT_*} values
 486      *         for this instance.
 487      * @hide
 488      */
 489     public int[] getTransportTypes() {
 490         return BitUtils.unpackBits(mTransportTypes);
 491     }
 492
 493     /**
 494      * Tests for the presence of a transport on this instance.
 495      *
 496      * @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be tested for.
 497      * @return {@code true} if set on this instance.
 498      */
 499     public boolean hasTransport(int transportType) {
 500         return isValidTransport(transportType) && ((mTransportTypes & (1 << transportType)) != 0);
 501     }
 502
 503     private void combineTransportTypes(NetworkCapabilities nc) {
 504         this.mTransportTypes |= nc.mTransportTypes;
 505     }
 506     private boolean satisfiedByTransportTypes(NetworkCapabilities nc) {
 507         return ((this.mTransportTypes == 0) ||
 508                 ((this.mTransportTypes & nc.mTransportTypes) != 0));
 509     }
 510     /** @hide */
 511     public boolean equalsTransportTypes(NetworkCapabilities nc) {
 512         return (nc.mTransportTypes == this.mTransportTypes);
 513     }
 514
 515     /**
 516      * Passive link bandwidth.  This is a rough guide of the expected peak bandwidth
 517      * for the first hop on the given transport.  It is not measured, but may take into account
 518      * link parameters (Radio technology, allocated channels, etc).
 519      */
 520     private int mLinkUpBandwidthKbps;
 521     private int mLinkDownBandwidthKbps;
 522
 523     /**
 524      * Sets the upstream bandwidth for this network in Kbps.  This always only refers to
 525      * the estimated first hop transport bandwidth.
 526      * <p>
 527      * Note that when used to request a network, this specifies the minimum acceptable.
 528      * When received as the state of an existing network this specifies the typical
 529      * first hop bandwidth expected.  This is never measured, but rather is inferred
 530      * from technology type and other link parameters.  It could be used to differentiate
 531      * between very slow 1xRTT cellular links and other faster networks or even between
 532      * 802.11b vs 802.11AC wifi technologies.  It should not be used to differentiate between
 533      * fast backhauls and slow backhauls.
 534      *
 535      * @param upKbps the estimated first hop upstream (device to network) bandwidth.
 536      * @hide
 537      */
 538     public void setLinkUpstreamBandwidthKbps(int upKbps) {
 539         mLinkUpBandwidthKbps = upKbps;
 540     }
 541
 542     /**
 543      * Retrieves the upstream bandwidth for this network in Kbps.  This always only refers to
 544      * the estimated first hop transport bandwidth.
 545      *
 546      * @return The estimated first hop upstream (device to network) bandwidth.
 547      */
 548     public int getLinkUpstreamBandwidthKbps() {
 549         return mLinkUpBandwidthKbps;
 550     }
 551
 552     /**
 553      * Sets the downstream bandwidth for this network in Kbps.  This always only refers to
 554      * the estimated first hop transport bandwidth.
 555      * <p>
 556      * Note that when used to request a network, this specifies the minimum acceptable.
 557      * When received as the state of an existing network this specifies the typical
 558      * first hop bandwidth expected.  This is never measured, but rather is inferred
 559      * from technology type and other link parameters.  It could be used to differentiate
 560      * between very slow 1xRTT cellular links and other faster networks or even between
 561      * 802.11b vs 802.11AC wifi technologies.  It should not be used to differentiate between
 562      * fast backhauls and slow backhauls.
 563      *
 564      * @param downKbps the estimated first hop downstream (network to device) bandwidth.
 565      * @hide
 566      */
 567     public void setLinkDownstreamBandwidthKbps(int downKbps) {
 568         mLinkDownBandwidthKbps = downKbps;
 569     }
 570
 571     /**
 572      * Retrieves the downstream bandwidth for this network in Kbps.  This always only refers to
 573      * the estimated first hop transport bandwidth.
 574      *
 575      * @return The estimated first hop downstream (network to device) bandwidth.
 576      */
 577     public int getLinkDownstreamBandwidthKbps() {
 578         return mLinkDownBandwidthKbps;
 579     }
 580
 581     private void combineLinkBandwidths(NetworkCapabilities nc) {
 582         this.mLinkUpBandwidthKbps =
 583                 Math.max(this.mLinkUpBandwidthKbps, nc.mLinkUpBandwidthKbps);
 584         this.mLinkDownBandwidthKbps =
 585                 Math.max(this.mLinkDownBandwidthKbps, nc.mLinkDownBandwidthKbps);
 586     }
 587     private boolean satisfiedByLinkBandwidths(NetworkCapabilities nc) {
 588         return !(this.mLinkUpBandwidthKbps > nc.mLinkUpBandwidthKbps ||
 589                 this.mLinkDownBandwidthKbps > nc.mLinkDownBandwidthKbps);
 590     }
 591     private boolean equalsLinkBandwidths(NetworkCapabilities nc) {
 592         return (this.mLinkUpBandwidthKbps == nc.mLinkUpBandwidthKbps &&
 593                 this.mLinkDownBandwidthKbps == nc.mLinkDownBandwidthKbps);
 594     }
 595
 596     private NetworkSpecifier mNetworkSpecifier = null;
 597
 598     /**
 599      * Sets the optional bearer specific network specifier.
 600      * This has no meaning if a single transport is also not specified, so calling
 601      * this without a single transport set will generate an exception, as will
 602      * subsequently adding or removing transports after this is set.
 603      * </p>
 604      *
 605      * @param networkSpecifier A concrete, parcelable framework class that extends
 606      *                         NetworkSpecifier.
 607      * @return This NetworkCapabilities instance, to facilitate chaining.
 608      * @hide
 609      */
 610     public NetworkCapabilities setNetworkSpecifier(NetworkSpecifier networkSpecifier) {
 611         if (networkSpecifier != null && Long.bitCount(mTransportTypes) != 1) {
 612             throw new IllegalStateException("Must have a single transport specified to use " +
 613                     "setNetworkSpecifier");
 614         }
 615
 616         mNetworkSpecifier = networkSpecifier;
 617
 618         return this;
 619     }
 620
 621     /**
 622      * Gets the optional bearer specific network specifier.
 623      *
 624      * @return The optional {@link NetworkSpecifier} specifying the bearer specific network
 625      *         specifier. See {@link #setNetworkSpecifier}.
 626      * @hide
 627      */
 628     public NetworkSpecifier getNetworkSpecifier() {
 629         return mNetworkSpecifier;
 630     }
 631
 632     private void combineSpecifiers(NetworkCapabilities nc) {
 633         if (mNetworkSpecifier != null && !mNetworkSpecifier.equals(nc.mNetworkSpecifier)) {
 634             throw new IllegalStateException("Can't combine two networkSpecifiers");
 635         }
 636         setNetworkSpecifier(nc.mNetworkSpecifier);
 637     }
 638
 639     private boolean satisfiedBySpecifier(NetworkCapabilities nc) {
 640         return mNetworkSpecifier == null || mNetworkSpecifier.satisfiedBy(nc.mNetworkSpecifier)
 641                 || nc.mNetworkSpecifier instanceof MatchAllNetworkSpecifier;
 642     }
 643
 644     private boolean equalsSpecifier(NetworkCapabilities nc) {
 645         return Objects.equals(mNetworkSpecifier, nc.mNetworkSpecifier);
 646     }
 647
 648     /**
 649      * Magic value that indicates no signal strength provided. A request specifying this value is
 650      * always satisfied.
 651      *
 652      * @hide
 653      */
 654     public static final int SIGNAL_STRENGTH_UNSPECIFIED = Integer.MIN_VALUE;
 655
 656     /**
 657      * Signal strength. This is a signed integer, and higher values indicate better signal.
 658      * The exact units are bearer-dependent. For example, Wi-Fi uses RSSI.
 659      */
 660     private int mSignalStrength;
 661
 662     /**
 663      * Sets the signal strength. This is a signed integer, with higher values indicating a stronger
 664      * signal. The exact units are bearer-dependent. For example, Wi-Fi uses the same RSSI units
 665      * reported by WifiManager.
 666      * <p>
 667      * Note that when used to register a network callback, this specifies the minimum acceptable
 668      * signal strength. When received as the state of an existing network it specifies the current
 669      * value. A value of code SIGNAL_STRENGTH_UNSPECIFIED} means no value when received and has no
 670      * effect when requesting a callback.
 671      *
 672      * @param signalStrength the bearer-specific signal strength.
 673      * @hide
 674      */
 675     public void setSignalStrength(int signalStrength) {
 676         mSignalStrength = signalStrength;
 677     }
 678
 679     /**
 680      * Returns {@code true} if this object specifies a signal strength.
 681      *
 682      * @hide
 683      */
 684     public boolean hasSignalStrength() {
 685         return mSignalStrength > SIGNAL_STRENGTH_UNSPECIFIED;
 686     }
 687
 688     /**
 689      * Retrieves the signal strength.
 690      *
 691      * @return The bearer-specific signal strength.
 692      * @hide
 693      */
 694     public int getSignalStrength() {
 695         return mSignalStrength;
 696     }
 697
 698     private void combineSignalStrength(NetworkCapabilities nc) {
 699         this.mSignalStrength = Math.max(this.mSignalStrength, nc.mSignalStrength);
 700     }
 701
 702     private boolean satisfiedBySignalStrength(NetworkCapabilities nc) {
 703         return this.mSignalStrength <= nc.mSignalStrength;
 704     }
 705
 706     private boolean equalsSignalStrength(NetworkCapabilities nc) {
 707         return this.mSignalStrength == nc.mSignalStrength;
 708     }
 709
 710     /**
 711      * Combine a set of Capabilities to this one.  Useful for coming up with the complete set
 712      * @hide
 713      */
 714     public void combineCapabilities(NetworkCapabilities nc) {
 715         combineNetCapabilities(nc);
 716         combineTransportTypes(nc);
 717         combineLinkBandwidths(nc);
 718         combineSpecifiers(nc);
 719         combineSignalStrength(nc);
 720     }
 721
 722     /**
 723      * Check if our requirements are satisfied by the given {@code NetworkCapabilities}.
 724      *
 725      * @param nc the {@code NetworkCapabilities} that may or may not satisfy our requirements.
 726      * @param onlyImmutable if {@code true}, do not consider mutable requirements such as link
 727      *         bandwidth, signal strength, or validation / captive portal status.
 728      *
 729      * @hide
 730      */
 731     private boolean satisfiedByNetworkCapabilities(NetworkCapabilities nc, boolean onlyImmutable) {
 732         return (nc != null &&
 733                 satisfiedByNetCapabilities(nc, onlyImmutable) &&
 734                 satisfiedByTransportTypes(nc) &&
 735                 (onlyImmutable || satisfiedByLinkBandwidths(nc)) &&
 736                 satisfiedBySpecifier(nc) &&
 737                 (onlyImmutable || satisfiedBySignalStrength(nc)));
 738     }
 739
 740     /**
 741      * Check if our requirements are satisfied by the given {@code NetworkCapabilities}.
 742      *
 743      * @param nc the {@code NetworkCapabilities} that may or may not satisfy our requirements.
 744      *
 745      * @hide
 746      */
 747     public boolean satisfiedByNetworkCapabilities(NetworkCapabilities nc) {
 748         return satisfiedByNetworkCapabilities(nc, false);
 749     }
 750
 751     /**
 752      * Check if our immutable requirements are satisfied by the given {@code NetworkCapabilities}.
 753      *
 754      * @param nc the {@code NetworkCapabilities} that may or may not satisfy our requirements.
 755      *
 756      * @hide
 757      */
 758     public boolean satisfiedByImmutableNetworkCapabilities(NetworkCapabilities nc) {
 759         return satisfiedByNetworkCapabilities(nc, true);
 760     }
 761
 762     /**
 763      * Checks that our immutable capabilities are the same as those of the given
 764      * {@code NetworkCapabilities}.
 765      *
 766      * @hide
 767      */
 768     public boolean equalImmutableCapabilities(NetworkCapabilities nc) {
 769         if (nc == null) return false;
 770         return (equalsNetCapabilitiesImmutable(nc) &&
 771                 equalsTransportTypes(nc) &&
 772                 equalsSpecifier(nc));
 773     }
 774
 775     /**
 776      * Checks that our requestable capabilities are the same as those of the given
 777      * {@code NetworkCapabilities}.
 778      *
 779      * @hide
 780      */
 781     public boolean equalRequestableCapabilities(NetworkCapabilities nc) {
 782         if (nc == null) return false;
 783         return (equalsNetCapabilitiesRequestable(nc) &&
 784                 equalsTransportTypes(nc) &&
 785                 equalsSpecifier(nc));
 786     }
 787
 788     @Override
 789     public boolean equals(Object obj) {
 790         if (obj == null || (obj instanceof NetworkCapabilities == false)) return false;
 791         NetworkCapabilities that = (NetworkCapabilities)obj;
 792         return (equalsNetCapabilities(that) &&
 793                 equalsTransportTypes(that) &&
 794                 equalsLinkBandwidths(that) &&
 795                 equalsSignalStrength(that) &&
 796                 equalsSpecifier(that));
 797     }
 798
 799     @Override
 800     public int hashCode() {
 801         return ((int)(mNetworkCapabilities & 0xFFFFFFFF) +
 802                 ((int)(mNetworkCapabilities >> 32) * 3) +
 803                 ((int)(mTransportTypes & 0xFFFFFFFF) * 5) +
 804                 ((int)(mTransportTypes >> 32) * 7) +
 805                 (mLinkUpBandwidthKbps * 11) +
 806                 (mLinkDownBandwidthKbps * 13) +
 807                 Objects.hashCode(mNetworkSpecifier) * 17 +
 808                 (mSignalStrength * 19));
 809     }
 810
 811     @Override
 812     public int describeContents() {
 813         return 0;
 814     }
 815     @Override
 816     public void writeToParcel(Parcel dest, int flags) {
 817         dest.writeLong(mNetworkCapabilities);
 818         dest.writeLong(mTransportTypes);
 819         dest.writeInt(mLinkUpBandwidthKbps);
 820         dest.writeInt(mLinkDownBandwidthKbps);
 821         dest.writeParcelable((Parcelable) mNetworkSpecifier, flags);
 822         dest.writeInt(mSignalStrength);
 823     }
 824
 825     public static final Creator<NetworkCapabilities> CREATOR =
 826         new Creator<NetworkCapabilities>() {
 827             @Override
 828             public NetworkCapabilities createFromParcel(Parcel in) {
 829                 NetworkCapabilities netCap = new NetworkCapabilities();
 830
 831                 netCap.mNetworkCapabilities = in.readLong();
 832                 netCap.mTransportTypes = in.readLong();
 833                 netCap.mLinkUpBandwidthKbps = in.readInt();
 834                 netCap.mLinkDownBandwidthKbps = in.readInt();
 835                 netCap.mNetworkSpecifier = in.readParcelable(null);
 836                 netCap.mSignalStrength = in.readInt();
 837                 return netCap;
 838             }
 839             @Override
 840             public NetworkCapabilities[] newArray(int size) {
 841                 return new NetworkCapabilities[size];
 842             }
 843         };
 844
 845     @Override
 846     public String toString() {
 847         int[] types = getTransportTypes();
 848         String transports = (types.length > 0) ? " Transports: " + transportNamesOf(types) : "";
 849
 850         types = getCapabilities();
 851         String capabilities = (types.length > 0 ? " Capabilities: " : "");
 852         for (int i = 0; i < types.length; ) {
 853             switch (types[i]) {
 854                 case NET_CAPABILITY_MMS:            capabilities += "MMS"; break;
 855                 case NET_CAPABILITY_SUPL:           capabilities += "SUPL"; break;
 856                 case NET_CAPABILITY_DUN:            capabilities += "DUN"; break;
 857                 case NET_CAPABILITY_FOTA:           capabilities += "FOTA"; break;
 858                 case NET_CAPABILITY_IMS:            capabilities += "IMS"; break;
 859                 case NET_CAPABILITY_CBS:            capabilities += "CBS"; break;
 860                 case NET_CAPABILITY_WIFI_P2P:       capabilities += "WIFI_P2P"; break;
 861                 case NET_CAPABILITY_IA:             capabilities += "IA"; break;
 862                 case NET_CAPABILITY_RCS:            capabilities += "RCS"; break;
 863                 case NET_CAPABILITY_XCAP:           capabilities += "XCAP"; break;
 864                 case NET_CAPABILITY_EIMS:           capabilities += "EIMS"; break;
 865                 case NET_CAPABILITY_NOT_METERED:    capabilities += "NOT_METERED"; break;
 866                 case NET_CAPABILITY_INTERNET:       capabilities += "INTERNET"; break;
 867                 case NET_CAPABILITY_NOT_RESTRICTED: capabilities += "NOT_RESTRICTED"; break;
 868                 case NET_CAPABILITY_TRUSTED:        capabilities += "TRUSTED"; break;
 869                 case NET_CAPABILITY_NOT_VPN:        capabilities += "NOT_VPN"; break;
 870                 case NET_CAPABILITY_VALIDATED:      capabilities += "VALIDATED"; break;
 871                 case NET_CAPABILITY_CAPTIVE_PORTAL: capabilities += "CAPTIVE_PORTAL"; break;
 872                 case NET_CAPABILITY_FOREGROUND:     capabilities += "FOREGROUND"; break;
 873             }
 874             if (++i < types.length) capabilities += "&";
 875         }
 876
 877         String upBand = ((mLinkUpBandwidthKbps > 0) ? " LinkUpBandwidth>=" +
 878                 mLinkUpBandwidthKbps + "Kbps" : "");
 879         String dnBand = ((mLinkDownBandwidthKbps > 0) ? " LinkDnBandwidth>=" +
 880                 mLinkDownBandwidthKbps + "Kbps" : "");
 881
 882         String specifier = (mNetworkSpecifier == null ?
 883                 "" : " Specifier: <" + mNetworkSpecifier + ">");
 884
 885         String signalStrength = (hasSignalStrength() ? " SignalStrength: " + mSignalStrength : "");
 886
 887         return "[" + transports + capabilities + upBand + dnBand + specifier + signalStrength + "]";
 888     }
 889
 890     /**
 891      * @hide
 892      */
 893     public static String transportNamesOf(int[] types) {
 894         if (types == null || types.length == 0) {
 895             return "";
 896         }
 897         StringBuilder transports = new StringBuilder();
 898         for (int t : types) {
 899             transports.append("|").append(transportNameOf(t));
 900         }
 901         return transports.substring(1);
 902     }
 903
 904     /**
 905      * @hide
 906      */
 907     public static String transportNameOf(int transport) {
 908         if (!isValidTransport(transport)) {
 909             return "UNKNOWN";
 910         }
 911         return TRANSPORT_NAMES[transport];
 912     }
 913
 914     private static void checkValidTransportType(int transport) {
 915         Preconditions.checkArgument(
 916                 isValidTransport(transport), "Invalid TransportType " + transport);
 917     }
 918 }