1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This class allows one to specify a preset stop time for a Player

    15 *

    16 */

    17 

    18 package com.nokia.microedition.media.control;

    19 

    20 /**

    21  * <code>StopTimeControl</code> allows one to specify a preset stop time for

    22  * a <code>Player</code>.

    23  * <p>

    24  */

    25 public class StopTimeControl extends ControlImpl

    26         implements javax.microedition.media.control.StopTimeControl

    27 {

    28     /**

    29      * StopTimeControl constructor

    30      */

    31     public StopTimeControl()

    32     {

    33     }

    34 

    35     /**

    36      * Gets the last value successfully set by <CODE>setStopTime</CODE>.

    37      *

    38      * Returns the constant <CODE>RESET</CODE> if no stop time is set.

    39      * This is the default.

    40      *

    41      * @return The current stop time in microseconds.

    42      * @see #setStopTime

    43      */

    44     public long getStopTime()

    45     {

    46         checkState();

    47         long time = _getStopTime(iEventSource, iControlHandle);

    48         return time;

    49     }

    50 

    51     /**

    52      *

    53      * Sets the <i>media time</i> at which you want the <code>Player</code>

    54      * to stop.

    55      * The <code>Player</code> will stop when its <i>media time</i>

    56      * reaches the stop-time.

    57      * A <code>STOPPED_AT_TIME</code> event

    58      * will be delivered through the <code>PlayerListener</code>.

    59      * <p>

    60      * The <code>Player</code> is guaranteed

    61      * to stop within one second past the preset stop-time

    62      * (i.e. <code>stop-time <= current-media-time <= stop-time + 1 sec.</code>);

    63      * unless the current media time is already passed the preset stop time

    64      * when the stop time is set.

    65      * If the current media time is already past the stop time set,

    66      * the <code>Player</code> will stop immediately.  A

    67      * <code>STOPPED_AT_TIME</code> event will be delivered.

    68      * After the <code>Player</code> stops due to the stop-time set,

    69      * the previously set stop-time will be cleared automatically.

    70      * Alternatively, the stop time can be explicitly removed by

    71      * setting it to: <code>RESET</code>.

    72      * <p>

    73      *

    74      * You can always call <code>setStopTime</code> on a stopped

    75      * <code>Player</code>.

    76      * To avoid a potential race condition, it is illegal to

    77      * call <code>setStopTime</code> on a started <code>Player</code> if a

    78      * <i>media stop-time</i> has already been set.

    79      *

    80      * @param aStopTime The time in microseconds at which you want the

    81      * <code>Player</code> to stop, in <i>media time</i>.

    82      * @exception IllegalStateException Thrown if

    83      * <code>aStopTime</code> is called on a started

    84      * <code>Player</code> and the

    85      * <i>media stop-time</i> has already been set.

    86      * @see #getStopTime

    87      */

    88     public void setStopTime(long aStopTime) throws IllegalStateException

    89     {

    90         checkState();

    91         if (iPlayer.getState() == iPlayer.STARTED && getStopTime() != RESET)

    92         {

    93             throw new IllegalStateException(

    94                 "Player is STARTED or setStopTime() is already called successfully");

    95         }

    96 

    97         // Set native object to stop at time

    98         _setStopTime(iEventSource, iControlHandle, aStopTime);

    99     }

   100 

   101     private static native long _getStopTime(int aEventSourceHandle,

   102                                             int aControlHandle);

   103 

   104     private static native int _setStopTime(int aEventSourceHandle,

   105                                            int aControlHandle,

   106                                            long aTime);

   107 

   108 }