/* * * Copyright 1990-2009 Sun Microsystems, Inc. All Rights Reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License version * 2 only, as published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License version 2 for more details (a copy is * included at /legal/license.txt). * * You should have received a copy of the GNU General Public License * version 2 along with this work; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA * 02110-1301 USA * * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa * Clara, CA 95054 or visit www.sun.com if you need additional * information or have any questions. */ package javax.microedition.media.control; /** * <code>StopTimeControl</code> allows one to specify a preset stop time for * a <code>Player</code>. * <p> */ public interface StopTimeControl extends javax.microedition.media.Control { /** * Returned by <CODE>getStopTime</CODE> if no stop-time is set. * <p> * Value <code>Long.MAX_VALUE</code> is assigned to <code>RESET</code>. */ long RESET = Long.MAX_VALUE; /** * * Sets the <i>media time</i> at which you want the <code>Player</code> * to stop. * The <code>Player</code> will stop when its <i>media time</i> * reaches the stop-time. * A <code>STOPPED_AT_TIME</code> event * will be delivered through the <code>PlayerListener</code>. * <p> * The <code>Player</code> is guaranteed * to stop within one second past the preset stop-time * (i.e. <code>stop-time <= current-media-time <= stop-time + 1 sec.</code>); * unless the current media time is already passed the preset stop time * when the stop time is set. * If the current media time is already past the stop time set, * the <code>Player</code> will stop immediately. A * <code>STOPPED_AT_TIME</code> event will be delivered. * After the <code>Player</code> stops due to the stop-time set, * the previously set stop-time will be cleared automatically. * Alternatively, the stop time can be explicitly removed by * setting it to: <code>RESET</code>. * <p> * * You can always call <code>setStopTime</code> on a stopped * <code>Player</code>. * To avoid a potential race condition, it is illegal to * call <code>setStopTime</code> on a started <code>Player</code> if a * <i>media stop-time</i> has already been set. * * @param stopTime The time in microseconds at which you want the * <code>Player</code> to stop, in <i>media time</i>. * @exception IllegalStateException Thrown if * <code>setStopTime</code> is called on a started * <code>Player</code> and the * <i>media stop-time</i> has already been set. * @see #getStopTime */ void setStopTime(long stopTime); /** * Gets the last value successfully set by <CODE>setStopTime</CODE>. * * Returns the constant <CODE>RESET</CODE> if no stop time is set. * This is the default. * * @return The current stop time in microseconds. * @see #setStopTime */ long getStopTime(); }