javax.microedition.amms.control.tuner
Interface TunerControl

All Superinterfaces:
Control

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 - @return the minimum frequency in 100 Hertzs the modulation whose supported minimum frequency is asked
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 - @return the maximum frequency in 100 Hertzs the modulation whose supported maximum frequency is asked
Throws:
IllegalArgumentException - if the modulationis 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 Hertzs that will be taken into use. If that frequency is not supported, the closest supported frequency will be taken into use.
modulation - @return the frequency in 100 Hertzs that was taken into use 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.
Throws:
IllegalArgumentException - if freq is not inside the frequency band supported by the device or if the modulation is not supported or the modulationisnull
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 Hertzs
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 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 - @return the found frequency in 100 Hertzs or, if no signal was found, 0 if true, the scan proceeds towards higher frequencies, otherwise towards lower frequencies
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 1 or preset 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 1 or preset number of preset range
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 Hertzs
mod - the modulation of the preset
stereoMode - the stereo mode of the preset
Throws:
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
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 - @return the frequency of the preset in 100 Hertzs the preset whose frequency is to be returned
Throws:
IllegalArgumentException - if preset 1 or preset number of presets
Since:
BlackBerry API 5.0.0

getPresetModulation

String getPresetModulation(int preset)
Gets the preset's modulation.

Parameters:
preset - @return the modulation of the preset the preset whose modulation is to be returned
Throws:
IllegalArgumentException - if preset 1 or preset number of presets
Since:
BlackBerry API 5.0.0

getPresetStereoMode

int getPresetStereoMode(int preset)
                        throws MediaException
Gets the preset's stereo mode.

Parameters:
preset - @return the stereo mode of the preset. Stereo mode is one of MONO, STEREO or AUTO. the preset whose stereo mode is to be returned
Throws:
IllegalArgumentException - if preset 1 or preset 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 - @return a String containing the preset name the preset whose name is to be returned
Throws:
IllegalArgumentException - if preset 1 or preset 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 1 or preset number of presets or if the name is null
SecurityException - if setting presets has been prohibited
Since:
BlackBerry API 5.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal