Recofiguring must happen after stopping the filter. + * + *
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 { * *
Does nothing if the filter is already started. * + *
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 { * *
Does nothing if the filter is stopped or not started. * + *
Filter must be stopped to reconfigure. + * + *
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 diff --git a/media/java/android/media/tv/tuner/filter/RestartEvent.java b/media/java/android/media/tv/tuner/filter/RestartEvent.java index 069630188e55d..9c5992af5f480 100644 --- a/media/java/android/media/tv/tuner/filter/RestartEvent.java +++ b/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. * *
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. * *
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. * - *
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. + *
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. * - *
0 is reserved for the newly opened filter's first start. It's optional to be received. + *
{@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;