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"

See Also:

Player

Since:

BlackBerry API 4.0.0

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

STARTED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

STOPPED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

STOPPED_AT_TIME

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

END_OF_MEDIA

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

DURATION_UPDATED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

DEVICE_UNAVAILABLE

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

DEVICE_AVAILABLE

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

VOLUME_CHANGED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

SIZE_CHANGED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

ERROR

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.

RIM Implementation Note

The String object specifying the error may be a numerical error code, in which case it corresponds to one of the errors below:

Error Code	Error
1	Media player busy: the media player is currently performing an operation that precludes the requested operation.
2	Invalid parameter: a parameter was specified with an invalid value.
3	Insufficient memory: there is insufficient memory to perform the requested operation.
4	Need more data: playback cannot proceed until the streaming source provides more data.
5	Unspecified: some error occured which does not fit into any other category.
6	Format: an error in the media file was detected.
7	No server response: a server has stopped responding.
8	Connetion lost: the current connection has been dropped.
9	DNS resolve error: an invalid URL has been detected.
10	Unseekable: the media player needs to seek in the file in order to access headers, but can't since the file being played is unseekable.
11	Connection timeout: the (streaming) server is unreachable.
12	No rights: The DRM agent wasn't able to find a valid digital right in the media RTSP error 401 has occurred
13	General client error: The streaming server rejected the streaming request RTSP error 4xx not covered by another error code has occurred
14	Server error: An error occured on the streaming server while streaming RTSP error 5xx has occurred
15	Payment required: Payment is required to stream this item from the server RTSP error 402 has occurred
16	Forbidden: The streaming server has rejected the streaming request for security reasons RTSP error 403 has occurred
17	Client file not found: The item required to stream doesn't exist or has been removed from the server RTSP error 404 has occurred
18	Client proxy authentication required: Device needs to authenticate with a proxy server before streaming RTSP error 407 has occurred
19	Client request URI too large: The request URI sent to the server is too large RTSP error 414 has occurred
20	Not enough bandwidth: There is not enough bandwidth to support streaming RTSP error 453 has occurred
21	Client session not found: Streaming session has been removed by the server (e.g.: when paused for too long) RTSP error 454 has occurred
22	Unsupported transport: The streaming server/network doesn't support UDP/TCP streaming RTSP error 461 has occurred
23	Indicates the (data) connectivity has been suspended.
24	Indicates that the media player is currently suspended that precludes the requested operation.
25	Indicates that the wrong License DB was detected.
26	Indicates the device does not have a reliable time source and a time source is required to play the content.
27	Indicates the media cannot be played because it uses DRM and a DRM session is not available.
28	Indicates the media cannot be played because it uses DRM and a DRM session is not available.
29	RTSP Content Switch cannot be completed: Try to do a fast content switch but failed. The server returned 4xx/5xx error.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

CLOSED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

RECORD_STARTED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

RECORD_STOPPED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

RECORD_ERROR

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

BUFFERING_STARTED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

BUFFERING_STOPPED

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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

Method Detail

playerUpdate

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:

BlackBerry API 4.0.0