JSR-234 1.1

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

static final int MONO
Monaural mode.

See Also:
Constant Field Values

STEREO

static final int STEREO
Stereo mode.

See Also:
Constant Field Values

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

MODULATION_FM

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

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

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

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

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

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

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

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

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

java.lang.String getModulation()
Gets the modulation in use.

Returns:
the modulation currently in use

getSignalStrength

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

int getStereoMode()
Gets the stereo mode in use.

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

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:
java.lang.IllegalArgumentException - if the given mode is not supported

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

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:
java.lang.IllegalArgumentException - if preset < 1 or preset > number of presets

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:
java.lang.IllegalArgumentException - if preset < 1 or preset > number of preset range
java.lang.SecurityException - if setting presets has been prohibited

setPreset

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

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

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

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

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

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

JSR-234 1.1

Copyright © 2004-2007 Nokia Corporation. See the Copyright for details.