01: /*
02: *
03: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
04: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
05: *
06: * This program is free software; you can redistribute it and/or
07: * modify it under the terms of the GNU General Public License version
08: * 2 only, as published by the Free Software Foundation.
09: *
10: * This program is distributed in the hope that it will be useful, but
11: * WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13: * General Public License version 2 for more details (a copy is
14: * included at /legal/license.txt).
15: *
16: * You should have received a copy of the GNU General Public License
17: * version 2 along with this work; if not, write to the Free Software
18: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
19: * 02110-1301 USA
20: *
21: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
22: * Clara, CA 95054 or visit www.sun.com if you need additional
23: * information or have any questions.
24: */
25:
26: package javax.microedition.media.control;
27:
28: /**
29: * <code>StopTimeControl</code> allows one to specify a preset stop time for
30: * a <code>Player</code>.
31: * <p>
32: */
33: public interface StopTimeControl extends
34: javax.microedition.media.Control {
35:
36: /**
37: * Returned by <CODE>getStopTime</CODE> if no stop-time is set.
38: * <p>
39: * Value <code>Long.MAX_VALUE</code> is assigned to <code>RESET</code>.
40: */
41: long RESET = Long.MAX_VALUE;
42:
43: /**
44: *
45: * Sets the <i>media time</i> at which you want the <code>Player</code>
46: * to stop.
47: * The <code>Player</code> will stop when its <i>media time</i>
48: * reaches the stop-time.
49: * A <code>STOPPED_AT_TIME</code> event
50: * will be delivered through the <code>PlayerListener</code>.
51: * <p>
52: * The <code>Player</code> is guaranteed
53: * to stop within one second past the preset stop-time
54: * (i.e. <code>stop-time <= current-media-time <= stop-time + 1 sec.</code>);
55: * unless the current media time is already passed the preset stop time
56: * when the stop time is set.
57: * If the current media time is already past the stop time set,
58: * the <code>Player</code> will stop immediately. A
59: * <code>STOPPED_AT_TIME</code> event will be delivered.
60: * After the <code>Player</code> stops due to the stop-time set,
61: * the previously set stop-time will be cleared automatically.
62: * Alternatively, the stop time can be explicitly removed by
63: * setting it to: <code>RESET</code>.
64: * <p>
65: *
66: * You can always call <code>setStopTime</code> on a stopped
67: * <code>Player</code>.
68: * To avoid a potential race condition, it is illegal to
69: * call <code>setStopTime</code> on a started <code>Player</code> if a
70: * <i>media stop-time</i> has already been set.
71: *
72: * @param stopTime The time in microseconds at which you want the
73: * <code>Player</code> to stop, in <i>media time</i>.
74: * @exception IllegalStateException Thrown if
75: * <code>setStopTime</code> is called on a started
76: * <code>Player</code> and the
77: * <i>media stop-time</i> has already been set.
78: * @see #getStopTime
79: */
80: void setStopTime(long stopTime);
81:
82: /**
83: * Gets the last value successfully set by <CODE>setStopTime</CODE>.
84: *
85: * Returns the constant <CODE>RESET</CODE> if no stop time is set.
86: * This is the default.
87: *
88: * @return The current stop time in microseconds.
89: * @see #setStopTime
90: */
91: long getStopTime();
92: }
|