net.rim.device.api.amms.control.fmradio
Interface FmTunerControl

All Superinterfaces:
TunerControl, Control

public interface FmTunerControl
extends TunerControl

Provides a superset of the functionality found in TunerControl. To use the FmTunerControl, cast the control interface returned by Player.getControl() as an FmTunerControl.

Example

    Player p = Manager.createPlayer("capture://radio");
    p.realize();
    FmTunerControl ftc = (FmTunerControl) p.getControl(FmTunerControl.class.getName());
    p.prefetch();
    // set the frequency to 88.8MHz and set the default minimum RSSI
    ftc.setFrequency(88800, ftc.getDefaultMinSignalStrengthInDb()); 
    p.start();

See Also:
FmRadioLocale
Since:
BlackBerry API 7.1.0

Field Summary
static int STATE_CLOSED
          FM Radio is not ready for use.
static int STATE_OPEN
          FM Radio is ready for use.
static int STATE_SEEKING
          FM radio is seeking for a signal.
static int STATE_TUNED
          FM radio is tuned to a signal.
static int STATE_UNKNOWN
          FM radio state is unknown.
 
Fields inherited from interface javax.microedition.amms.control.tuner.TunerControl
AUTO, MODULATION_AM, MODULATION_FM, MONO, STEREO
 
Method Summary
 void deletePreset(int preset)
          Deletes a station preset.
 int getDefaultMinSignalStrengthInDb()
          Gets the default minimum Radio Signal Strength Indication (RSSI) value.
 int[] getFrequencyAndRssi()
          Gets the current frequency and Radio Signal Strength Indication (RSSI) (in decibel).
 FmRadioLocale getLocale()
          Gets the FmRadioLocale object.
 int getRadioState()
          Gets the current radio state.
 int getSignalStrengthInDb()
          Gets the current Radio Signal Strength Indication (RSSI) value in decibel.
 boolean isExternalAntennaConnected()
          Gets the external antenna state.
 boolean isMute()
          Indicates whether or not the radio stream is currently muted.
 int[] seek(int startFreq, boolean upwards, int rssi)
          Seeks for next available station.
 int setFrequency(int frequency, int rssi)
          Tunes the radio to the desired frequency if the frequency is inside the range defined by the FmRadioLocale.
 void setMute(boolean mute)
          Mutes the FM radio stream.
 void setRdsRbdsReceptionEnabled(boolean enable)
          Sets the state for RDS/RBDS reception on/off.
 void stopSeek()
          Stops seeking for the next frequency.
 
Methods inherited from interface javax.microedition.amms.control.tuner.TunerControl
getFrequency, getMaxFreq, getMinFreq, getModulation, getNumberOfPresets, getPresetFrequency, getPresetModulation, getPresetName, getPresetStereoMode, getSignalStrength, getSquelch, getStereoMode, seek, setFrequency, setPreset, setPreset, setPresetName, setSquelch, setStereoMode, usePreset
 



Field Detail

STATE_UNKNOWN

static final int STATE_UNKNOWN
FM radio state is unknown.

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

STATE_TUNED

static final int STATE_TUNED
FM radio is tuned to a signal.

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

STATE_SEEKING

static final int STATE_SEEKING
FM radio is seeking for a signal.

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

STATE_OPEN

static final int STATE_OPEN
FM Radio is ready for use.

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

STATE_CLOSED

static final int STATE_CLOSED
FM Radio is not ready for use.

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0


Method Detail

seek

int[] seek(int startFreq,
           boolean upwards,
           int rssi)
           throws MediaException
Seeks for next available station. The Player must be in the Player.PREFETCHED or in the Player.STARTED state before you invoke this method. If the seek reaches the band-limit in the search direction it will restart the seek at the other band-limit in the same direction (wrap-around).

Please note that the seek result may return the currently tuned frequency. This may result from the current signal being so strong that the seek returns success immediately. Try specifying an offset to the starting frequency in that case.

Parameters:
startFreq - The starting frequency.
upwards - true to seek for a higher frequency; false to seek for a lower frequency.
rssi - The Radio Signal Strength Indication (RSSI) in decibel that the new station should at least have.
Returns:
An int array. int[0] is the frequency found and int[1] is the RSSI in decibel.
Throws:
MediaException - If the player was not prefetched or started.
Since:
BlackBerry API 7.1.0

setFrequency

int setFrequency(int frequency,
                 int rssi)
                 throws MediaException
Tunes the radio to the desired frequency if the frequency is inside the range defined by the FmRadioLocale. The range can be checked by calling (@link #getLocale()) and comparing the frequency to set to be between FmRadioLocale.getMinFreq() and FmRadioLocale.getMaxFreq().
The default value for the RSSI parameter to set is (@link #getDefaultMinSignalStrengthInDb()). The Player must be in the Player.PREFETCHED or Player.STARTED state before you invoke this method.

Parameters:
frequency - The desired frequency.
rssi - The desired RSSI value. If the signal strength on the frequency is lower the audio will be muted.
Returns:
The frequency in 100 Hertzs that was taken into use.
Throws:
MediaException - If the player was not prefetched; If the frequency to set is out of the range specified by the FmRadioLocale object or is not a valid frequency step.
Since:
BlackBerry API 7.1.0

getFrequencyAndRssi

int[] getFrequencyAndRssi()
                          throws MediaException
Gets the current frequency and Radio Signal Strength Indication (RSSI) (in decibel). You should invoke this method only after you tuned the radio to a station.

Returns:
An int array. int[0] is the current frequency and int[1] is the RSSI in decibel.
Throws:
MediaException - If the player was not prefetched or the radio was not tuned.
Since:
BlackBerry API 7.1.0

stopSeek

void stopSeek()
              throws MediaException
Stops seeking for the next frequency. You should invoke this method only after the player has started seeking.

Throws:
MediaException - If the radio is not currently seeking for a signal.
Since:
BlackBerry API 7.1.0

getSignalStrengthInDb

int getSignalStrengthInDb()
                          throws MediaException
Gets the current Radio Signal Strength Indication (RSSI) value in decibel. Calls (@link #getFrequencyAndRssi()) to retrieve the RSSI value. The Player must be in the Player.PREFETCHED or Player.STARTED state before you invoke this method.

Returns:
The current RSSI value in decibel.
Throws:
MediaException - If the player was not prefetched.
Since:
BlackBerry API 7.1.0

getDefaultMinSignalStrengthInDb

int getDefaultMinSignalStrengthInDb()
Gets the default minimum Radio Signal Strength Indication (RSSI) value.

Returns:
The minimum RSSI value in decibel.
Since:
BlackBerry API 7.1.0

getLocale

FmRadioLocale getLocale()
Gets the FmRadioLocale object. If the Player is in the Player.UNREALIZED or Player.REALIZED state the locale may represent the last stored value, while in Player.PREFETCHED or Player.STARTED state the locale has been determined automatically and will be up to date.

Returns:
The current locale setting.
See Also:
FmRadioLocale
Since:
BlackBerry API 7.1.0

getRadioState

int getRadioState()
                  throws MediaException
Gets the current radio state. The Player must be in the Player.REALIZED, Player.PREFETCHED or Player.STARTED state before you invoke this method.

Returns:
The FM radio state; one of STATE_TUNED or STATE_SEEKING or STATE_OPEN or STATE_CLOSED or STATE_UNKNOWN.
Throws:
MediaException - If the player was not realized.
Since:
BlackBerry API 7.1.0

isExternalAntennaConnected

boolean isExternalAntennaConnected()
Gets the external antenna state. You can receive notifications of changes in the antenna state by implementing the PlayerListener interface. Use the Player.addPlayerListener(PlayerListener) to register your PlayerListener. In the method playerUpdate(Player player, String event, Object eventData) you can compare the event to "com.rim.antennaConnected" or "com.rim.antennaDisconnected" Strings to catch antenna connection/disconnection state changes.

Returns:
true if connected; false otherwise.
Since:
BlackBerry API 7.1.0

deletePreset

void deletePreset(int preset)
Deletes a station preset.

Parameters:
preset - Preset id to be deleted.
Throws:
IllegalArgumentException - If the preset id does not exist.
Since:
BlackBerry API 7.1.0

setMute

void setMute(boolean mute)
             throws MediaException
Mutes the FM radio stream. If setMute(true) succeeds, the stream is transformed into a stream of zeroes. The Player must be in the Player.REALIZED, Player.PREFETCHED or Player.STARTED state before you invoke this method.

Throws:
MediaException - If the player was not realized.
Since:
BlackBerry API 7.1.0

isMute

boolean isMute()
               throws MediaException
Indicates whether or not the radio stream is currently muted. The Player must be in the Player.REALIZED, Player.PREFETCHED or Player.STARTED state before you invoke this method.

Returns:
true is muted; false otherwise.
Throws:
MediaException - If the player was not realized.
Since:
BlackBerry API 7.1.0

setRdsRbdsReceptionEnabled

void setRdsRbdsReceptionEnabled(boolean enable)
                                throws MediaException
Sets the state for RDS/RBDS reception on/off. The Player must be in the Player.PREFETCHED or Player.STARTED state before you invoke this method. You should invoke this method only after you tuned the radio to a station. RDS/RBDS receiption only starts after the player is started and tuned to a station that broadcasts the service.

Throws:
MediaException - If the player was not tuned to a frequency first.
Since:
BlackBerry API 7.1.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