Merge "Unhide filter event part 1"

api/system-current.txt

@@ -4574,6 +4574,36 @@ package android.media.tv.tuner {
   public class Tuner.Descrambler {
   }
 
+  public class Tuner.Filter {
+  }
+
+  public static interface Tuner.FilterCallback {
+    method public void onFilterEvent(@NonNull android.media.tv.tuner.Tuner.Filter, @NonNull android.media.tv.tuner.filter.FilterEvent[]);
+    method public void onFilterStatusChanged(@NonNull android.media.tv.tuner.Tuner.Filter, int);
+  }
+
+  public final class TunerConstants {
+    field public static final int FILTER_STATUS_DATA_READY = 1; // 0x1
+    field public static final int FILTER_STATUS_HIGH_WATER = 4; // 0x4
+    field public static final int FILTER_STATUS_LOW_WATER = 2; // 0x2
+    field public static final int FILTER_STATUS_OVERFLOW = 8; // 0x8
+  }
+
+}
+
+package android.media.tv.tuner.filter {
+
+  public abstract class FilterEvent {
+    ctor public FilterEvent();
+  }
+
+  public class SectionEvent extends android.media.tv.tuner.filter.FilterEvent {
+    method public int getDataLength();
+    method public int getSectionNumber();
+    method public int getTableId();
+    method public int getVersion();
+  }
+
 }
 
 package android.metrics {

media/java/android/media/tv/tuner/Tuner.java

@@ -23,6 +23,7 @@ import android.annotation.SystemApi;
 import android.content.Context;
 import android.media.tv.tuner.FilterConfiguration.Settings;
 import android.media.tv.tuner.TunerConstants.DemuxPidType;
+import android.media.tv.tuner.TunerConstants.FilterStatus;
 import android.media.tv.tuner.TunerConstants.FilterSubtype;
 import android.media.tv.tuner.TunerConstants.FilterType;
 import android.media.tv.tuner.TunerConstants.FrontendScanType;
@@ -170,19 +171,23 @@ public final class Tuner implements AutoCloseable  {
     }
 
     /**
-     * Frontend Callback.
-     *
-     * @hide
+     * Callback interface for receiving information from the corresponding filters.
      */
     public interface FilterCallback {
         /**
          * Invoked when there are filter events.
+         *
+         * @param filter the corresponding filter which sent the events.
+         * @param events the filter events sent from the filter.
          */
-        void onFilterEvent(FilterEvent[] events);
+        void onFilterEvent(@NonNull Filter filter, @NonNull FilterEvent[] events);
         /**
          * Invoked when filter status changed.
+         *
+         * @param filter the corresponding filter whose status is changed.
+         * @param status the new status of the filter.
          */
-        void onFilterStatus(int status);
+        void onFilterStatusChanged(@NonNull Filter filter, @FilterStatus int status);
     }
 
     /**
@@ -228,7 +233,7 @@ public final class Tuner implements AutoCloseable  {
                 case MSG_ON_FILTER_STATUS: {
                     Filter filter = (Filter) msg.obj;
                     if (filter.mCallback != null) {
-                        filter.mCallback.onFilterStatus(msg.arg1);
+                        filter.mCallback.onFilterStatusChanged(filter, msg.arg1);
                     }
                     break;
                 }
@@ -463,7 +468,11 @@ public final class Tuner implements AutoCloseable  {
         }
     }
 
-    /** @hide */
+    /**
+     * Tuner data filter.
+     *
+     * <p> This class is used to filter wanted data according to the filter's configuration.
+     */
     public class Filter {
         private long mNativeContext;
         private FilterCallback mCallback;
@@ -495,6 +504,7 @@ public final class Tuner implements AutoCloseable  {
          *
          * @param settings the settings of the filter.
          * @return result status of the operation.
+         * @hide
          */
         public int configure(FilterConfiguration settings) {
             int subType = -1;
@@ -509,6 +519,7 @@ public final class Tuner implements AutoCloseable  {
          * Gets the filter Id.
          *
          * @return the hardware resource Id for the filter.
+         * @hide
          */
         public int getId() {
             return nativeGetId();
@@ -525,6 +536,7 @@ public final class Tuner implements AutoCloseable  {
          * @param source the filter instance which provides data input. Switch to
          * use demux as data source if the filter instance is NULL.
          * @return result status of the operation.
+         * @hide
          */
         public int setDataSource(@Nullable Filter source) {
             return nativeSetDataSource(source);
@@ -534,6 +546,7 @@ public final class Tuner implements AutoCloseable  {
          * Starts the filter.
          *
          * @return result status of the operation.
+         * @hide
          */
         public int start() {
             return nativeStartFilter();
@@ -544,6 +557,7 @@ public final class Tuner implements AutoCloseable  {
          * Stops the filter.
          *
          * @return result status of the operation.
+         * @hide
          */
         public int stop() {
             return nativeStopFilter();
@@ -553,11 +567,13 @@ public final class Tuner implements AutoCloseable  {
          * Flushes the filter.
          *
          * @return result status of the operation.
+         * @hide
          */
         public int flush() {
             return nativeFlushFilter();
         }
 
+        /** @hide */
         public int read(@NonNull byte[] buffer, int offset, int size) {
             size = Math.min(size, buffer.length - offset);
             return nativeRead(buffer, offset, size);
@@ -567,6 +583,7 @@ public final class Tuner implements AutoCloseable  {
          * Release the Filter instance.
          *
          * @return result status of the operation.
+         * @hide
          */
         public int close() {
             return nativeClose();

media/java/android/media/tv/tuner/TunerConstants.java

@@ -18,14 +18,18 @@ package android.media.tv.tuner;
 
 import android.annotation.IntDef;
 import android.annotation.LongDef;
+import android.annotation.SystemApi;
 import android.hardware.tv.tuner.V1_0.Constants;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
+ * Constants for tuner framework.
+ *
  * @hide
  */
+@SystemApi
 public final class TunerConstants {
     /** @hide */
     public static final int INVALID_TS_PID = Constants.Constant.INVALID_TS_PID;
@@ -181,6 +185,37 @@ public final class TunerConstants {
     /** @hide */
     public static final int FILTER_SUBTYPE_PTP = 16;
 
+    /** @hide */
+    @IntDef({FILTER_STATUS_DATA_READY, FILTER_STATUS_LOW_WATER, FILTER_STATUS_HIGH_WATER,
+            FILTER_STATUS_OVERFLOW})
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface FilterStatus {}
+
+    /**
+     * The status of a filter that the data in the filter buffer is ready to be read.
+     */
+    public static final int FILTER_STATUS_DATA_READY = Constants.DemuxFilterStatus.DATA_READY;
+    /**
+     * The status of a filter that the amount of available data in the filter buffer is at low
+     * level.
+     *
+     * The value is set to 25 percent of the buffer size by default. It can be changed when
+     * configuring the filter.
+     */
+    public static final int FILTER_STATUS_LOW_WATER = Constants.DemuxFilterStatus.LOW_WATER;
+    /**
+     * The status of a filter that the amount of available data in the filter buffer is at high
+     * level.
+     * The value is set to 75 percent of the buffer size by default. It can be changed when
+     * configuring the filter.
+     */
+    public static final int FILTER_STATUS_HIGH_WATER = Constants.DemuxFilterStatus.HIGH_WATER;
+    /**
+     * The status of a filter that the filter buffer is full and newly filtered data is being
+     * discarded.
+     */
+    public static final int FILTER_STATUS_OVERFLOW = Constants.DemuxFilterStatus.OVERFLOW;
+
     /** @hide */
     @IntDef({FRONTEND_SCAN_UNDEFINED, FRONTEND_SCAN_AUTO, FRONTEND_SCAN_BLIND})
     @Retention(RetentionPolicy.SOURCE)

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

@@ -16,10 +16,13 @@
 
 package android.media.tv.tuner.filter;
 
+import android.annotation.SystemApi;
+
 /**
- * Demux filter event.
+ * An entity class that is passed to the filter callbacks.
  *
  * @hide
  */
+@SystemApi
 public abstract class FilterEvent {
 }

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

@@ -16,14 +16,54 @@
 
 package android.media.tv.tuner.filter;
 
+import android.annotation.SystemApi;
+import android.media.tv.tuner.Tuner.Filter;
+
 /**
- * Section event.
+ * Filter event sent from {@link Filter} objects with section type.
+ *
  * @hide
  */
-public class SectionEvent {
-    // TODO: add constructor and getters
-    private int mTableId;
-    private int mVersion;
-    private int mSectionNum;
-    private int mDataLength;
+@SystemApi
+public class SectionEvent extends FilterEvent {
+    private final int mTableId;
+    private final int mVersion;
+    private final int mSectionNum;
+    private final int mDataLength;
+
+    // This constructor is used by JNI code only
+    private SectionEvent(int tableId, int version, int sectionNum, int dataLength) {
+        mTableId = tableId;
+        mVersion = version;
+        mSectionNum = sectionNum;
+        mDataLength = dataLength;
+    }
+
+    /**
+     * Gets table ID of filtered data.
+     */
+    public int getTableId() {
+        return mTableId;
+    }
+
+    /**
+     * Gets version number of filtered data.
+     */
+    public int getVersion() {
+        return mVersion;
+    }
+
+    /**
+     * Gets section number of filtered data.
+     */
+    public int getSectionNumber() {
+        return mSectionNum;
+    }
+
+    /**
+     * Gets data size in bytes of filtered data.
+     */
+    public int getDataLength() {
+        return mDataLength;
+    }
 }