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.

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.

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,

Variable Index

 o ACTIVE
The ACTIVE state indicates that a Terminal is actively part of a telephone call.
 o DROPPED
The DROPPED state indicates that a particular Terminal has permanently left the telephone call.
 o IDLE
The IDLE state is the initial state for all TerminalConnection objects.
 o PASSIVE
The PASSIVE state indicates that a Terminal is part of a telephone call but not in an active fashion.
 o RINGING
The RINGING state indicates the a Terminal is ringing, indicating that the Terminal has an incoming Call.
 o UNKNOWN
The UNKNOWN state indicates that the implementation is unable to determine the state of the TerminalConnection.

Method Index

 o answer()
Answers a telephone call.
 o getConnection()
Returns the Connection object associated with this TerminalConnection.
 o getState()
Returns the state of the TerminalConnection object.
 o getTerminal()
Returns the Terminal associated with this TerminalConnection object.
 o getTerminalConnectionCapabilities(Terminal, Address)
Gets the TerminalConnectionCapabilities object with respect to a Terminal and an Address.

Variables

 o IDLE
  public final static int IDLE
The IDLE state is the initial state for all TerminalConnection objects.
 o RINGING
  public final static int RINGING
The RINGING state indicates the a Terminal is ringing, indicating that the Terminal has an incoming Call.
 o 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.
 o 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.
 o DROPPED
  public final static int DROPPED
The DROPPED state indicates that a particular Terminal has permanently left the telephone call.
 o UNKNOWN
  public final static int UNKNOWN
The UNKNOWN state indicates that the implementation is unable to determine the state of the TerminalConnection.

Methods

 o 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.
 o 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.
 o 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.
 o 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:

  1. ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
  2. this.getState() == TerminalConnection.RINGING
  3. (this.getConnection()).getState() == Connection.ALERTING

The post-condition predicates for this method are, indicating the successful completetion of this invocation:

  1. ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
  2. this.getState() == TerminalConnection.ACTIVE
  3. (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

 o 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