Interface java.telephony.TerminalConnection
All Packages Class Hierarchy This Package Previous Next Index
Interface java.telephony.TerminalConnection
- public interface TerminalConnection
- extends Object
The TerminalConnection interface describes the relationship between a
Call and a Terminal. A TerminalConnection object must always be associated
with some Connection object. A TerminalConnection object cannot exist
without being part of a Connection object. The TerminalConnection object
has a state. Similar to the Connection state, the TerminalConnection state
describes the relationship between the Terminal and the Call.
TerminalConnections are the means by which the call model describes
exactly which Terminals are part of the Call. In order for a
TerminalConnection to be associated with a Terminal, the Terminal must have
as one of its Address objects the Address object pointed to by the
Connection object.
There are six states on the TerminalConnection object: IDLE, RINGING,
PASSIVE, ACTIVE, DROPPED, and UNKNOWN.
The IDLE state is the initial state for all TerminalConnections. Terminal
Connections do not stay in this state for long. They typically transition
into another state quickly.
The RINGING state indicates the a Terminal is ringing, indicating that the
Terminal has an incoming Call.
The PASSIVE state indicates that a Terminal is part of a telephone call
but not in an active fashion. This may imply that a resource of the Terminal
is being used and may limit actions on the Terminal.
The ACTIVE state indicates that a Terminal is actively part of a telephone
call. This usually implies that the party speaking on that Terminal is party
of the telephone call.
The DROPPED state indicates that a particular Terminal has permanently left
the telephone call.
The UNKNOWN state indiciates that the implementation is unable to determine
the state of the TerminalConnection. TerminalConnections may transition
into and out of the UNKNOWN state at any time.
These states are partially described by the allowable transitions from one
to another. The following chart describes these allowable transitions.
Each state on the left many transition into the listed states on the right.
- IDLE ---> PASSIVE, RINGING, ACTIVE, DROPPED, UNKNOWN
- PASSIVE ---> ACTIVE, DROPPED, UNKNOWN
- RINGING ---> DROPPED, PASSIVE, ACTIVE, UNKNOWN
- ACTIVE ---> PASSIVE, DROPPED, UNKNOWN
- DROPPED ---> no state transition allowed.
- UNKNOWN ---> IDLE, PASSIVE, RINGING, ACTIVE, DROPPED
These TerminalConnection states also depend upon the Connection states. In
the description of the Call.connect() method these
TerminalConnections are created and transition states during certain
stages outlined in the Call.connect() method. Below is a chart
which relates Connection states w.r.t allowable TerminalConnection states.
In other words, if a Connection is in a certain state, all
TerminalConnection objects associated with it must be in certain states as
defined below. The states on the left represent Connection states and the
states on the right represent TerminalConnection states.
- IDLE ---> no connection states may exist
- CONNECTED ---> PASSIVE | ACTIVE | DROPPED
- INPROGRESS ---> no connection states may exist
- ALERTING ---> RINGING
- DISCONNECTED ---> DROPPED
- FAILED ---> DROPPED
- UNKNOWN ---> UNKNOWN
A TerminalConnection may answer incoming telephone calls with the
answer() method. It may answer telephony calls only if the
TerminalConnection is in the TerminalConnection.RINGING state. This is more
formally described by the pre-conditions of the answer() method.
- See Also:
- CallObserver,
-
ACTIVE
- The ACTIVE state indicates that a Terminal is actively part of a
telephone call.
-
DROPPED
- The DROPPED state indicates that a particular Terminal has permanently
left the telephone call.
-
IDLE
- The IDLE state is the initial state for all TerminalConnection objects.
-
PASSIVE
- The PASSIVE state indicates that a Terminal is part of a telephone call
but not in an active fashion.
-
RINGING
- The RINGING state indicates the a Terminal is ringing, indicating that the
Terminal has an incoming Call.
-
UNKNOWN
- The UNKNOWN state indicates that the implementation is unable to determine
the state of the TerminalConnection.
-
answer()
- Answers a telephone call.
-
getConnection()
- Returns the Connection object associated with this TerminalConnection.
-
getState()
- Returns the state of the TerminalConnection object.
-
getTerminal()
- Returns the Terminal associated with this TerminalConnection object.
-
getTerminalConnectionCapabilities(Terminal, Address)
- Gets the TerminalConnectionCapabilities object with respect to a Terminal and an
Address.
IDLE
public final static int IDLE
- The IDLE state is the initial state for all TerminalConnection objects.
RINGING
public final static int RINGING
- The RINGING state indicates the a Terminal is ringing, indicating that the
Terminal has an incoming Call.
PASSIVE
public final static int PASSIVE
- The PASSIVE state indicates that a Terminal is part of a telephone call
but not in an active fashion. This may imply that a resource of the
Terminal is being used and may limit actions on the Terminal.
ACTIVE
public final static int ACTIVE
- The ACTIVE state indicates that a Terminal is actively part of a
telephone call. This usually implies that the party speaking on that
Terminal is party of the telephone call.
DROPPED
public final static int DROPPED
- The DROPPED state indicates that a particular Terminal has permanently
left the telephone call.
UNKNOWN
public final static int UNKNOWN
- The UNKNOWN state indicates that the implementation is unable to determine
the state of the TerminalConnection.
getState
public abstract int getState() throws PlatformException
- Returns the state of the TerminalConnection object.
- Returns:
- The current state of the TerminalConnection object.
- Throws: PlatformException
- A platform-specific exception occurred.
getTerminal
public abstract Terminal getTerminal() throws PlatformException
- Returns the Terminal associated with this TerminalConnection object.
A TerminalConnection's reference to its Terminal remains valid for
the lifetime of the object, even if the Terminal loses its references
to this TerminalConnection object. Also, this reference does not
change once the TerminalConnection object has been created.
- Returns:
- The Terminal object associated with this TerminalConnection.
- Throws: PlatformException
- A platform-specific exception occurred.
getConnection
public abstract Connection getConnection() throws PlatformException
- Returns the Connection object associated with this TerminalConnection.
A TerminalConnection's reference to the Connection remains valid
thoughout the lifetime of the TerminalConnection. Also, this reference
does not change once the TerminalConnection object has been created.
- Returns:
- The Connections associated with this TerminalConnection.
- Throws: PlatformException
- A platform-specific exception occurred.
answer
public abstract void answer() throws PrivilegeViolationException, ResourceUnavailableException, MethodNotSupportedException, InvalidStateException, PlatformException
- Answers a telephone call. The TerminalConnection object must be in the
TerminalConnection.RINGING state. A successful invocation of this method
results in the TerminalConnection moving from the
TerminalConnection.RINGING state into the TerminalConnection.ACTIVE state.
The Provider must be in the Provider.IN_SERVICE state in order for
this method to be valid. The Connection associated with this
TerminalConnection must also be in the Connection.ALERTING state, however
this condition is implied when the TerminalConnection is in the
TerminalConnection.RINGING state.
The pre-condition predicates for this method are:
- ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
- this.getState() == TerminalConnection.RINGING
- (this.getConnection()).getState() == Connection.ALERTING
The post-condition predicates for this method are, indicating the
successful completetion of this invocation:
- ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
- this.getState() == TerminalConnection.ACTIVE
- (this.getConnection()).getState() == Connection.CONNECTED
Note that because the way in which TerminalConnections are related to
Connections, when the TerminalConnection is in the
TerminalConnection.RINGING state, it must be associated with a Connetion
in the Connection.ALERTING state. Also, when this method returns, the
TerminalConnection is in the TerminalConnection.ACTIVE state, however
this implies that the associated Connection moves into the
Connection.CONNECTED state at the same time.
Also, if the ALERTING Connection has more than one Terminal, all of these
Terminals will have TerminalConnections which will be in the
TerminalConnection.RINGING state. What happens to these other
TerminalConnections when the answer() method is invoked depends
upon the configuration of the switch. Unfortunately, this configuration
cannot be determined in advanced. These other TerminalConnections may
either go into the TerminalConnection.PASSIVE state or the
TerminalConnection.DROPPED state.
The following events are reported to the application via the CallObserver
interface for the Call associated with this TerminalConnection when this
method successfully completes: a java.telephony.events.TermConnActiveEv
for this TerminalConnection, a java.telephony.events.ConnConnectedEv
for the Connection associated with this TerminalConnection, and either
java.telephony.events.TermConnPassiveEv or a
java.telephony.events.TermConnDroppedEv for the other Terminal
Connections associated with this TerminalConnection's Connection.
- Throws: PrivilegeViolationException
- The application did not have
proper authority to answers the telephone call.
- Throws: ResourceUnavailableException
- The neccessary resources to
answer the telephone call were not available when the method was invoked.
- Throws: MethodNotSupportedException
- This method is currently not
supported by this implementation.
- Throws: InvalidStateException
- An object was not in the proper state,
violating the pre-conditions of this method.
- Throws: PlatformException
- A platform-specific exception occurred.
- See Also:
- TermConnActiveEv, TermConnPassiveEv, , ConnConnectedEv
getTerminalConnectionCapabilities
public abstract TerminalConnectionCapabilities getTerminalConnectionCapabilities(Terminal terminal,
Address address) throws InvalidArgumentException, PlatformException
- Gets the TerminalConnectionCapabilities object with respect to a Terminal and an
Address.
If null is passed as a Terminal parameter, the general/provider-wide Terminal Connection
capabilities are returned.
All Packages Class Hierarchy This Package Previous Next Index