javax.microedition.media
Interface PlayerListener


public interface PlayerListener

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.

Code fragment for catching standard events in playerUpdate()

if (eventType == PlayerListener.STARTED) {...}

Code fragment for catching proprietary events in playerUpdate()

if (eventType.equals("com.company.myEvent")) {...}
RIM Implementation Notes

RIM uses a proprietary event to notify PlayerListeners that a recording has been committed. After calling RecordControl.commit() the application should wait until it receives this event before attempting to do anything with the recording. The event name is

"net.rim.device.internal.media.recordCommitted"

RIM uses a proprietary event to notify PlayerListeners of media time updates during media playback. The event name is

"com.rim.timeUpdate"
and the eventData parameter is a Long object whose value is the current media time in microseconds. Time update events should occur approximately once every second but the time between updates may be greater.

Since:
JDE 4.0.0
See Also:
Player

Field Summary
static String BUFFERING_STARTED
          Posted when the Player enters into a buffering mode.
static String BUFFERING_STOPPED
          Posted when the Player leaves the buffering mode.
static String CLOSED
          Posted when a Player is closed.
static String DEVICE_AVAILABLE
          Posted when the system or another higher priority application has released an exclusive device which is now available to the Player.
static String DEVICE_UNAVAILABLE
          Posted when the system or another higher priority application has temporarily taken control of an exclusive device which was previously available to the Player.
static String DURATION_UPDATED
          Posted when the duration of a Player is updated.
static String END_OF_MEDIA
          Posted when a Player has reached the end of the media.
static String ERROR
          Posted when an error had occurred.
static String RECORD_ERROR
          Posted when an error occurs during the recording.
static String RECORD_STARTED
          Posted when recording is started.
static String RECORD_STOPPED
          Posted when recording is stopped.
static String SIZE_CHANGED
          Posted when the size of the video is changed either because the source video size or the display size is changed.
static String STARTED
          Posted when a Player is started.
static String STOPPED
          Posted when a Player stops in response to the stop method call.
static String STOPPED_AT_TIME
          Posted when a Player is stopped as responding to the setStopTime call using the StopTimeControl.
static String VOLUME_CHANGED
          Posted when the volume of an audio device is changed.
 
Method Summary
 void playerUpdate(Player player, String event, Object eventData)
          This method is called to deliver an event to a registered listener when a Player event is observed.
 

Field Detail

BUFFERING_STARTED

public static final String BUFFERING_STARTED
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.

Since:
JDE 4.0.0

BUFFERING_STOPPED

public static final String BUFFERING_STOPPED
Posted when the Player leaves the buffering mode.

Applications may require this event to handle other tasks.

When this even 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.

Since:
JDE 4.0.0

CLOSED

public static final String CLOSED
Posted when a Player is closed. When this event is received, the eventData parameter is null.

Value closed is assigned to CLOSED.

Since:
JDE 4.0.0

DEVICE_AVAILABLE

public static final String DEVICE_AVAILABLE
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.

Since:
JDE 4.0.0

DEVICE_UNAVAILABLE

public static final String DEVICE_UNAVAILABLE
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.

Since:
JDE 4.0.0

DURATION_UPDATED

public static final String DURATION_UPDATED
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.

Since:
JDE 4.0.0

END_OF_MEDIA

public static final String END_OF_MEDIA
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.

Since:
JDE 4.0.0

ERROR

public static final String ERROR
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.

Since:
JDE 4.0.0

RECORD_ERROR

public static final String RECORD_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.

Since:
JDE 4.0.0

RECORD_STARTED

public static final String RECORD_STARTED
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.

Since:
JDE 4.0.0

RECORD_STOPPED

public static final String RECORD_STOPPED
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.

Since:
JDE 4.0.0

SIZE_CHANGED

public static final String SIZE_CHANGED
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 VideoControl object. The new sizes can be queried from the VideoControl.

Value sizeChanged is assigned to SIZE_CHANGED.

Since:
JDE 4.0.0

STARTED

public static final String STARTED
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.

Since:
JDE 4.0.0

STOPPED

public static final String STOPPED
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.

Since:
JDE 4.0.0

STOPPED_AT_TIME

public static final String STOPPED_AT_TIME
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.

Since:
JDE 4.0.0

VOLUME_CHANGED

public static final String VOLUME_CHANGED
Posted when the volume of an audio device is changed. When this event is received, the eventData parameter will be a VolumeControl object. The new volume can be queried from the VolumeControl.

Value volumeChanged is assigned to VOLUME_CHANGED.

Since:
JDE 4.0.0
Method Detail

playerUpdate

public void playerUpdate(Player player,
                         String event,
                         Object eventData)
This method is called to deliver an event to a registered listener when a Player event is observed.
Parameters:
player - The player which generated the event.
event - The event generated as defined by the enumerated types.
eventData - The associated event data.
Since:
JDE 4.0.0



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.