1 /*
2  * Copyright (C) 2013 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;
18 
19 /** @hide */
20 public interface MediaTimeProvider {
21     // we do not allow negative media time
22     /**
23      * Presentation time value if no timed event notification is requested.
24      */
25     public final static long NO_TIME = -1;
26 
27     /**
28      * Cancels all previous notification request from this listener if any.  It
29      * registers the listener to get seek and stop notifications.  If timeUs is
30      * not negative, it also registers the listener for a timed event
31      * notification when the presentation time reaches (becomes greater) than
32      * the value specified.  This happens immediately if the current media time
33      * is larger than or equal to timeUs.
34      *
35      * @param timeUs presentation time to get timed event callback at (or
36      *               {@link #NO_TIME})
37      */
notifyAt(long timeUs, OnMediaTimeListener listener)38     public void notifyAt(long timeUs, OnMediaTimeListener listener);
39 
40     /**
41      * Cancels all previous notification request from this listener if any.  It
42      * registers the listener to get seek and stop notifications.  If the media
43      * is stopped, the listener will immediately receive a stop notification.
44      * Otherwise, it will receive a timed event notificaton.
45      */
scheduleUpdate(OnMediaTimeListener listener)46     public void scheduleUpdate(OnMediaTimeListener listener);
47 
48     /**
49      * Cancels all previous notification request from this listener if any.
50      */
cancelNotifications(OnMediaTimeListener listener)51     public void cancelNotifications(OnMediaTimeListener listener);
52 
53     /**
54      * Get the current presentation time.
55      *
56      * @param precise   Whether getting a precise time is important. This is
57      *                  more costly.
58      * @param monotonic Whether returned time should be monotonic: that is,
59      *                  greater than or equal to the last returned time.  Don't
60      *                  always set this to true.  E.g. this has undesired
61      *                  consequences if the media is seeked between calls.
62      * @throws IllegalStateException if the media is not initialized
63      */
getCurrentTimeUs(boolean precise, boolean monotonic)64     public long getCurrentTimeUs(boolean precise, boolean monotonic)
65             throws IllegalStateException;
66 
67     /** @hide */
68     public static interface OnMediaTimeListener {
69         /**
70          * Called when the registered time was reached naturally.
71          *
72          * @param timeUs current media time
73          */
onTimedEvent(long timeUs)74         void onTimedEvent(long timeUs);
75 
76         /**
77          * Called when the media time changed due to seeking.
78          *
79          * @param timeUs current media time
80          */
onSeek(long timeUs)81         void onSeek(long timeUs);
82 
83         /**
84          * Called when the playback stopped.  This is not called on pause, only
85          * on full stop, at which point there is no further current media time.
86          */
onStop()87         void onStop();
88     }
89 }
90 
91