JSR-043: JTAPI-1.4

javax.telephony.mobile
Interface MobileProvider

All Superinterfaces:
Provider
All Known Subinterfaces:
NetworkSelection

public interface MobileProvider
extends Provider

A MobileProvider represents the telephony software-entity that interfaces with a wireless subsystem. It is an extension of the core provider with various additions needed for wireless communication.

MobileProvider States

This interface defines states for the Provider which provide greater detail beyond the states defined in the Provider interface. The states defined by this interface are related to the states defined in the core package in certain, specific ways, as defined below. Applications may obtain the MobileProvider state via the Provider.getState() method defined on the core. This method returns one of the integer state constants defined in this interface.

Below is a description of each MobileProvider state in real-world terms. These real-world descriptions only serve to provide a more intuitive understanding of what is going on. Several methods in this specification state pre-conditions based upon the MobileProvider state. Most of the states are identical to those defined in the core package.

MobileProvider.RESTRICTED_SERVICE This state indicates that the subscription is invalid (invalid subscription, forbidden network...): from the network point of view, only emergency calls are allowed. Local operations (such as Personal Information Management) are available.

Core vs. Mobile Package States

There is a strong relationship between the MobileProvider states and the Provider states. If an implementation supports the mobile package, it must ensure this relationship is properly maintained.

Since the states defined in the MobileProvider interface provide more detail to the states defined in the Provider interface, each state in the Provider interface corresponds to a state defined in the MobileProvider interface. Conversely, each MobileProvider state corresponds to exactly one Provider state. This arrangement permits applications to view either the core state or the mobile state and still see a consistent view.

The following table outlines the relationship between the core package Provider states and the mobile package Provider states.

If the mobile package state is... then the core package state must be...
MobileProvider.RESTRICTED_SERVICE Provider.IN_SERVICE

Listeners and Events

Each time a state changes occurs on a MobileProvider, the application is notified via an event. This event is reported via the MobileProviderListener interface. Applications instantiate objects which implement this interface and use the Provider.addProviderListener(MobileProviderListener) method to begin the delivery of events.

See Also:
MobileProviderEvent, MobileProviderListener

Field Summary
static int RESTRICTED_SERVICE
          The MobileProvider.RESTRICTED_SERVICE state indicates a MobileProvider services are restricted because of missing user subscription or invalid/missing password such as four-digit PIN-code.
 
Fields inherited from interface javax.telephony.Provider
IN_SERVICE, OUT_OF_SERVICE, SHUTDOWN
 
Method Summary
 void cancelAvailableNetworkRequest()
          Cancels an outstanding getAvailableNetworks-request, if possible.
 MobileNetwork[] getAvailableNetworks(boolean fullsearch)
          Scans for available networks in the area or returns the previous search results, if available.
 MobileNetwork getCurrentNetwork()
          Returns the current network object.
 MobileNetwork getHomeNetwork()
          Get the home network object.
 int getMobileState()
          Returns the current state of the MobileProvider.
 java.util.Date getNetworkTime()
          Get the network time.
 java.util.TimeZone getNetworkTimeZone()
          Get the network time zone.
 java.lang.String getType()
          Returns the type of network/wireless service.
 boolean isRoaming()
          Return the current roaming status.
 void setNetwork(MobileNetwork network)
          Selects a network as the current servicing network.
 
Methods inherited from interface javax.telephony.Provider
addObserver, addProviderListener, createCall, getAddress, getAddressCapabilities, getAddressCapabilities, getAddresses, getCallCapabilities, getCallCapabilities, getCalls, getCapabilities, getConnectionCapabilities, getConnectionCapabilities, getName, getObservers, getProviderCapabilities, getProviderCapabilities, getProviderListeners, getState, getTerminal, getTerminalCapabilities, getTerminalCapabilities, getTerminalConnectionCapabilities, getTerminalConnectionCapabilities, getTerminals, removeObserver, removeProviderListener, shutdown
 

Field Detail

RESTRICTED_SERVICE

public static final int RESTRICTED_SERVICE
The MobileProvider.RESTRICTED_SERVICE state indicates a MobileProvider services are restricted because of missing user subscription or invalid/missing password such as four-digit PIN-code. In this state, only emergency calls are allowed.
Method Detail

getMobileState

public int getMobileState()
Returns the current state of the MobileProvider.

Returns:
The current state of the mobileprovider.

getAvailableNetworks

public MobileNetwork[] getAvailableNetworks(boolean fullsearch)
                                     throws MethodNotSupportedException,
                                            InvalidStateException,
                                            ResourceUnavailableException
Scans for available networks in the area or returns the previous search results, if available. The state of particular network may or may not be known.

Parameters:
fullsearch - True, if full search is initiated. This may take several tens of seconds to complete. False, if previous results without a full scan are asked for.
Returns:
A list of networks in the area or previous search results.
Throws:
MethodNotSupportedException - Indicates that the scanning for available networks is not supported.
InvalidStateException - Indicates the implementation is in a such state which network search is not possible (call ongoing, for example.)
ResourceUnavailableException - indicates that a resource inside the system is not available to complete an operation. This may often be the case when the application wants the previous results.
See Also:
MobileNetwork

cancelAvailableNetworkRequest

public void cancelAvailableNetworkRequest()
                                   throws MethodNotSupportedException,
                                          InvalidStateException
Cancels an outstanding getAvailableNetworks-request, if possible.

Throws:
MethodNotSupportedException - Indicates the cancelling of the radio scan capability is not supported.
InvalidStateException - Indicates the implementation is in a such state in which the cancelling of an operation is not possible.

getCurrentNetwork

public MobileNetwork getCurrentNetwork()
Returns the current network object. If no connection to a network is available this must return null. The current network is the one the mobile has registered to.

Returns:
A network object of the current network.

getHomeNetwork

public MobileNetwork getHomeNetwork()
                             throws MethodNotSupportedException,
                                    ResourceUnavailableException
Get the home network object. The information capability is in some cases dynamic i.e., it may or may not be available. (Information may be stored in a changeable SIM-card, for example.)

Returns:
The home network.
Throws:
MethodNotSupportedException - Indicates the home network information capability is not supported.
ResourceUnavailableException - Indicates that a resource inside the system is not available to complete an operation.

setNetwork

public void setNetwork(MobileNetwork network)
                throws MethodNotSupportedException,
                       InvalidStateException,
                       ResourceUnavailableException
Selects a network as the current servicing network. If the selected network is available, it will become the current network. Note: setting the network with this method forces the network selection mode to manual.
Parameters:
network - Network to be selected.
Throws:
MethodNotSupportedException - Indicates network selection is not supported.
InvalidStateException - Indicates the implementation is in a state in which setting the network is not possible (call ongoing, for example.)
ResourceUnavailableException - Indicates that a resource inside the system is not available to complete the operation.

isRoaming

public boolean isRoaming()
                  throws MethodNotSupportedException,
                         InvalidStateException
Return the current roaming status. True, if roaming.
Returns:
The current roaming status.
Throws:
MethodNotSupportedException - Indicates this method is not supported by the implementation.
InvalidStateException - Indicates the MobileProvider or MobileRadio is in a state in which the roaming state is not available.

getType

public java.lang.String getType()
Returns the type of network/wireless service. Totally up the implementation. Example: "GSM", "PCS1900", "CDMA" ...

Returns:
A string representing the air interface type.

getNetworkTime

public java.util.Date getNetworkTime()
                              throws MethodNotSupportedException
Get the network time.

Returns:
The current network time.
Throws:
MethodNotSupportedException - Indicates the home network information capability is not supported.

getNetworkTimeZone

public java.util.TimeZone getNetworkTimeZone()
                                      throws MethodNotSupportedException
Get the network time zone.

Returns:
The current network time zone.
Throws:
MethodNotSupportedException - Indicates the home network information capability is not supported.

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org