PlayerListener.java

/*
 * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 * This code 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.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code 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 in the LICENSE file that
 * accompanied this code).
 *
 * 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 Oracle, 500 Oracle Parkway, Redwood Shores
 * CA 94065 USA or visit www.oracle.com if you need additional information or
 * have any questions.
 */

package javax.microedition.media;
/**
 * PlayerListener is the interface for receiving asynchronous events generated by Players. Applications may implement this interface and register their implementations with the addPlayerListener method in Player.
 * A number of standard Player events are defined here in this interface. Event types are defined as strings to support extensibility as different implementations may introduce proprietary events by adding new event types. To avoid name conflicts, proprietary events should be named with the "reverse-domainname" convention. For example, a company named "mycompany" should name its proprietary event names with strings like "com.mycompany.myEvent" etc.
 * Applications that rely on proprietary events may not function properly across different implementations. In order to make the applications that use those events to behave well in environments that don't implement them, String.equals() should be used to check the event.
 * See Also:Player
 */
public interface PlayerListener{
    /**
     * Posted when the Player enters into a buffering mode. Applications may require this event to handle other tasks.
     * When this event is received, the eventData parameter will be a Long object designating the media time when the buffering is started.
     * Value bufferingStarted is assigned to BUFFERING_STARTED.
     * See Also:Constant Field Values
     */
    static final java.lang.String BUFFERING_STARTED="bufferingStarted";

    /**
     * Posted when the Player leaves the buffering mode. Applications may require this event to handle other tasks.
     * When this event is received, the eventData parameter will be a Long object designating the media time when the buffering stopped.
     * Value bufferingStopped is assigned to BUFFERING_STOPPED.
     * See Also:Constant Field Values
     */
    static final java.lang.String BUFFERING_STOPPED="bufferingStopped";

    /**
     * Posted when a Player is closed. When this event is received, the eventData parameter is null.
     * Value closed is assigned to CLOSED.
     * See Also:Constant Field Values
     */
    static final java.lang.String CLOSED="closed";

    /**
     * Posted when the system or another higher priority application has released an exclusive device which is now available to the Player.
     * The Player will be in the REALIZED state when this event is received. The application may acquire the device with the prefetch or start method.
     * A DEVICE_UNAVAILABLE event must preceed this event.
     * The eventData parameter is a String specifying the name of the device.
     * Value deviceAvailable is assigned to DEVICE_AVAILABLE.
     * See Also:Constant Field Values
     */
    static final java.lang.String DEVICE_AVAILABLE="deviceAvailable";

    /**
     * Posted when the system or another higher priority application has temporarily taken control of an exclusive device which was previously available to the Player.
     * The Player will be in the REALIZED state when this event is received.
     * This event must be followed by either a DEVICE_AVAILABLE event when the device becomes available again, or an ERROR event if the device becomes permanently unavailable.
     * The eventData parameter is a String specifying the name of the device.
     * Value deviceUnavailable is assigned to DEVICE_UNAVAILABLE.
     * See Also:Constant Field Values
     */
    static final java.lang.String DEVICE_UNAVAILABLE="deviceUnavailable";

    /**
     * Posted when the duration of a Player is updated. This happens for some media types where the duration cannot be derived ahead of time. It can only be derived after the media is played for a period of time -- for example, when it reaches a key frame with duration info; or when it reaches the end of media.
     * When this event is received, the eventData parameter will be a Long object designating the duration of the media.
     * Value durationUpdated is assigned to DURATION_UPDATED.
     * See Also:Constant Field Values
     */
    static final java.lang.String DURATION_UPDATED="durationUpdated";

    /**
     * Posted when a Player has reached the end of the media. When this event is received, the eventData parameter will be a Long object designating the media time when the Player reached end of media and stopped.
     * Value endOfMedia is assigned to END_OF_MEDIA.
     * See Also:Constant Field Values
     */
    static final java.lang.String END_OF_MEDIA="endOfMedia";

    /**
     * Posted when an error had occurred. When this event is received, the eventData parameter will be a String object specifying the error message.
     * Value error is assigned to ERROR.
     * See Also:Constant Field Values
     */
    static final java.lang.String ERROR="error";

    /**
     * Posted when an error occurs during the recording. The current recording will be discarded. The application may set a new record location or stream to start recording again. When this event is received, the eventData parameter will be a String object specifying the error message.
     * Value recordError is assigned to RECORD_ERROR.
     * See Also:Constant Field Values
     */
    static final java.lang.String RECORD_ERROR="recordError";

    /**
     * Posted when recording is started.
     * When this event is received, the eventData parameter will be a Long object designating the media time when the recording is started.
     * Value recordStarted is assigned to RECORD_STARTED.
     * See Also:Constant Field Values
     */
    static final java.lang.String RECORD_STARTED="recordStarted";

    /**
     * Posted when recording is stopped.
     * When this event is received, the eventData parameter will be a Long object designating the media time when the recording stopped.
     * Value recordStopped is assigned to RECORD_STOPPED.
     * See Also:Constant Field Values
     */
    static final java.lang.String RECORD_STOPPED="recordStopped";

    /**
     * Posted when the size of the video is changed either because the source video size or the display size is changed. When this event is received, the eventData parameter will be a
     * object. The new sizes can be queried from the VideoControl.
     * Value sizeChanged is assigned to SIZE_CHANGED.
     * See Also:Constant Field Values
     */
    static final java.lang.String SIZE_CHANGED="sizeChanged";

    /**
     * Posted when a Player is started. When this event is received, the eventData parameter will be a Long object designating the media time when the Player is started.
     * Value started is assigned to STARTED.
     * See Also:Constant Field Values
     */
    static final java.lang.String STARTED="started";

    /**
     * Posted when a Player stops in response to the stop method call. When this event is received, the eventData parameter will be a Long object designating the media time when the Player stopped.
     * Value stopped is assigned to STOPPED.
     * See Also:Constant Field Values
     */
    static final java.lang.String STOPPED="stopped";

    /**
     * Posted when a Player is stopped as responding to the setStopTime call using the StopTimeControl. When this event is received, the eventData parameter will be a Long object designating the media time when the Player is stopped.
     * Value stoppedAtTime is assigned to STOPPED_AT_TIME.
     * See Also:Constant Field Values
     */
    static final java.lang.String STOPPED_AT_TIME="stoppedAtTime";

    /**
     * Posted when the volume of an audio device is changed. When this event is received, the eventData parameter will be a
     * object. The new volume can be queried from the VolumeControl.
     * Value volumeChanged is assigned to VOLUME_CHANGED.
     * See Also:Constant Field Values
     */
    static final java.lang.String VOLUME_CHANGED="volumeChanged";

    /**
     * This method is called to deliver an event to a registered listener when a Player event is observed.
     */
    abstract void playerUpdate(javax.microedition.media.Player player, java.lang.String event, java.lang.Object eventData);

}