Address tuner API review comments

Bug: 210738665
Fix: 210738665
Test: atest android.media.tv.tuner.cts
Change-Id: Id7152fdbe3dffb27ed5cdc7b87fde5a09e6cd0b2

core/api/system-current.txt

@@ -7554,7 +7554,7 @@ package android.media.tv.tuner.frontend {
     method public int getSignalStrength();
     method public int getSnr();
     method public int getSpectralInversion();
-    method @NonNull public int[] getStreamIdList();
+    method @NonNull public int[] getStreamIds();
     method public int getSymbolRate();
     method @IntRange(from=0, to=65535) public int getSystemId();
     method public int getTransmissionMode();
@@ -7601,7 +7601,7 @@ package android.media.tv.tuner.frontend {
     field public static final int FRONTEND_STATUS_TYPE_SIGNAL_STRENGTH = 6; // 0x6
     field public static final int FRONTEND_STATUS_TYPE_SNR = 1; // 0x1
     field public static final int FRONTEND_STATUS_TYPE_SPECTRAL = 10; // 0xa
-    field public static final int FRONTEND_STATUS_TYPE_STREAM_ID_LIST = 39; // 0x27
+    field public static final int FRONTEND_STATUS_TYPE_STREAM_IDS = 39; // 0x27
     field public static final int FRONTEND_STATUS_TYPE_SYMBOL_RATE = 7; // 0x7
     field public static final int FRONTEND_STATUS_TYPE_T2_SYSTEM_ID = 29; // 0x1d
     field public static final int FRONTEND_STATUS_TYPE_TRANSMISSION_MODE = 27; // 0x1b

media/java/android/media/tv/tuner/dvr/DvrPlayback.java

@@ -281,11 +281,11 @@ public class DvrPlayback implements AutoCloseable {
     /**
      * Sets the file pointer offset of the file descriptor.
      *
-     * @param pos the offset position, measured in bytes from the beginning of the file.
-     * @return the new offset position.
+     * @param position the offset position, measured in bytes from the beginning of the file.
+     * @return the new offset position. On error, {@code -1} is returned.
      */
     @BytesLong
-    public long seek(@BytesLong long pos) {
-        return nativeSeek(pos);
+    public long seek(@BytesLong long position) {
+        return nativeSeek(position);
     }
 }

media/java/android/media/tv/tuner/filter/DownloadSettings.java

@@ -47,9 +47,12 @@ public class DownloadSettings extends Settings {
     /**
      * Gets whether download ID is used.
      *
+     * If it's set to false, HAL will begin to send data before it knows downloadId and document
+     * structures.
+     *
      * <p>This query is only supported in Tuner 2.0 or higher version. Unsupported version will
-     * return {@code false}.
-     * Use {@link TunerVersionChecker#getTunerVersion()} to get the version information.
+     * return {@code false}. Use {@link TunerVersionChecker#getTunerVersion()} to get the version
+     * information.
      */
     public boolean useDownloadId() { return mUseDownloadId; }
 
@@ -78,6 +81,9 @@ public class DownloadSettings extends Settings {
         /**
          * Sets whether download ID is used or not.
          *
+         * If it's set to false, HAL will begin to send data before it knows downloadId and document
+         * structures.
+         *
          * <p>This configuration is only supported in Tuner 2.0 or higher version. Unsupported
          * version will cause no-op. Use {@link TunerVersionChecker#getTunerVersion()} to get the
          * version information.

media/java/android/media/tv/tuner/filter/SectionEvent.java

@@ -16,6 +16,7 @@
 
 package android.media.tv.tuner.filter;
 
+import android.annotation.BytesLong;
 import android.annotation.SystemApi;
 
 /**
@@ -69,5 +70,11 @@ public class SectionEvent extends FilterEvent {
         return (int) getDataLengthLong();
     }
 
-    public long getDataLengthLong() { return mDataLength; }
+    /**
+     * Gets data size in bytes of filtered data.
+     */
+    @BytesLong
+    public long getDataLengthLong() {
+        return mDataLength;
+    }
 }

media/java/android/media/tv/tuner/frontend/FrontendStatus.java

@@ -53,7 +53,7 @@ public class FrontendStatus {
             FRONTEND_STATUS_TYPE_MODULATIONS_EXT, FRONTEND_STATUS_TYPE_ROLL_OFF,
             FRONTEND_STATUS_TYPE_IS_MISO_ENABLED, FRONTEND_STATUS_TYPE_IS_LINEAR,
             FRONTEND_STATUS_TYPE_IS_SHORT_FRAMES_ENABLED, FRONTEND_STATUS_TYPE_ISDBT_MODE,
-            FRONTEND_STATUS_TYPE_ISDBT_PARTIAL_RECEPTION_FLAG, FRONTEND_STATUS_TYPE_STREAM_ID_LIST})
+            FRONTEND_STATUS_TYPE_ISDBT_PARTIAL_RECEPTION_FLAG, FRONTEND_STATUS_TYPE_STREAM_IDS})
     @Retention(RetentionPolicy.SOURCE)
     public @interface FrontendStatusType {}
 
@@ -255,9 +255,9 @@ public class FrontendStatus {
             android.hardware.tv.tuner.FrontendStatusType.ISDBT_PARTIAL_RECEPTION_FLAG;
 
     /**
-     * Stream ID list included in a transponder.
+     * Stream IDs included in a transponder.
      */
-    public static final int FRONTEND_STATUS_TYPE_STREAM_ID_LIST =
+    public static final int FRONTEND_STATUS_TYPE_STREAM_IDS =
             android.hardware.tv.tuner.FrontendStatusType.STREAM_ID_LIST;
 
     /** @hide */
@@ -1008,19 +1008,19 @@ public class FrontendStatus {
     }
 
     /**
-     * Gets stream id list included in a transponder.
+     * Gets stream ids included in a transponder.
      *
      * <p>This query is only supported by Tuner HAL 2.0 or higher. Unsupported version or if HAL
-     * doesn't return stream id list status will throw IllegalStateException. Use
+     * doesn't return stream ids will throw IllegalStateException. Use
      * {@link TunerVersionChecker#getTunerVersion()} to check the version.
      */
     @SuppressLint("ArrayReturn")
     @NonNull
-    public int[] getStreamIdList() {
+    public int[] getStreamIds() {
         TunerVersionChecker.checkHigherOrEqualVersionTo(
-                TunerVersionChecker.TUNER_VERSION_2_0, "stream id list status");
+                TunerVersionChecker.TUNER_VERSION_2_0, "stream ids status");
         if (mStreamIds == null) {
-            throw new IllegalStateException("stream id list status is empty");
+            throw new IllegalStateException("stream ids are empty");
         }
         return mStreamIds;
     }