Improve documentation of L2capNetworkSpecifier
Addresses comments in aosp/3429160.
Test: TH
Change-Id: I05588b7f0a3d22beae4ddb2237b9a6eebdd00d03
diff --git a/framework/src/android/net/L2capNetworkSpecifier.java b/framework/src/android/net/L2capNetworkSpecifier.java
index 82ad05d..0d46a3e 100644
--- a/framework/src/android/net/L2capNetworkSpecifier.java
+++ b/framework/src/android/net/L2capNetworkSpecifier.java
@@ -20,6 +20,7 @@
import android.annotation.IntDef;
import android.annotation.NonNull;
import android.annotation.Nullable;
+import android.os.Build;
import android.os.Parcel;
import android.os.Parcelable;
@@ -33,31 +34,43 @@
* A {@link NetworkSpecifier} used to identify an L2CAP network.
*
* An L2CAP network is not symmetrical, meaning there exists both a server (Bluetooth peripheral)
- * and a client (Bluetooth central) node. This specifier contains information required to request or
- * reserve an L2CAP network.
+ * and a client (Bluetooth central) node. This specifier contains the information required to
+ * request a client L2CAP network using {@link ConnectivityManager#requestNetwork} while specifying
+ * the remote MAC address, and Protocol/Service Multiplexer (PSM). It can also contain information
+ * allocated by the system when reserving a server network using {@link
+ * ConnectivityManager#reserveNetwork} such as the Protocol/Service Multiplexer (PSM). In both
+ * cases, the header compression option must be specified.
*
- * An L2CAP server network allocates a PSM to be advertised to the client. Therefore, the server
- * network must always be reserved using {@link ConnectivityManager#reserveNetwork}. The subsequent
- * {@link ConnectivityManager.NetworkCallback#onReserved(NetworkCapabilities)} includes information
- * (i.e. the PSM) for the server to advertise to the client.
- * Under the hood, an L2CAP server network is represented by a {@link
- * android.bluetooth.BluetoothServerSocket} which can, in theory, accept many connections. However,
- * before Android 15 Bluetooth APIs do not expose the channel ID, so these connections are
- * indistinguishable. In practice, this means that network matching semantics in {@link
- * ConnectivityService} will tear down all but the first connection.
+ * An L2CAP server network allocates a Protocol/Service Multiplexer (PSM) to be advertised to the
+ * client. A new server network must always be reserved using {@code
+ * ConnectivityManager#reserveNetwork}. The subsequent {@link
+ * ConnectivityManager.NetworkCallback#onReserved(NetworkCapabilities)} callback includes an {@code
+ * L2CapNetworkSpecifier}. The {@link getPsm()} method will return the Protocol/Service Multiplexer
+ * (PSM) of the reserved network so that the server can advertise it to the client and the client
+ * can connect.
+ * An L2CAP server network is backed by a {@link android.bluetooth.BluetoothServerSocket} which can,
+ * in theory, accept many connections. However, before SDK version {@link
+ * Build.VERSION_CODES.VANILLA_ICE_CREAM} Bluetooth APIs do not expose the channel ID, so these
+ * connections are indistinguishable. In practice, this means that the network matching semantics in
+ * ConnectivityService will tear down all but the first connection.
*
- * The L2cap client network can be connected using {@link ConnectivityManager#requestNetwork}
- * including passing in the relevant information (i.e. PSM and destination MAC address) using the
- * {@link L2capNetworkSpecifier}.
- *
+ * When the connection between client and server completes, a {@link Network} whose capabilities
+ * satisfy this {@code L2capNetworkSpecifier} will connect and the usual callbacks, such as {@link
+ * NetworkCallback#onAvailable}, will be called on the callback object passed to {@code
+ * ConnectivityManager#reserveNetwork} or {@code ConnectivityManager#requestNetwork}.
*/
@FlaggedApi(Flags.FLAG_IPV6_OVER_BLE)
public final class L2capNetworkSpecifier extends NetworkSpecifier implements Parcelable {
- /** Accept any role. */
+ /**
+ * Match any role.
+ *
+ * This role is only meaningful in {@link NetworkRequest}s. Specifiers for actual L2CAP
+ * networks never have this role set.
+ */
public static final int ROLE_ANY = 0;
- /** Specifier describes a client network. */
+ /** Specifier describes a client network, i.e., the device is the Bluetooth central. */
public static final int ROLE_CLIENT = 1;
- /** Specifier describes a server network. */
+ /** Specifier describes a server network, i.e., the device is the Bluetooth peripheral. */
public static final int ROLE_SERVER = 2;
/** @hide */
@@ -72,7 +85,12 @@
@Role
private final int mRole;
- /** Accept any form of header compression. */
+ /**
+ * Accept any form of header compression.
+ *
+ * This option is only meaningful in {@link NetworkRequest}s. Specifiers for actual L2CAP
+ * networks never have this option set.
+ */
public static final int HEADER_COMPRESSION_ANY = 0;
/** Do not compress packets on this network. */
public static final int HEADER_COMPRESSION_NONE = 1;
@@ -91,16 +109,19 @@
@HeaderCompression
private final int mHeaderCompression;
- /**
- * The MAC address of the remote.
- */
+ /** The MAC address of the remote. */
@Nullable
private final MacAddress mRemoteAddress;
- /** Match any PSM. */
+ /**
+ * Match any Protocol/Service Multiplexer (PSM).
+ *
+ * This PSM value is only meaningful in {@link NetworkRequest}s. Specifiers for actual L2CAP
+ * networks never have this value set.
+ */
public static final int PSM_ANY = -1;
- /** The Bluetooth L2CAP Protocol Service Multiplexer (PSM). */
+ /** The Bluetooth L2CAP Protocol/Service Multiplexer (PSM). */
private final int mPsm;
private L2capNetworkSpecifier(Parcel in) {
@@ -131,12 +152,19 @@
return mHeaderCompression;
}
- /** Returns the remote MAC address for this network to connect to. */
+ /**
+ * Returns the remote MAC address for this network to connect to.
+ *
+ * The remote address is only meaningful for networks that have ROLE_CLIENT.
+ *
+ * When receiving this {@link L2capNetworkSpecifier} from Connectivity APIs such as a {@link
+ * ConnectivityManager.NetworkCallback}, the MAC address is redacted.
+ */
public @Nullable MacAddress getRemoteAddress() {
return mRemoteAddress;
}
- /** Returns the PSM for this network to connect to. */
+ /** Returns the Protocol/Service Multiplexer (PSM) for this network to connect to. */
public int getPsm() {
return mPsm;
}
@@ -144,9 +172,9 @@
/** A builder class for L2capNetworkSpecifier. */
public static final class Builder {
@Role
- private int mRole;
+ private int mRole = ROLE_ANY;
@HeaderCompression
- private int mHeaderCompression;
+ private int mHeaderCompression = HEADER_COMPRESSION_ANY;
@Nullable
private MacAddress mRemoteAddress;
private int mPsm = PSM_ANY;
@@ -154,6 +182,8 @@
/**
* Set the role to use for this network.
*
+ * If not set, defaults to {@link ROLE_ANY}.
+ *
* @param role the role to use.
*/
@NonNull
@@ -165,6 +195,10 @@
/**
* Set the header compression mechanism to use for this network.
*
+ * If not set, defaults to {@link HEADER_COMPRESSION_ANY}. This option must be specified
+ * (i.e. must not be set to {@link HEADER_COMPRESSION_ANY}) when requesting or reserving a
+ * new network.
+ *
* @param headerCompression the header compression mechanism to use.
*/
@NonNull
@@ -176,7 +210,7 @@
/**
* Set the remote address for the client to connect to.
*
- * Only valid for client networks. A null MacAddress matches *any* MacAddress.
+ * Only valid for client networks. If not set, the specifier matches any MAC address.
*
* @param remoteAddress the MAC address to connect to, or null to match any MAC address.
*/
@@ -187,11 +221,11 @@
}
/**
- * Set the PSM for the client to connect to.
+ * Set the Protocol/Service Multiplexer (PSM) for the client to connect to.
*
- * Can only be configured on client networks.
+ * If not set, defaults to {@link PSM_ANY}.
*
- * @param psm the Protocol Service Multiplexer (PSM) to connect to.
+ * @param psm the Protocol/Service Multiplexer (PSM) to connect to.
*/
@NonNull
public Builder setPsm(int psm) {