javax.microedition.amms.control.tuner
Interface TunerControl

All Superinterfaces:

javax.microedition.media.Control

public interface TunerControl

extends javax.microedition.media.Control

TunerControl is an interface for controlling the tuner settings of a Player.

If no parameters concerning frequency, modulation or stereo mode were specified when the Player was created, they are assigned device-specific default values. The application must then query and/or change them accordingly.

The presets of TunerControl are referring to presets of the native tuner application and its settings. Using and setting of the presets only read and write the preset data respectively. If some preset has been taken in to use by usePreset the settings of the tuner do not change if the presets are changed after that unless usePreset is called again.

If no native tuner application or settings exist then presets of TunerControl are not usable either and getNumberOfPresets returns 0. Naturally, Java applications can always map and store frequencies and channel names internally.

The modulations supported by the tuner can be retrieved from system property tuner.modulations.

Field Summary

static int	AUTO Automatic stereo mode.
static java.lang.String	MODULATION_AM AM modulation.
static java.lang.String	MODULATION_FM FM modulation.
static int	MONO Monaural mode.
static int	STEREO Stereo mode.

Method Summary

int	getFrequency() Gets the frequency which the tuner has been tuned to.
int	getMaxFreq(java.lang.String modulation) Gets the maximum frequency supported by this tuner with the given modulation.
int	getMinFreq(java.lang.String modulation) Gets the minimum frequency supported by this tuner with the given modulation.
java.lang.String	getModulation() Gets the modulation in use.
int	getNumberOfPresets() Gets the number of presets.
int	getPresetFrequency(int preset) Gets the preset's frequency.
java.lang.String	getPresetModulation(int preset) Gets the preset's modulation.
java.lang.String	getPresetName(int preset) Gets the preset name.
int	getPresetStereoMode(int preset) Gets the preset's stereo mode.
int	getSignalStrength() Gets the strength of the recepted signal.
boolean	getSquelch() Gets the current squelching (muting in frequencies without broadcast) setting.
int	getStereoMode() Gets the stereo mode in use.
int	seek(int startFreq, java.lang.String modulation, boolean upwards) Seeks for the next broadcast signal.
int	setFrequency(int freq, java.lang.String modulation) Tunes to the given frequency or to the closest supported frequency.
void	setPreset(int preset) Configures the preset using current frequency and modulation (and stereo mode if native presets support storing it).
void	setPreset(int preset, int freq, java.lang.String mod, int stereoMode) Configures the preset using given settings.
void	setPresetName(int preset, java.lang.String name) Sets the preset name.
void	setSquelch(boolean squelch) Sets squelching on or off.
void	setStereoMode(int mode) Sets the stereo mode.
void	usePreset(int preset) Tunes the tuner by using settings specified in the preset.

Field Detail

MONO

public static final int MONO

Monaural mode.

See Also:

Constant Field Values

STEREO

public static final int STEREO

Stereo mode.

See Also:

Constant Field Values

AUTO

public static final int AUTO

Automatic stereo mode. This mode uses the best available mode. The best mode might be multichannel, for example.

See Also:

Constant Field Values

MODULATION_FM

public static final java.lang.String MODULATION_FM

FM modulation. Equals the modulation string in the system property if FM is supported.

See Also:

Constant Field Values

MODULATION_AM

public static final java.lang.String MODULATION_AM

AM modulation. Equals the modulation string in the system property if AM is supported.

See Also:

Constant Field Values

Method Detail

getMinFreq

public int getMinFreq(java.lang.String modulation)

Gets the minimum frequency supported by this tuner with the given modulation.

Parameters:

modulation - the modulation whose supported minimum frequency is asked

Returns:

the minimum frequency in 100 Hertzs

Throws:

java.lang.IllegalArgumentException - if the modulation is not supported or it is null

getMaxFreq

public int getMaxFreq(java.lang.String modulation)

Gets the maximum frequency supported by this tuner with the given modulation.

Parameters:

modulation - the modulation whose supported maximum frequency is asked

Returns:

the maximum frequency in 100 Hertzs

Throws:

java.lang.IllegalArgumentException - if the modulation is not supported or it is null

setFrequency

public int setFrequency(int freq,
                        java.lang.String modulation)

Tunes to the given frequency or to the closest supported frequency.

Parameters:

freq - the frequency in 100 Hertzs that will be taken into use. If that frequency is not supported, the closest supported frequency will be taken into use.

modulation - the modulation to be used. TunerControl specifies predefined constants MODULATION_FM and MODULATION_AM but other modulations can be supported as well. Supported modulations can be queried by System property tuner.modulations.

Returns:

the frequency in 100 Hertzs that was taken into use

Throws:

java.lang.IllegalArgumentException - if freq is not inside the frequency band supported by the device or if the modulation is not supported or the modulation is null

getFrequency

public int getFrequency()

Gets the frequency which the tuner has been tuned to.

Returns:

the frequency to which the device has been tuned, in 100 Hertzs

seek

public int seek(int startFreq,
                java.lang.String modulation,
                boolean upwards)
         throws javax.microedition.media.MediaException

Seeks for the next broadcast signal. If the end of the Player's frequency band is reached before a signal was found, the scan continues from the other end until a signal is found or the starting frequency is reached.

After seeking, the frequency of the Player is the one that was returned or if nothing was found, the original frequency.

Parameters:

startFreq - the frequency in 100 Hertzs wherefrom the scan starts (inclusive)

modulation - the modulation to be used. TunerControl specifies predefined constants MODULATION_FM and MODULATION_AM but other modulations can be supported as well. Supported modulations can be queried by System property tuner.modulations.

upwards - if true, the scan proceeds towards higher frequencies, otherwise towards lower frequencies

Returns:

the found frequency in 100 Hertzs or, if no signal was found, 0

Throws:

java.lang.IllegalArgumentException - if startFreq is not between the supported minimum and maximum frequencies or if the modulation is null

javax.microedition.media.MediaException - if the seek functionality is not available for the given modulation

getSquelch

public boolean getSquelch()

Gets the current squelching (muting in frequencies without broadcast) setting.

Returns:

true if squelch is on or false if squelch is off

setSquelch

public void setSquelch(boolean squelch)
                throws javax.microedition.media.MediaException

Sets squelching on or off. Squelching means muting the frequencies that do not contain radio broadcast.

Parameters:

squelch - true to turn the squelch on or false to turn the squelch off

Throws:

javax.microedition.media.MediaException - if the given squelch setting is not supported

getModulation

public java.lang.String getModulation()

Gets the modulation in use.

Returns:

the modulation currently in use

getSignalStrength

public int getSignalStrength()
                      throws javax.microedition.media.MediaException

Gets the strength of the recepted signal.

Returns:

a value between 0 and 100 where 0 means the faintest and 100 the strongest possible signal strength

Throws:

javax.microedition.media.MediaException - if querying the signal strength is not supported

getStereoMode

public int getStereoMode()

Gets the stereo mode in use.

Returns:

the stereo mode in use. Stereo mode is one of MONO, STEREO or AUTO.

setStereoMode

public void setStereoMode(int mode)

Sets the stereo mode.

Parameters:

mode - the stereo mode to be used. Stereo mode is one of MONO, STEREO or AUTO.

Throws:

java.lang.IllegalArgumentException - if the given mode is not supported

getNumberOfPresets

public int getNumberOfPresets()

Gets the number of presets. The numbering of presets starts from one and the largest preset number equals the value returned from this method.

Returns:

the number of presets, or zero if the presets are not supported

usePreset

public void usePreset(int preset)

Tunes the tuner by using settings specified in the preset. Changes to presets following a usePreset call do not tune the tuner automatically.

Parameters:

preset - the preset to be used

Throws:

java.lang.IllegalArgumentException - if preset < 1 or preset > number of presets

setPreset

public void setPreset(int preset)

Configures the preset using current frequency and modulation (and stereo mode if native presets support storing it).

Parameters:

preset - the preset to be set

Throws:

java.lang.IllegalArgumentException - if preset < 1 or preset > number of preset range

java.lang.SecurityException - if setting presets has been prohibited

setPreset

public void setPreset(int preset,
                      int freq,
                      java.lang.String mod,
                      int stereoMode)

Configures the preset using given settings. The stereo mode might not be stored if it is not supported by the presets. (In that case, IllegalArgumentException is not thrown.)

Parameters:

preset - the preset to be configured

freq - the frequency of the preset in 100 Hertzs

mod - the modulation of the preset

stereoMode - the stereo mode of the preset

Throws:

java.lang.IllegalArgumentException - if preset < 1 or preset > number of presets or freq or modulation are not available or if the modulation is null or if stereoMode is not a supported stereo mode

java.lang.SecurityException - if setting presets has been prohibited

getPresetFrequency

public int getPresetFrequency(int preset)

Gets the preset's frequency.

Parameters:

preset - the preset whose frequency is to be returned

Returns:

the frequency of the preset in 100 Hertzs

Throws:

java.lang.IllegalArgumentException - if preset < 1 or preset > number of presets

getPresetModulation

public java.lang.String getPresetModulation(int preset)

Gets the preset's modulation.

Parameters:

preset - the preset whose modulation is to be returned

Returns:

the modulation of the preset

Throws:

java.lang.IllegalArgumentException - if preset < 1 or preset > number of presets

getPresetStereoMode

public int getPresetStereoMode(int preset)
                        throws javax.microedition.media.MediaException

Gets the preset's stereo mode.

Parameters:

preset - the preset whose stereo mode is to be returned

Returns:

the stereo mode of the preset. Stereo mode is one of MONO, STEREO or AUTO.

Throws:

java.lang.IllegalArgumentException - if preset < 1 or preset > number of presets

javax.microedition.media.MediaException - if the presets do not support storing of the stereo mode

getPresetName

public java.lang.String getPresetName(int preset)

Gets the preset name.

Parameters:

preset - the preset whose name is to be returned

Returns:

a String containing the preset name

Throws:

java.lang.IllegalArgumentException - if preset < 1 or preset > number of presets

setPresetName

public void setPresetName(int preset,
                          java.lang.String name)

Sets the preset name.

Parameters:

preset - the preset whose name is to be set

name - the name of the preset

Throws:

java.lang.IllegalArgumentException - if preset < 1 or preset > number of presets or if the name is null

java.lang.SecurityException - if setting presets has been prohibited