JSR-043: JTAPI-1.4

javax.telephony.mobile
Interface MobileRadio


public interface MobileRadio

The MobileRadio interface is used for simple radio management capabilities (turning on and off), if the platform supports it. and getting information about the current signal strength.

Network States

The MobileRadio state can either be on (setState(true)) or off (setState(false)). If state management is not user controllable, then the setState method will throw a MethodNotSupportedException If the device has been secured via password protection (e.g. PIN-code), the setState method may also throw the InvalidStateException, if an attempt is made to manipulate the radio while the device is secured.

Mobile Radio Listeners

All changes in a MobileRadio object are reported via the MobileRadioListener interface. Applications instantiate an object which implements this interface and begins this delivery of events to this object using the MobileRadio.addRadioListener() method. Applications receive events on a listener until the listener is removed via the MobileRadio.removeRadioListener() method.

See Also:
MobileRadioEvent, MobileRadioListener

Method Summary
 void addRadioListener(MobileRadioListener listener)
          Add a listener for MobileRadio events.
 int getMaxSignalLevel()
          Get the maximum radio signal level.
 boolean getRadioStartState()
          Returns the MobileRadio startup state at boot.
 boolean getRadioState()
          Returns the current MobileRadio state.
 int getSignalLevel()
          Get the current radio signal level.
 void removeRadioListener(MobileRadioListener listener)
          Remove a listener from the MobileRadio.
 void setRadioStartState(boolean state)
          Sets the MobileRadio startup state at boot.
 void setRadioState(boolean state)
          Set the MobileRadio state.
 

Method Detail

getRadioState

public boolean getRadioState()
                      throws MethodNotSupportedException
Returns the current MobileRadio state.
Returns:
true if the radio is on, otherwise false.
Throws:
MethodNotSupportedException - can not access the current radio state.

setRadioState

public void setRadioState(boolean state)
                   throws MethodNotSupportedException,
                          InvalidStateException
Set the MobileRadio state. The MobileProvider must be OUT_OF_SERVICE before the MobileRadio object may turn the physical radio off. After the radio is successfully turned off the MobileRadio state must be changed to reflect the radio off status. When the radio is turned off, no further network events will be generated and the radio signal level is set to zero, until the radio is reenabled.

When the radio is turned on, the MobileProvider can be in any valid state, depending on whether there are networks detected and subscription details are OK.

Parameters:
state - The desired radio state.
Throws:
MethodNotSupportedException - Indicates the radio state can not be manipulated on this implementation.
InvalidStateException - Indicates the network service state cannot be changed due to current MobileProvider state.

getRadioStartState

public boolean getRadioStartState()
                           throws MethodNotSupportedException
Returns the MobileRadio startup state at boot.
Returns:
The current radio startup state.
Throws:
MethodNotSupportedException - Indicates the radio state startup management capability is not supported.

setRadioStartState

public void setRadioStartState(boolean state)
                        throws MethodNotSupportedException,
                               InvalidStateException
Sets the MobileRadio startup state at boot. A possible required password will not be given here for security reasons! The password required should be given some other way, determined by native implementation, or at next time when a MobileProvider object is requested from the JtapiPeer.
Parameters:
state - The new radio startup state. True, if radio is turned on. Otherwise, false.
Throws:
MethodNotSupportedException - Indicates the radio state startup management is not supported.
InvalidStateException - Indicates the network service startup state cannot be changed due to current platform state.

getSignalLevel

public int getSignalLevel()
Get the current radio signal level.

When the radio is turned off the signal level is set to zero. The radio signal is mapped to positive integer values from 1 to getMaxSignalLevel. In GSM networks the signal strength is mapped to the range 1-5. (e.g. Level 1 = 20%, Level 5 = 100%)

Returns:
The current radio signal level.
See Also:
getMaxSignalLevel()

getMaxSignalLevel

public int getMaxSignalLevel()
Get the maximum radio signal level.
Returns:
The maximum radio signal level.
See Also:
getSignalLevel()

addRadioListener

public void addRadioListener(MobileRadioListener listener)
                      throws MethodNotSupportedException
Add a listener for MobileRadio events.
Parameters:
listener - The listener object to add.
Throws:
MethodNotSupportedException - This implementation does not generate events.

removeRadioListener

public void removeRadioListener(MobileRadioListener listener)
Remove a listener from the MobileRadio.
Parameters:
listener - The listener to remove.

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org