IpSecTransformState: Rename API methods and improve docs
Rename API methods and update API docs as per API
council feedbacks
Bug: 316603231
Test: make update-api && make
Change-Id: Ibb1f58792d2e40ef1084c2b532e999a516a87b37
diff --git a/framework-t/api/current.txt b/framework-t/api/current.txt
index 7cd3d4f..9ae0cf7 100644
--- a/framework-t/api/current.txt
+++ b/framework-t/api/current.txt
@@ -127,7 +127,7 @@
public final class IpSecTransform implements java.lang.AutoCloseable {
method public void close();
- method @FlaggedApi("com.android.net.flags.ipsec_transform_state") public void getIpSecTransformState(@NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<android.net.IpSecTransformState,java.lang.RuntimeException>);
+ method @FlaggedApi("com.android.net.flags.ipsec_transform_state") public void requestIpSecTransformState(@NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<android.net.IpSecTransformState,java.lang.RuntimeException>);
}
public static class IpSecTransform.Builder {
@@ -145,7 +145,7 @@
method public long getPacketCount();
method @NonNull public byte[] getReplayBitmap();
method public long getRxHighestSequenceNumber();
- method public long getTimestamp();
+ method public long getTimestampMillis();
method public long getTxHighestSequenceNumber();
method public void writeToParcel(@NonNull android.os.Parcel, int);
field @NonNull public static final android.os.Parcelable.Creator<android.net.IpSecTransformState> CREATOR;
@@ -158,7 +158,7 @@
method @NonNull public android.net.IpSecTransformState.Builder setPacketCount(long);
method @NonNull public android.net.IpSecTransformState.Builder setReplayBitmap(@NonNull byte[]);
method @NonNull public android.net.IpSecTransformState.Builder setRxHighestSequenceNumber(long);
- method @NonNull public android.net.IpSecTransformState.Builder setTimestamp(long);
+ method @NonNull public android.net.IpSecTransformState.Builder setTimestampMillis(long);
method @NonNull public android.net.IpSecTransformState.Builder setTxHighestSequenceNumber(long);
}
diff --git a/framework-t/src/android/net/IpSecTransform.java b/framework-t/src/android/net/IpSecTransform.java
index 246a2dd..4e10a96 100644
--- a/framework-t/src/android/net/IpSecTransform.java
+++ b/framework-t/src/android/net/IpSecTransform.java
@@ -215,7 +215,7 @@
* @see IpSecTransformState
*/
@FlaggedApi(IPSEC_TRANSFORM_STATE)
- public void getIpSecTransformState(
+ public void requestIpSecTransformState(
@CallbackExecutor @NonNull Executor executor,
@NonNull OutcomeReceiver<IpSecTransformState, RuntimeException> callback) {
Objects.requireNonNull(executor);
diff --git a/framework-t/src/android/net/IpSecTransformState.java b/framework-t/src/android/net/IpSecTransformState.java
index b575dd5..5b80ae2 100644
--- a/framework-t/src/android/net/IpSecTransformState.java
+++ b/framework-t/src/android/net/IpSecTransformState.java
@@ -23,6 +23,7 @@
import android.annotation.NonNull;
import android.os.Parcel;
import android.os.Parcelable;
+import android.os.SystemClock;
import com.android.internal.annotations.VisibleForTesting;
import com.android.net.module.util.HexDump;
@@ -40,7 +41,7 @@
*/
@FlaggedApi(IPSEC_TRANSFORM_STATE)
public final class IpSecTransformState implements Parcelable {
- private final long mTimeStamp;
+ private final long mTimestamp;
private final long mTxHighestSequenceNumber;
private final long mRxHighestSequenceNumber;
private final long mPacketCount;
@@ -54,7 +55,7 @@
long packetCount,
long byteCount,
byte[] replayBitmap) {
- mTimeStamp = timestamp;
+ mTimestamp = timestamp;
mTxHighestSequenceNumber = txHighestSequenceNumber;
mRxHighestSequenceNumber = rxHighestSequenceNumber;
mPacketCount = packetCount;
@@ -78,7 +79,7 @@
@VisibleForTesting(visibility = Visibility.PRIVATE)
public IpSecTransformState(@NonNull Parcel in) {
Objects.requireNonNull(in, "The input PersistableBundle is null");
- mTimeStamp = in.readLong();
+ mTimestamp = in.readLong();
mTxHighestSequenceNumber = in.readLong();
mRxHighestSequenceNumber = in.readLong();
mPacketCount = in.readLong();
@@ -97,7 +98,7 @@
@Override
public void writeToParcel(@NonNull Parcel out, int flags) {
- out.writeLong(mTimeStamp);
+ out.writeLong(mTimestamp);
out.writeLong(mTxHighestSequenceNumber);
out.writeLong(mRxHighestSequenceNumber);
out.writeLong(mPacketCount);
@@ -120,16 +121,17 @@
};
/**
- * Retrieve the epoch timestamp (milliseconds) for when this state was created
+ * Retrieve the timestamp (milliseconds) when this state was created, as per {@link
+ * SystemClock#elapsedRealtime}
*
- * @see Builder#setTimestamp(long)
+ * @see Builder#setTimestampMillis(long)
*/
- public long getTimestamp() {
- return mTimeStamp;
+ public long getTimestampMillis() {
+ return mTimestamp;
}
/**
- * Retrieve the highest sequence number sent so far
+ * Retrieve the highest sequence number sent so far as an unsigned long
*
* @see Builder#setTxHighestSequenceNumber(long)
*/
@@ -138,7 +140,7 @@
}
/**
- * Retrieve the highest sequence number received so far
+ * Retrieve the highest sequence number received so far as an unsigned long
*
* @see Builder#setRxHighestSequenceNumber(long)
*/
@@ -147,7 +149,10 @@
}
/**
- * Retrieve the number of packets received AND sent so far
+ * Retrieve the number of packets processed so far as an unsigned long.
+ *
+ * <p>The packet count direction (inbound or outbound) aligns with the direction in which the
+ * IpSecTransform is applied to.
*
* @see Builder#setPacketCount(long)
*/
@@ -156,7 +161,10 @@
}
/**
- * Retrieve the number of bytes received AND sent so far
+ * Retrieve the number of bytes processed so far as an unsigned long
+ *
+ * <p>The byte count direction (inbound or outbound) aligns with the direction in which the
+ * IpSecTransform is applied to.
*
* @see Builder#setByteCount(long)
*/
@@ -183,10 +191,15 @@
return mReplayBitmap.clone();
}
- /** Builder class for testing purposes */
+ /**
+ * Builder class for testing purposes
+ *
+ * <p>Except for testing, IPsec callers normally do not instantiate {@link IpSecTransformState}
+ * themselves but instead get a reference via {@link IpSecTransformState}
+ */
@FlaggedApi(IPSEC_TRANSFORM_STATE)
public static final class Builder {
- private long mTimeStamp;
+ private long mTimestamp;
private long mTxHighestSequenceNumber;
private long mRxHighestSequenceNumber;
private long mPacketCount;
@@ -194,22 +207,22 @@
private byte[] mReplayBitmap;
public Builder() {
- mTimeStamp = System.currentTimeMillis();
+ mTimestamp = SystemClock.elapsedRealtime();
}
/**
- * Set the epoch timestamp (milliseconds) for when this state was created
+ * Set the timestamp (milliseconds) when this state was created
*
- * @see IpSecTransformState#getTimestamp()
+ * @see IpSecTransformState#getTimestampMillis()
*/
@NonNull
- public Builder setTimestamp(long timeStamp) {
- mTimeStamp = timeStamp;
+ public Builder setTimestampMillis(long timestamp) {
+ mTimestamp = timestamp;
return this;
}
/**
- * Set the highest sequence number sent so far
+ * Set the highest sequence number sent so far as an unsigned long
*
* @see IpSecTransformState#getTxHighestSequenceNumber()
*/
@@ -220,7 +233,7 @@
}
/**
- * Set the highest sequence number received so far
+ * Set the highest sequence number received so far as an unsigned long
*
* @see IpSecTransformState#getRxHighestSequenceNumber()
*/
@@ -231,7 +244,7 @@
}
/**
- * Set the number of packets received AND sent so far
+ * Set the number of packets processed so far as an unsigned long
*
* @see IpSecTransformState#getPacketCount()
*/
@@ -242,7 +255,7 @@
}
/**
- * Set the number of bytes received AND sent so far
+ * Set the number of bytes processed so far as an unsigned long
*
* @see IpSecTransformState#getByteCount()
*/
@@ -271,7 +284,7 @@
@NonNull
public IpSecTransformState build() {
return new IpSecTransformState(
- mTimeStamp,
+ mTimestamp,
mTxHighestSequenceNumber,
mRxHighestSequenceNumber,
mPacketCount,