The following functionality is provided:
FM Radio works according the following state table:
tizen.fmradio.seekUp() and tizen.fmradio.seekDown() work when the radio is in playing state. InvalidStateError is thrown when they are called in other states.
For more information about how to use FMRadio API, see FMRadio Guide.
Since: 2.3
Interface | Method |
---|---|
FMRadioObject | |
FMRadioManager | void start (optional double? frequency) void stop () void seekUp (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) void seekDown (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) void scanStart (FMRadioScanCallback radioScanCallback, optional ErrorCallback? errorCallback) void scanStop (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) void setFMRadioInterruptedListener (FMRadioInterruptCallback interruptCallback) void unsetFMRadioInterruptedListener () void setAntennaChangeListener (AntennaChangeCallback changeCallback) void unsetAntennaChangeListener () |
FMRadioScanCallback | void onfrequencyfound (double frequency) void onfinished (double[] frequencies) |
FMRadioInterruptCallback | void oninterrupted (DOMString reason) void oninterruptfinished () |
AntennaChangeCallback | void onchange (boolean isAntennaConnected) |
enum RadioState { "PLAYING", "SCANNING", "READY"};
Since: 2.3
The states defined by this enumerator are:
[NoInterfaceObject] interface FMRadioObject { readonly attribute FMRadioManager fmradio; };
Tizen implements FMRadioObject;
Since: 2.3
The tizen.fmradio object provides access to the functionality of the FM Radio API.
[NoInterfaceObject] interface FMRadioManager { readonly attribute double frequency; readonly attribute double frequencyUpperBound; readonly attribute double frequencyLowerBound; readonly attribute long signalStrength; readonly attribute RadioState state; readonly attribute boolean isAntennaConnected; attribute boolean mute; void start(optional double? frequency) raises(WebAPIException); void stop() raises(WebAPIException); void seekUp(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void seekDown(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void scanStart(FMRadioScanCallback radioScanCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void scanStop(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void setFMRadioInterruptedListener (FMRadioInterruptCallback interruptCallback) raises(WebAPIException); void unsetFMRadioInterruptedListener() raises(WebAPIException); void setAntennaChangeListener(AntennaChangeCallback changeCallback) raises(WebAPIException); void unsetAntennaChangeListener() raises(WebAPIException); };
Since: 2.3
Since: 2.3
Since: 2.3
Since: 2.3
Since: 2.3
If the system detects that the radio antenna is disconnected then the isAntennaConnected is false.
For example, an earphone cable is commonly used as a FM antenna in mobile phones. In that case, the isAntennaConnected attribute can be used to check if the FM antenna is connected or not.
Since: 2.3
Code example:
if (!tizen.fmradio.isAntennaConnected) { console.log("Please plug in the earphones to listen to the radio"); }
Since: 2.3
start
void start(optional double? frequency);
Since: 2.3
This method allows the user to set the radio frequency between frequencyUpperBound and frequencyLowerBound. If the user calls this method without any frequency value, frequencyLowerBound is set.
Parameters:
Exceptions:
with error type ServiceNotAvailableError, if the radio hardware is not available because another application is using it.
with error type TypeMismatchError, if any input parameter is not of the expected type for that parameter.
with error type InvalidValuesError, if the frequency is out of bounds.
with error type InvalidStateError, if the radio state is not READY or PLAYING.
with error type UnknownError, if any other error occurs.
Code example:
var radioState = tizen.fmradio.state; if(radioState == "READY") { tizen.fmradio.start(87.5); } // jump to your favorite radio station (95.9MHz) and start playing //tizen.fmradio.start(95.9);
stop
void stop();
Since: 2.3
Exceptions:
with error type InvalidStateError, if the radio state is not PLAYING
with error type UnknownError, if the radio cannot be stopped because of a platform error.
Code example:
var radioState = tizen.fmradio.state; if(radioState == "PLAYING") { tizen.fmradio.stop(); }
seekUp
void seekUp(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 2.3
This method is only available in the PLAYING state. There is no change of state.
When the next valid frequency is successfully found, successCallback is invoked.
After the search, the radio begins playing the new channel automatically.
If the highest frequency(frequencyUpperBound) has been reached, it finds the lowest frequency(frequencyLowerBound) channel.
The ErrorCallback is launched with these error types:
Remark : It is not allowed to call a seek method in quick succession (e.g. calling seekUp() or seekDown() twice in one second). If a user call seekUp() while the radio is seeking, the errorCallback will be invoked.
Parameters:
Exceptions:
with error type TypeMismatchError, if any input parameter is not of the expected type for that parameter.
Code example:
var radioState = tizen.fmradio.state; function successCallback() { console.log("The radio find a new frequency successfully"); } function errorCallback(err) { console.log("The following error occurred : " + err.name); } if(radioState == "PLAYING") { tizen.fmradio.seekUp(successCallback, errorCallback); }
seekDown
void seekDown(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 2.3
This method is only available in the PLAYING state. There is no change of state.
When the next valid frequency is successfully found, successCallback is invoked.
After the search, the radio begins playing the new channel automatically.
If the lowest frequency(frequencyLowerBound) has been reached, it finds the highest frequency(frequencyUpperBound) channel.
The ErrorCallback is launched with these error types:
Remark : It is not allowed to call a seek method in quick succession (e.g. calling seekUp() or seekDown() twice in one second). If a user call seekDown() while the radio is seeking, the errorCallback will be invoked.
Parameters:
Exceptions:
with error type TypeMismatchError, if any input parameter is not of the expected type for that parameter.
Code example:
var radioState = tizen.fmradio.state; function successCallback() { console.log("The radio find a new frequency successfully"); } function errorCallback(err) { console.log("The following error occurred : " + err.name); } if(radioState == "PLAYING") { tizen.fmradio.seekDown(successCallback, errorCallback); }
scanStart
void scanStart(FMRadioScanCallback radioScanCallback, optional ErrorCallback? errorCallback);
Since: 2.3
This method is only available in the READY state. While the radio is scanning the channels, the radio state is SCANNING. After the scanning is completed, the radio state is changed to READY.
It scans all available channels from frequencyLowerBound to frequencyUpperBound.
Once the scan has started, it is not possible to call start(), seekUp(),
or seekDown() until the scan completes.
The scan can be cancelled any time, by calling scanStop(). The radio frequency will not be changed by the scan.
The following methods are invoked depending on the progress of this process :
The ErrorCallback is launched with these error types:
Parameters:
Exceptions:
with error type TypeMismatchError, if any input parameter is not of the expected type for that parameter.
Code example:
var radioState = tizen.fmradio.state; var radioScanCallback = { onfrequencyfound: function(frequency) { console.log("A new frequency found: " + frequency); }, onfinished: function(frequencies) { console.log(frequencies.length + "frequencies found!"); for (var i = 0; i < frequencies.length; i++) { console.log(i + ": " + frequencies[i]); } } }; function errorCallback(err) { console.log("The following error occurred : " + err.name); } if(radioState == "READY") { tizen.fmradio.scanStart(radioScanCallback, errorCallback); }
scanStop
void scanStop(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 2.3
This method can be used in the middle of scanning. After the scan has stopped, the radio restores the frequency played before the scan.
The ErrorCallback is launched with these error types:
Parameters:
Exceptions:
with error type TypeMismatchError, if any input parameter is not of the expected type for that parameter.
Code example:
var radioState = tizen.fmradio.state; function successCallback() { console.log("The scanning stops"); } function errorCallback(err) { console.log("The following error occurred : " + err.name); } if (radioState == "SCANNING") { tizen.fmradio.scanStop(successCallback, errorCallback); }
setFMRadioInterruptedListener
void setFMRadioInterruptedListener(FMRadioInterruptCallback interruptCallback);
Since: 2.3
This method sets a FMRadioInterruptCallback type callback that is triggered when the radio is interrupted. The callback lasts until the unsetFMRadioInterruptedListener() method is called.
Remark : When an audio interrupt occurs, the radio loses an audio focus and stops. Interrupts may occur for an incoming call, launching another audio player, or another player which also uses audio. To resume playing the radio, user interaction with the device is required. This is to avoid the occurrence of a race condition among applications that try to play without user interaction.
Parameters:
Exceptions:
with error type TypeMismatchError, if any input parameter is not of the expected type for that parameter.
with error type UnknownError, if any other error occurs.
Code example:
var interruptCallback = { oninterrupted: function(reason) { console.log(reason); }, oninterruptfinished: function() { console.log("The radio interruption finished."); } }; tizen.fmradio.setFMRadioInterruptedListener(interruptCallback);
unsetFMRadioInterruptedListener
void unsetFMRadioInterruptedListener();
Since: 2.3
Exceptions:
with error type UnknownError, if the method cannot be completed because of a platform error.
Code example:
tizen.fmradio.unsetFMRadioInterruptListener();
setAntennaChangeListener
void setAntennaChangeListener(AntennaChangeCallback changeCallback);
Since: 2.3
Parameters:
Exceptions:
with error type TypeMismatchError, if any input parameter is not of the expected type for that parameter.
with error type UnknownError, if the method cannot be completed because of a platform error.
Code example:
function antennaCallback(isAntennaConnected) { alert("Antenna status has been changed. It is now " + (isAntennaConnected ? "connected" : "disconnected")); } tizen.fmradio.setAntennaChangeListener(antennaCallback);
unsetAntennaChangeListener
void unsetAntennaChangeListener();
Since: 2.3
Exceptions:
with error type UnknownError, if the method cannot be completed because of a platform error.
Code example:
// When you don't want to detect a change in the antenna status tizen.fmradio.unsetAntennaChangeListener();
[Callback=FunctionOnly, NoInterfaceObject] interface FMRadioScanCallback { void onfrequencyfound(double frequency); void onfinished(double[] frequencies); };
Since: 2.3
onfrequencyfound
void onfrequencyfound(double frequency);
Since: 2.3
Parameters:
onfinished
void onfinished(double[] frequencies);
Since: 2.3
Parameters:
[Callback, NoInterfaceObject] interface FMRadioInterruptCallback { void oninterrupted(DOMString reason); void oninterruptfinished(); };
Since: 2.3
oninterrupted
void oninterrupted(DOMString reason);
Since: 2.3
Parameters:
oninterruptfinished
void oninterruptfinished();
Since: 2.3
Note that after it is invoked, you can turn on FM radio by invoking tizen.fmradio.start().
[Callback=FunctionOnly, NoInterfaceObject] interface AntennaChangeCallback { void onchange(boolean isAntennaConnected); };
Since: 2.3
onchange
void onchange(boolean isAntennaConnected);
Since: 2.3
Parameters:
To guarantee that the FM radio application runs on a device with FM radio, declare the following feature requirements in the config file:
module FMRadio { enum RadioState { "PLAYING", "SCANNING", "READY"}; [NoInterfaceObject] interface FMRadioObject { readonly attribute FMRadioManager fmradio; }; Tizen implements FMRadioObject; [NoInterfaceObject] interface FMRadioManager { readonly attribute double frequency; readonly attribute double frequencyUpperBound; readonly attribute double frequencyLowerBound; readonly attribute long signalStrength; readonly attribute RadioState state; readonly attribute boolean isAntennaConnected; attribute boolean mute; void start(optional double? frequency) raises(WebAPIException); void stop() raises(WebAPIException); void seekUp(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void seekDown(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void scanStart(FMRadioScanCallback radioScanCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void scanStop(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void setFMRadioInterruptedListener (FMRadioInterruptCallback interruptCallback) raises(WebAPIException); void unsetFMRadioInterruptedListener() raises(WebAPIException); void setAntennaChangeListener(AntennaChangeCallback changeCallback) raises(WebAPIException); void unsetAntennaChangeListener() raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface FMRadioScanCallback { void onfrequencyfound(double frequency); void onfinished(double[] frequencies); }; [Callback, NoInterfaceObject] interface FMRadioInterruptCallback { void oninterrupted(DOMString reason); void oninterruptfinished(); }; [Callback=FunctionOnly, NoInterfaceObject] interface AntennaChangeCallback { void onchange(boolean isAntennaConnected); }; };