javax.microedition.amms.control.tuner
Interface TunerControl

All Superinterfaces:

Control

All Known Subinterfaces:

FmTunerControl

public interface TunerControl
extends 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.

Since:

BlackBerry API 5.0.0

Field Summary
static int	AUTO Automatic stereo mode.
static String	MODULATION_AM AM modulation.
static 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(String modulation) Gets the maximum frequency supported by this tuner with the given modulation.
int	getMinFreq(String modulation) Gets the minimum frequency supported by this tuner with the given modulation.
String	getModulation() Gets the modulation in use.
int	getNumberOfPresets() Gets the number of presets.
int	getPresetFrequency(int preset) Gets the preset's frequency.
String	getPresetModulation(int preset) Gets the preset's modulation.
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, String modulation, boolean upwards) Seeks for the next broadcast signal.
int	setFrequency(int freq, 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, String mod, int stereoMode) Configures the preset using given settings.
void	setPresetName(int preset, 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

static final int MONO

Monaural mode.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

STEREO

static final int STEREO

Stereo mode.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

AUTO

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

Since:

BlackBerry API 5.0.0

MODULATION_FM

static final String MODULATION_FM

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

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

MODULATION_AM

static final String MODULATION_AM

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

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

Method Detail

getMinFreq

int getMinFreq(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 Hertz

Throws:

IllegalArgumentException - if the modulation is not supported or it is null

Since:

BlackBerry API 5.0.0

getMaxFreq

int getMaxFreq(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 Hertz

Throws:

IllegalArgumentException - if the modulation is not supported or it isnull

Since:

BlackBerry API 5.0.0

setFrequency

int setFrequency(int freq,
                 String modulation)

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

Parameters:

freq - the frequency in 100 Hertz 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 Hertz that was taken into use

Throws:

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

Since:

BlackBerry API 5.0.0

getFrequency

int getFrequency()

Gets the frequency which the tuner has been tuned to.

Returns:

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

Since:

BlackBerry API 5.0.0

seek

int seek(int startFreq,
         String modulation,
         boolean upwards)
         throws 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 Hertz 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 Hertz or, if no signal was found, 0

Throws:

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

MediaException - if the seek functionality is not available for the given modulation

Since:

BlackBerry API 5.0.0

getSquelch

boolean getSquelch()

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

Returns:

true if squelch is on or false if squelch is off

Since:

BlackBerry API 5.0.0

setSquelch

void setSquelch(boolean squelch)
                throws 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:

MediaException - if the given squelch setting is not supported

Since:

BlackBerry API 5.0.0

getModulation

String getModulation()

Gets the modulation in use.

Returns:

the modulation currently in use

Since:

BlackBerry API 5.0.0

getSignalStrength

int getSignalStrength()
                      throws 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:

MediaException - if querying the signal strength is not supported

Since:

BlackBerry API 5.0.0

getStereoMode

int getStereoMode()

Gets the stereo mode in use.

Returns:

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

Since:

BlackBerry API 5.0.0

setStereoMode

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:

IllegalArgumentException - if the given mode is not supported

Since:

BlackBerry API 5.0.0

getNumberOfPresets

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

Since:

BlackBerry API 5.0.0

usePreset

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:

IllegalArgumentException - if preset is less than 1 or preset is greater than the number of presets

Since:

BlackBerry API 5.0.0

setPreset

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:

IllegalArgumentException - if preset is less than 1 or preset is greater than the number of presets

SecurityException - if setting presets has been prohibited

Since:

BlackBerry API 5.0.0

setPreset

void setPreset(int preset,
               int freq,
               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 Hertz

mod - the modulation of the preset

stereoMode - the stereo mode of the preset

Throws:

IllegalArgumentException - if preset is less than 1 or preset is greater than the 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

SecurityException - if setting presets has been prohibited

Since:

BlackBerry API 5.0.0

getPresetFrequency

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 Hertz

Throws:

IllegalArgumentException - if preset is less than 1 or preset is greater than the number of presets

Since:

BlackBerry API 5.0.0

getPresetModulation

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:

IllegalArgumentException - if preset is less than 1 or preset is greater than the number of presets

Since:

BlackBerry API 5.0.0

getPresetStereoMode

int getPresetStereoMode(int preset)
                        throws 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:

IllegalArgumentException - if preset is less than 1 or preset is greater than the number of presets

MediaException - if the presets do not support storing of the stereo mode

Since:

BlackBerry API 5.0.0

getPresetName

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:

IllegalArgumentException - if preset is less than 1 or preset is greater than the number of presets

Since:

BlackBerry API 5.0.0

setPresetName

void setPresetName(int preset,
                   String name)

Sets the preset name.

Parameters:

preset - the preset whose name is to be set

name - the name of the preset

Throws:

IllegalArgumentException - if preset is less than 1 or preset is greater than the number of presets or if the name is null

SecurityException - if setting presets has been prohibited

Since:

BlackBerry API 5.0.0