net.rim.device.api.amms.control.fmradio
Class FmRadioLocale

java.lang.Object
  net.rim.device.api.amms.control.fmradio.FmRadioLocale

public class FmRadioLocale
extends Object

Represents the regional characteristics of FM radio reception. These characteristics optimize radio signal reception based for the region. This class configures the frequency band and frequency step parameters of FmTunerControl.seek(). Differences can be observed in the following parameters of the implementation:

• frequency band: 76-90MHz in Japan vs. 87.5-108MHz everywhere else
• frequency step: frequency steps used when seeking between stations
• emphasis: signal quality factor used on sender and receiver side (must be equal on both sides)

Technical Details

The locale is set by the BlackBerry device and the API can only be used to update the UI properly or set seek parameters according to the set locale. Use the FmTunerControl.getLocale() method to retrieve an FmRadioLocale object that you can use to fine configure your application according to the regional settings.

See Also:

FmTunerControl

Since:

BlackBerry API 7.1.0

Field Summary
static int	BAND_CCIR FM band outside of Japan (87.5-108MHz)
static int	BAND_JAPAN FM band in Japan (76-90MHz).
static int	EMPHASIS_50_US FM Emphasis used outside of North America
static int	EMPHASIS_75_US FM Emphasis used in North America
static FmRadioLocale	LOCALE_AMERICA FM Locale for North America.
static FmRadioLocale	LOCALE_JAPAN FM Locale for Japan.
static FmRadioLocale	LOCALE_OTHERS FM Locale for other countries.
static FmRadioLocale	LOCALE_OTHERS_STEP_50 FM Locale for other countries using a frequency step of 50kHz like Italy and Thailand.
static int	STEP_100_KHZ FM step used mostly in the rest of the world outside of North America
static int	STEP_200_KHZ FM step used in North America
static int	STEP_50_KHZ FM step

Constructor Summary

FmRadioLocale(int band, int maxFreq, int minFreq, int step, boolean isEvenOffset, int emphasis)
Constructor.

Method Summary
int	clampFrequency(int freq) Clamps the specified frequency into this locale's valid range.
boolean	equals(Object obj) Indicates whether two FmRadioLocale objects are equal by checking their FM data (band, minFreq, maxFreq, step, offset, and emphasis).
int	getBand() Gets the FM band.
int	getEmphasis() Gets the FM emphasis.
int	getFrequencyDigitsAfterDecimal() Checks the FM step size to be 50kHz.
int	getMaxFreq() Gets the maximum frequency for this locale.
int	getMinFreq() Gets the minimum frequency for this locale.
static FmRadioLocale[]	getPredefined() Gets a list of predefined FmRadioLocale objects.
int	getStep() Gets the FM step.
static int[]	getValidEmphases() Gets a list of valid FM emphasis.
static int[]	getValidSteps() Gets a list of valid FM steps.
int	hashCode() Creates a unique hashcode for this object.
boolean	isEvenOffset() Gets the FM offset.
boolean	isFrequencyInRange(int freq) Indicates whether the frequency is valid in the range defined for the locale.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

BAND_CCIR

public static final int BAND_CCIR

FM band outside of Japan (87.5-108MHz)

See Also:

Constant Field Values

Since:

BlackBerry API 7.1.0

BAND_JAPAN

public static final int BAND_JAPAN

FM band in Japan (76-90MHz).

See Also:

Constant Field Values

Since:

BlackBerry API 7.1.0

STEP_200_KHZ

public static final int STEP_200_KHZ

FM step used in North America

See Also:

Constant Field Values

Since:

BlackBerry API 7.1.0

STEP_100_KHZ

public static final int STEP_100_KHZ

FM step used mostly in the rest of the world outside of North America

See Also:

Constant Field Values

Since:

BlackBerry API 7.1.0

STEP_50_KHZ

public static final int STEP_50_KHZ

FM step

See Also:

Constant Field Values

Since:

BlackBerry API 7.1.0

EMPHASIS_75_US

public static final int EMPHASIS_75_US

FM Emphasis used in North America

See Also:

Constant Field Values

Since:

BlackBerry API 7.1.0

EMPHASIS_50_US

public static final int EMPHASIS_50_US

FM Emphasis used outside of North America

See Also:

Constant Field Values

Since:

BlackBerry API 7.1.0

LOCALE_JAPAN

public static final FmRadioLocale LOCALE_JAPAN

FM Locale for Japan. Useful when comparing a retrieved locale using the equals() method to determine whether the set locale is Japan.

Since:

BlackBerry API 7.1.0

LOCALE_AMERICA

public static final FmRadioLocale LOCALE_AMERICA

FM Locale for North America. Useful when comparing a retrieved locale using the equals() method to determine whether the set locale is North America.

Since:

BlackBerry API 7.1.0

LOCALE_OTHERS

public static final FmRadioLocale LOCALE_OTHERS

FM Locale for other countries. Useful when comparing a retrieved locale using the equals() method to determine whether the set locale is outside of Japan and North America.

Since:

BlackBerry API 7.1.0

LOCALE_OTHERS_STEP_50

public static final FmRadioLocale LOCALE_OTHERS_STEP_50

FM Locale for other countries using a frequency step of 50kHz like Italy and Thailand. Useful when comparing a retrieved locale using the equals() method to determine whether the set locale is outside of Japan and North America.

Since:

BlackBerry API 7.1.0

Constructor Detail

FmRadioLocale

public FmRadioLocale(int band,
                     int maxFreq,
                     int minFreq,
                     int step,
                     boolean isEvenOffset,
                     int emphasis)

Constructor.

Parameters:

band - The FM band to be set.

maxFreq - The upper frequency band-limit of the locale in 100Hz.

minFreq - The lower frequency band-limit of the locale in 100Hz.

step - The FM step to be set.

isEvenOffset - true even offset; false odd offset.

emphasis - The FM emphasis to be set.

Throws:

IllegalArgumentException - If the band is not either BAND_JAPAN or BAND_CCIR; If the step is not STEP_200_KHZ or STEP_100_KHZ or STEP_50_KHZ; If the emphasis is not EMPHASIS_75_US or EMPHASIS_50_US

Since:

BlackBerry API 7.1.0

Method Detail

getStep

public int getStep()

Gets the FM step.

Returns:

one of the STEP_200_KHZ or STEP_100_KHZ or STEP_50_KHZ constants defined in this class.

Since:

BlackBerry API 7.1.0

getFrequencyDigitsAfterDecimal

public int getFrequencyDigitsAfterDecimal()

Checks the FM step size to be 50kHz. This can be helpful for displaying frequencies with one or two digits after the decimal point.

Returns:

2, if the step equals STEP_50_KHZ, 1, otherwise.

Since:

BlackBerry API 7.1.0

isEvenOffset

public boolean isEvenOffset()

Gets the FM offset.

Returns:

true if the offset is even; false otherwise.

Since:

BlackBerry API 7.1.0

getEmphasis

public int getEmphasis()

Gets the FM emphasis.

Returns:

one of the EMPHASIS_75_US or EMPHASIS_50_US constants defined in this class.

Since:

BlackBerry API 7.1.0

getBand

public int getBand()

Gets the FM band.

Returns:

one of the BAND_JAPAN or BAND_CCIR constants defined in this class.

Since:

BlackBerry API 7.1.0

equals

public boolean equals(Object obj)

Indicates whether two FmRadioLocale objects are equal by checking their FM data (band, minFreq, maxFreq, step, offset, and emphasis).

Overrides:

equals in class Object

Parameters:

obj - An FMRadioLocale object.

Returns:

true if the two locale objects have the same FM data; false otherwise.

See Also:

Boolean.hashCode(), Hashtable

Since:

BlackBerry API 7.1.0

hashCode

public int hashCode()

Creates a unique hashcode for this object.

Overrides:

hashCode in class Object

Returns:

a unique hashcode based on the different possible locale attributes.

See Also:

Object.equals(java.lang.Object), Hashtable

Since:

BlackBerry API 7.1.0

getPredefined

public static FmRadioLocale[] getPredefined()

Gets a list of predefined FmRadioLocale objects.

Returns:

a newly-created array containing each of the LOCALE_ constants defined in this class.

Since:

BlackBerry API 7.1.0

getValidSteps

public static int[] getValidSteps()

Gets a list of valid FM steps.

Returns:

a newly-created array containing each of the STEP_ constants defined in this class.

Since:

BlackBerry API 7.1.0

getValidEmphases

public static int[] getValidEmphases()

Gets a list of valid FM emphasis.

Returns:

a newly-created array containing each of the EMPHASIS_ constants defined in this class.

Since:

BlackBerry API 7.1.0

getMinFreq

public int getMinFreq()

Gets the minimum frequency for this locale.

Returns:

frequency The minimum frequency for this locale in 100Hz.

Since:

BlackBerry API 7.1.0

getMaxFreq

public int getMaxFreq()

Gets the maximum frequency for this locale.

Returns:

frequency The maximum frequency for this locale in 100Hz.

Since:

BlackBerry API 7.1.0

isFrequencyInRange

public boolean isFrequencyInRange(int freq)

Indicates whether the frequency is valid in the range defined for the locale.

Parameters:

frequency - The desired frequency.

Returns:

true if the frequency is valid in the locale's range; false otherwise.

Since:

BlackBerry API 7.1.0

clampFrequency

public int clampFrequency(int freq)

Clamps the specified frequency into this locale's valid range. This method returns:

• the maximum frequency for the specified locale if the specified frequency is greater than the valid maximum frequency for the locale
• the minimum frequency for the specified locale if the specified frequency is less than the valid minimum frequency for the locale
• the specified frequency if the frequency is valid for the specified locale

Parameters:

frequency - The desired frequency.

Returns:

The nearest valid frequency for the locale.

Since:

BlackBerry API 7.1.0