javax.microedition.broadcast.control
Interface TimerEventsControl

All Superinterfaces:

javax.microedition.media.Control

public interface TimerEventsControl
extends javax.microedition.media.Control

TimerEventsControl extends the MMAPI Player Control to provide information about the progress of the media playback. It helps the application to synchronize its actions to the played content.

TimerEventsControl can work in three modes. In interval mode (INTERVAL_MODE) the media player sends events constantly. Rate of the events is set by the application. In scheduled event mode (SCHEDULED_MODE) the media player sends events according to times specified by the application. In INTERVAL_AND_SCHEDULED_MODE the control acts like in interval and scheduled event modes at the same time.

In all modes, the time refers to media time of the Player. Mode is selected by setMode(int mode).

The default values for TimerEventsControl are: mode is INTERVAL_MODE, interval is 1 second (1000000 microseconds) and control is not enabled.

Interval mode

Interval mode is used for constant synchronization, for instance, to display a progress bar or timer on the screen, or to synchronize some other media to this player. In this mode the media player sends events at constant rate set by the application.

Interval is set in microseconds by setInterval(long interval). The minimum supported interval can be queried by getMinInterval(). For instance, if interval is set to 500000 microseconds and media player is started, an event will be sent after 0.5s, 1.0s, 1.5s and so on. Greatest minimum interval is 1 second and setting the interval to whole seconds is guaranteed to work despite the actual minimum interval.

Rate of events is related to the media time, not real time. For instance, if in the previous example the media is played in double speed, the events come in after 0.25s, 0.5s, 0.75s and so on.

The media engine can align the sending of the events in relation to the media time. For instance, if the interval ise set to 1000000 microseconds when the media time is 0.750 seconds, the time stamp event can come at 1s, 2s and so on. Interval only specifies the rate of the events. The media player can decide the exact time when the first event is sent but it will be sent within the real time (not media time) passing 2 * the minimum interval despite the playback speed of the player.

Scheduled event mode

Scheduled event mode allows application to specify the times of the events in advance. This mode is recommend for events that are known in advance, relatively few and spread unevenly over time. Overhead is small compared to constantly reading the Player's media time or to receive constant synchronization events.

Events are set individually by addScheduledEvent(long time) or by setting an array of them by addScheduledEvents(long[] time), and they can be removed by removeScheduledEvent(long time) or by removeAllScheduledEvents(). Time of the scheduled events when set is not evaluated except that the ones referring to past are ignored. However, it can not be guaranteed that the events are received exactly when they are timed. Implementation can still align the time to send the event to its own internal clock resolution. In addition, sending of events can be delayed in cases where several events needs to be sent within very short time frame. In practice, applications probably don't notice any difference even when events sometimes are delivered late.

Change to INTERVAL_MODE removes all scheduled events.

Receiving the events

Application receives events by reading them from readNextEvent(). When event occurs the method returns the time of the event. Time equals the mediaTime of the Player. For scheduled events the method returns the time the event was scheduled for even if the event in practice takes place later than that.

TimerEventsControl buffers one event. When an event occurs and application has not called readNextEvent the event is placed in the buffer. If multiple events occur only the latest is buffered. The other ones are missed.

readNextEvent() is a blocking method that returns

• Immediately if the buffer has an event. Event from the buffer is returned and the buffer is cleared.
• When the next event occurs if the buffer does not have an event.

Therefore, application should never read the events directly but an event reader in a separate thread should be used.

For instance, TimerEventsControl is enabled in INTERVAL_MODE with 1 second interval (1000000 µs). Therefore, an event is delivered in every one seconds. First call to readNextEvent() at 0.5 s would return when media player passes 1 second mark. If the first call is done at 5.5 s the method would return immediately with long value 5000000. (Assuming that media player does not align the times according to it's internal clock)

Field Summary

static int	INTERVAL_AND_SCHEDULED_MODE
static int	INTERVAL_MODE
static int	SCHEDULED_MODE

Method Summary

void	addScheduledEvent(long time) Add a scheduled event time.
void	addScheduledEvents(long[] times) Add an array of scheduled event times.
long	getInterval() Gets the interval.
long	getMinInterval() Gets the minimum supported interval.
int	getMode() Gets the current mode.
int	getScheduledEventCount() Gets the number of scheduled events..
long[]	getScheduledEvents() Get all scheduled events.
boolean	isEnabled() Queries the status of the sending of the timer event.
long	readNextEvent() Reads the next notification from the event buffer.
void	removeAllScheduledEvents() Remove all scheduled events.
void	removeScheduledEvent(long time) Remove scheduled event.
void	setEnabled(boolean enable) Enables the sending of timer events.
long	setInterval(long interval) Sets the interval to send events about the progress of the playback.
void	setMode(int mode) Sets the mode.

Field Detail

INTERVAL_AND_SCHEDULED_MODE

static final int INTERVAL_AND_SCHEDULED_MODE

See Also:

Constant Field Values

INTERVAL_MODE

static final int INTERVAL_MODE

See Also:

Constant Field Values

SCHEDULED_MODE

static final int SCHEDULED_MODE

See Also:

Constant Field Values

Method Detail

addScheduledEvent

void addScheduledEvent(long time)
                       throws java.lang.IllegalArgumentException

Add a scheduled event time. An event will occur when media time reaches time If the scheduled event time that is less than current media time or if the control is in INTERVAL_MODE mode the method call is be ignored.

Parameters:

time - time of the scheduled notification time in microseconds.

Throws:

java.lang.IllegalArgumentException - if time is less than minimum interval away from existing scheduled events.

addScheduledEvents

void addScheduledEvents(long[] times)
                        throws java.lang.IllegalArgumentException

Add an array of scheduled event times. An event will occur when media time reaches a time in the array of times Times in the array that are less than current media time are ignored. If the control is in INTERVAL_MODE mode the method call is be ignored.

Parameters:

times - array of scheduled event times in microseconds. Times in the array don't need to be in any specific order.

Throws:

java.lang.IllegalArgumentException - if any time in times is less than minimum interval away from existing scheduled events or from other events in times.

java.lang.NullPointerException - if times is null.

getInterval

long getInterval()

Gets the interval.

Returns:

the interval in microseconds

getMinInterval

long getMinInterval()

Gets the minimum supported interval. The return value must be greater than 0, and equal or less than 1000000.

Returns:

the minimum supported interval in microseconds.

getMode

int getMode()

Gets the current mode.

Returns:

current mode.

getScheduledEventCount

int getScheduledEventCount()

Gets the number of scheduled events..

Returns:

number of scheduled events or 0 if in INTERVAL_MODE mode.

getScheduledEvents

long[] getScheduledEvents()

Get all scheduled events.

Returns:

Array of scheduled event times. In INTERVAL_MODE an empty array is returned.

isEnabled

boolean isEnabled()

Queries the status of the sending of the timer event.

Returns:

true if the sending of timer events is active, false otherwise.

readNextEvent

long readNextEvent()

Reads the next notification from the event buffer. This method is blocking until next event occurs if the buffer is empty. If the buffer has an event the method returns immediately and the buffer is cleared. Application should use a separate thread to call this method.

Returns:

the next notification from the time buffer in the microseconds.

removeAllScheduledEvents

void removeAllScheduledEvents()

Remove all scheduled events. In INTERVAL_MODE mode the method call is ignored.

removeScheduledEvent

void removeScheduledEvent(long time)

Remove scheduled event.

Parameters:

time - time of the removed scheduled event in microseconds. If a scheduled event to match the time does not exist or the control is in INTERVAL_MODE mode the method call is ignored.

setEnabled

void setEnabled(boolean enable)

Enables the sending of timer events.

Parameters:

enable - true to enable, false to disable.

setInterval

long setInterval(long interval)

Sets the interval to send events about the progress of the playback.

Parameters:

interval - in microseconds. Implementation can round the interval to closest appropriate interval. Intervals that are multiplications of the minimum interval or multiplications of 1000000 (i.e. whole seconds) will not be rounded.

Returns:

interval that was actually set.

Throws:

java.lang.IllegalArgumentException - if the given value is less than minimum interval.

setMode

void setMode(int mode)

Sets the mode. Change to INTERVAL_MODE clears the buffer for scheduled events.

Throws:

java.lang.IllegalArgumentException - if mode is not INTERVAL_MODE, SCHEDULED_MODE or INTERVAL_AND_SCHEDULED_MODE.