1 /*
2  * Copyright 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.media.tv.tuner.filter;
18 
19 import android.annotation.SystemApi;
20 import android.media.tv.tuner.Tuner;
21 import android.media.tv.tuner.Tuner.Result;
22 import android.media.tv.tuner.TunerUtils;
23 
24 /**
25  *  A timer filter is used to filter data based on timestamps.
26  *
27  *  <p> If the timestamp is set, data is discarded if its timestamp is smaller than the
28  *  timestamp in this time filter.
29  *
30  *  <p> The format of the timestamps is the same as PTS defined in ISO/IEC 13818-1:2019. The
31  *  timestamps may or may not be related to PTS or DTS.
32  *
33  * @hide
34  */
35 @SystemApi
36 public class TimeFilter implements AutoCloseable {
37 
38 
nativeSetTimestamp(long timestamp)39     private native int nativeSetTimestamp(long timestamp);
nativeClearTimestamp()40     private native int nativeClearTimestamp();
nativeGetTimestamp()41     private native Long nativeGetTimestamp();
nativeGetSourceTime()42     private native Long nativeGetSourceTime();
nativeClose()43     private native int nativeClose();
44 
45     private long mNativeContext;
46 
47     private boolean mEnable = false;
48 
49     // Called by JNI code
TimeFilter()50     private TimeFilter() {
51     }
52 
53     /**
54      * Set timestamp for time based filter.
55      *
56      * It is used to set initial timestamp and enable time filtering. Once set, the time will be
57      * increased automatically like a clock. Contents are discarded if their timestamps are
58      * older than the time in the time filter.
59      *
60      * This method can be called more than once to reset the initial timestamp.
61      *
62      * @param timestamp initial timestamp for the time filter before it's increased. It's
63      * based on the 90KHz counter, and it's the same format as PTS (Presentation Time Stamp)
64      * defined in ISO/IEC 13818-1:2019. The timestamps may or may not be related to PTS or DTS.
65      * @return result status of the operation.
66      */
67     @Result
setCurrentTimestamp(long timestamp)68     public int setCurrentTimestamp(long timestamp) {
69         int res = nativeSetTimestamp(timestamp);
70         if (res == Tuner.RESULT_SUCCESS) {
71             mEnable = true;
72         }
73         return res;
74     }
75 
76     /**
77      * Clear the timestamp in the time filter.
78      *
79      * It is used to clear the time value of the time filter. Time filtering is disabled then.
80      *
81      * @return result status of the operation.
82      */
83     @Result
clearTimestamp()84     public int clearTimestamp() {
85         int res = nativeClearTimestamp();
86         if (res == Tuner.RESULT_SUCCESS) {
87             mEnable = false;
88         }
89         return res;
90     }
91 
92     /**
93      * Get the current time in the time filter.
94      *
95      * It is used to inquiry current time in the time filter.
96      *
97      * @return current timestamp in the time filter. It's based on the 90KHz counter, and it's
98      * the same format as PTS (Presentation Time Stamp) defined in ISO/IEC 13818-1:2019. The
99      * timestamps may or may not be related to PTS or DTS. Returns
100      * {@link Tuner#INVALID_TIMESTAMP} if the timestamp is never set.
101      */
getTimeStamp()102     public long getTimeStamp() {
103         if (!mEnable) {
104             return Tuner.INVALID_TIMESTAMP;
105         }
106         return nativeGetTimestamp();
107     }
108 
109     /**
110      * Get the timestamp from the beginning of incoming data stream.
111      *
112      * It is used to inquiry the timestamp from the beginning of incoming data stream.
113      *
114      * @return first timestamp of incoming data stream. It's based on the 90KHz counter, and
115      * it's the same format as PTS (Presentation Time Stamp) defined in ISO/IEC 13818-1:2019.
116      * The timestamps may or may not be related to PTS or DTS. Returns
117      * {@link Tuner#INVALID_TIMESTAMP} if the timestamp is not available.
118      */
getSourceTime()119     public long getSourceTime() {
120         if (!mEnable) {
121             return Tuner.INVALID_TIMESTAMP;
122         }
123         return nativeGetSourceTime();
124     }
125 
126     /**
127      * Close the Time Filter instance
128      *
129      * It is to release the TimeFilter instance. Resources are reclaimed so the instance must
130      * not be accessed after this method is called.
131      */
132     @Override
close()133     public void close() {
134         int res = nativeClose();
135         if (res != Tuner.RESULT_SUCCESS) {
136             TunerUtils.throwExceptionForResult(res, "Failed to close time filter.");
137         }
138     }
139 }
140