Merge "Improve documation of RestartEvent of Tuner Filter" into sc-dev

core/api/system-current.txt

@@ -5817,6 +5817,7 @@ package android.media.tv.tuner.filter {
 
   public final class RestartEvent extends android.media.tv.tuner.filter.FilterEvent {
     method public int getStartId();
+    field public static final int NEW_FILTER_FIRST_START_ID = 0; // 0x0
   }
 
   public final class ScramblingStatusEvent extends android.media.tv.tuner.filter.FilterEvent {

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

@@ -284,6 +284,12 @@ public class Filter implements AutoCloseable {
     /**
      * Configures the filter.
      *
+     * <p>Recofiguring must happen after stopping the filter.
+     *
+     * <p>When stopping, reconfiguring and restarting the filter, the client should discard all
+     * coming events until it receives {@link RestartEvent} through {@link FilterCallback} to avoid
+     * using the events from the previous configuration.
+     *
      * @param config the configuration of the filter.
      * @return result status of the operation.
      */
@@ -393,6 +399,10 @@ public class Filter implements AutoCloseable {
      *
      * <p>Does nothing if the filter is already started.
      *
+     * <p>When stopping, reconfiguring and restarting the filter, the client should discard all
+     * coming events until it receives {@link RestartEvent} through {@link FilterCallback} to avoid
+     * using the events from the previous configuration.
+     *
      * @return result status of the operation.
      */
     @Result
@@ -409,6 +419,12 @@ public class Filter implements AutoCloseable {
      *
      * <p>Does nothing if the filter is stopped or not started.
      *
+     * <p>Filter must be stopped to reconfigure.
+     *
+     * <p>When stopping, reconfiguring and restarting the filter, the client should discard all
+     * coming events until it receives {@link RestartEvent} through {@link FilterCallback} to avoid
+     * using the events from the previous configuration.
+     *
      * @return result status of the operation.
      */
     @Result

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

@@ -19,17 +19,29 @@ package android.media.tv.tuner.filter;
 import android.annotation.SystemApi;
 
 /**
- * An Event that the client would reveice after stopping, reconfiguring and restarting a filter.
+ * An Event that the client would receive after starting a filter. This event is optional to be
+ * received on the newly opened and started filter. It must be received after stopping,
+ * reconfiguring and restarting a Filter to differentiate the valid reconfigured events from the
+ * previous events.
  *
  * <p>After stopping and restarting the filter, the client has to discard all coming events until
  * it receives {@link RestartEvent} to avoid using the events from the previous configuration.
  *
  * <p>Recofiguring must happen after stopping the filter.
  *
+ * @see Filter#stop()
+ * @see Filter#start()
+ * @see Filter#configure(FilterConfiguration)
+ *
  * @hide
  */
 @SystemApi
 public final class RestartEvent extends FilterEvent {
+    /**
+     * The stard id reserved for the newly opened filter's first start event.
+     */
+    public static final int NEW_FILTER_FIRST_START_ID = 0;
+
     private final int mStartId;
 
     // This constructor is used by JNI code only
@@ -38,13 +50,13 @@ public final class RestartEvent extends FilterEvent {
     }
 
     /**
-     * Gets the start id.
+     * Gets the start id sent via the current Restart Event.
      *
-     * <p>An unique ID to mark the start point of receiving the valid filter events after
-     * reconfiguring. It must be sent at least once in the first event after the filter is
-     * restarted.
+     * <p>An unique ID to mark the start point of receiving the valid reconfigured filter events.
+     * The client must receive at least once after the filter is reconfigured and restarted.
      *
-     * <p>0 is reserved for the newly opened filter's first start. It's optional to be received.
+     * <p>{@link #NEW_FILTER_FIRST_START_ID} is reserved for the newly opened filter's first start.
+     * It's optional to be received.
      */
     public int getStartId() {
         return mStartId;