Clarify docs, sanity check roaming state.

Update public docs to hide the fact that NetworkCapabilities is only
used inside NetworkRequest as an implementation detail.

Take up less room on the wire when passing NetworkCapabilities around
via NetworkRequest.

Sanity check that the roaming state between NetworkInfo and
NetworkCapabilities is in agreement.

Test: bit FrameworksNetTests:android.net.,com.android.server.net.,com.android.server.connectivity.,com.android.server.ConnectivityServiceTest
Bug: 67040695
Change-Id: I982b4c3c41a140934bbad3b8ca8f12dc3814e86c

core/java/android/net/NetworkCapabilities.java

@@ -31,16 +31,10 @@ import java.util.Objects;
 import java.util.StringJoiner;
 
 /**
- * Representation of the capabilities of a network. This object serves two
- * purposes:
- * <ul>
- * <li>An expression of the current capabilities of an active network, typically
- * expressed through
+ * Representation of the capabilities of an active network. Instances are
+ * typically obtained through
  * {@link NetworkCallback#onCapabilitiesChanged(Network, NetworkCapabilities)}
  * or {@link ConnectivityManager#getNetworkCapabilities(Network)}.
- * <li>An expression of the future capabilities of a desired network, typically
- * expressed through {@link NetworkRequest}.
- * </ul>
  * <p>
  * This replaces the old {@link ConnectivityManager#TYPE_MOBILE} method of
  * network selection. Rather than indicate a need for Wi-Fi because an
@@ -79,7 +73,7 @@ public final class NetworkCapabilities implements Parcelable {
      */
     public void clearAll() {
         mNetworkCapabilities = mTransportTypes = 0;
-        mLinkUpBandwidthKbps = mLinkDownBandwidthKbps = 0;
+        mLinkUpBandwidthKbps = mLinkDownBandwidthKbps = LINK_BANDWIDTH_UNSPECIFIED;
         mNetworkSpecifier = null;
         mSignalStrength = SIGNAL_STRENGTH_UNSPECIFIED;
     }
@@ -359,6 +353,7 @@ public final class NetworkCapabilities implements Parcelable {
 
     /**
      * Sets all the capabilities set on this {@code NetworkCapability} instance.
+     * This overwrites any existing capabilities.
      *
      * @hide
      */
@@ -582,6 +577,7 @@ public final class NetworkCapabilities implements Parcelable {
 
     /**
      * Sets all the transports set on this {@code NetworkCapability} instance.
+     * This overwrites any existing transports.
      *
      * @hide
      */
@@ -780,7 +776,7 @@ public final class NetworkCapabilities implements Parcelable {
      * 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.
      */
-    private int mSignalStrength;
+    private int mSignalStrength = SIGNAL_STRENGTH_UNSPECIFIED;
 
     /**
      * Sets the signal strength. This is a signed integer, with higher values indicating a stronger

core/java/android/net/NetworkRequest.java

@@ -16,6 +16,7 @@
 
 package android.net;
 
+import android.annotation.NonNull;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.text.TextUtils;
@@ -32,7 +33,7 @@ public class NetworkRequest implements Parcelable {
      * The {@link NetworkCapabilities} that define this request.
      * @hide
      */
-    public final NetworkCapabilities networkCapabilities;
+    public final @NonNull NetworkCapabilities networkCapabilities;
 
     /**
      * Identifies the request.  NetworkRequests should only be constructed by
@@ -307,7 +308,7 @@ public class NetworkRequest implements Parcelable {
         return 0;
     }
     public void writeToParcel(Parcel dest, int flags) {
-        dest.writeParcelable(networkCapabilities, flags);
+        networkCapabilities.writeToParcel(dest, flags);
         dest.writeInt(legacyType);
         dest.writeInt(requestId);
         dest.writeString(type.name());
@@ -315,7 +316,7 @@ public class NetworkRequest implements Parcelable {
     public static final Creator<NetworkRequest> CREATOR =
         new Creator<NetworkRequest>() {
             public NetworkRequest createFromParcel(Parcel in) {
-                NetworkCapabilities nc = (NetworkCapabilities)in.readParcelable(null);
+                NetworkCapabilities nc = NetworkCapabilities.CREATOR.createFromParcel(in);
                 int legacyType = in.readInt();
                 int requestId = in.readInt();
                 Type type = Type.valueOf(in.readString());  // IllegalArgumentException if invalid.

core/java/android/net/NetworkState.java

@@ -18,6 +18,7 @@ package android.net;
 
 import android.os.Parcel;
 import android.os.Parcelable;
+import android.util.Slog;
 
 /**
  * Snapshot of network state.
@@ -43,6 +44,16 @@ public class NetworkState implements Parcelable {
         this.network = network;
         this.subscriberId = subscriberId;
         this.networkId = networkId;
+
+        // This object is an atomic view of a network, so the various components
+        // should always agree on roaming state.
+        if (networkInfo != null && networkCapabilities != null) {
+            if (networkInfo.isRoaming() == networkCapabilities
+                    .hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_ROAMING)) {
+                Slog.wtf("NetworkState", "Roaming state disagreement between " + networkInfo
+                        + " and " + networkCapabilities);
+            }
+        }
     }
 
     public NetworkState(Parcel in) {