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
17package android.media;
18
19/** @hide */
20public 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     */
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     */
46    public void scheduleUpdate(OnMediaTimeListener listener);
47
48    /**
49     * Cancels all previous notification request from this listener if any.
50     */
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     */
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         */
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         */
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         */
87        void onStop();
88    }
89}
90
91