Interface java.telephony.callcontrol.CallControlTerminalConnection
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.telephony.callcontrol.CallControlTerminalConnection

public interface CallControlTerminalConnection
extends Object
extends TerminalConnection
The CallControlTerminalConnection interface extends the TerminalConnection interface. The CallControlTerminalConnection interface provides a greater level of detail for the TerminalConnection class states. Typically, an application will monitor either the TerminalConnection states or the CallControlTerminalConnection states. In this way, the CallControlTerminalConnection is to the TerminalConnection object as the CallControlConnection is to the Connection object.

The CallControlTerminalConnection state is obtained via the getCallControlState() method on this interface. Certain methods in the CallControlTerminal object require that the CallControlTerminalConnection be in a certain state.

When the TerminalConnection is in a certain state, it implies that the CallControlTerminalConnection state for the same object must be in one or a couple of states. This mapping is defined below. The states associated with the CallControlTerminalConnection are: RINGING, TALKING, HELD, BRIDGED, INUSE, and DROPPED. The following provides informal, real-world descriptions of each of these states:

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 has the same definition as in the TerminalConnection class. The phone is on-hook but the phone is ringing indicates there is an incoming call.

The TALKING state indicates that the phone is off-hook and the party is active and talking on the telephone call.

The HELD state indicates that a Terminal is part of a telephone call, but is on hold. Other Terminals may or may not also be in the HELD state. The core TerminalConnection state must be ACTIVE, and the core Connection state must be CONNECTED.

The BRIDGED state indicates that a Terminal is currently bridged into a telephone call. A Terminal may typically join a telephone call when it is bridged. A bridged Terminal is part of the telephone call, in that a resource is occupied on that Terminal, however is not strictly active in the telephone call. The core TerminalConnection state must be in the PASSIVE state.

The INUSE state indicates that a Terminal is part of a telephone call, but not actively so. It may not join this phone call, however the resource on the Terminal is currently in use. This state is similar to the BRIDGED state however, the Terminal may not join the call. The core TerminalConnection state must be in the PASSIVE state. The DROPPED state has the same definition as in the TerminalConnection class.

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 following chart describes the possible states in which the CallControlTerminalConnection state must be in, given the TerminalConnection state. The TerminalConnection states are listed on the left, and the CallControlTerminalConnection states on the right.


Variable Index

 o BRIDGED
The BRIDGED state variable.
 o DROPPED
The DROPPED state variable.
 o HELD
The HELD state variable.
 o IDLE
The IDLE state variable.
 o INUSE
The INUSE state variable.
 o RINGING
The RINGING state variable.
 o TALKING
The TALKING state variable.
 o UNKNOWN
The UNKNOWN state variable.

Method Index

 o getCallControlState()
Returns the call control state of the TerminalConnection object.
 o hold()
Places a TerminalConnection on hold with respect to the telephone call of which it is a part.
 o join()
Makes a TerminalConnection which is bridged with a telephone call active on that telephone call.
 o leave()
Takes a TerminalConnection which is active in a telephone call and places it back into the bridged state.
 o unhold()
Takes a TerminalConnection off hold with respect to the telephone call of which it is a part.

Variables

 o IDLE
  public final static int IDLE
The IDLE state variable.
 o RINGING
  public final static int RINGING
The RINGING state variable.
 o TALKING
  public final static int TALKING
The TALKING state variable.
 o HELD
  public final static int HELD
The HELD state variable.
 o BRIDGED
  public final static int BRIDGED
The BRIDGED state variable.
 o INUSE
  public final static int INUSE
The INUSE state variable.
 o DROPPED
  public final static int DROPPED
The DROPPED state variable.
 o UNKNOWN
  public final static int UNKNOWN
The UNKNOWN state variable.

Methods

 o getCallControlState
  public abstract int getCallControlState() throws PlatformException
Returns the call control state of the TerminalConnection object.

Returns:
The current state of the TerminalConnection object.
Throws: PlatformException
A platform-specific exception occurred.
 o hold
  public abstract void hold() throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Places a TerminalConnection on hold with respect to the telephone call of which it is a part. Many TerminalConnections may be involved in a telephone call which are part of the same address, and any one of them may go "on hold" at any time provided they are active in the telephone call. This method returns successfully when the TerminalConnection has been placed on hold, otherwise an exception is thrown to signal an error.

This TerminalConnection must be in the TALKING state and the Provider must be IN_SERVICE. The pre-conditions are given below:

  1. (this.getTerminal()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == TALKING

The post-conditions for this method are as follows:

  1. (terminal.getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == HELD

Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o unhold
  public abstract void unhold() throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Takes a TerminalConnection off hold with respect to the telephone call of which it is a part. Many Terminals may be involved in a telephone call which are part of the same address, and any one of them may go "on hold" at any time provided they are active in the telephone call. This method returns successfully once the TerminalConnection has been taken off of hold, otherwise an exception is thrown to signal an error.

This TerminalConnection must be in the HELD state and the Provider must be IN_SERVICE. These pre-conditions are given below:

  1. ((this.getTerminal()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == HELD

The post-conditions for this method are:

  1. ((this.getTerminal()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == TALKING

Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o join
  public abstract void join() throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Makes a TerminalConnection which is bridged with a telephone call active on that telephone call. Bridging situations exists when another Terminal which shares an address with this Terminal is active on a telephone call. This method returns successful when the Terminal has been made active on this telephone call, otherwise an exception is thrown to signal an error.

This TerminalConnection must be in the BRIDGED state and the Provider must be IN_SERVICE. These pre-conditions are given below:

  1. ((this.getTerminal()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == BRIDGED

The post-conditions for this method are:

  1. ((this.getTerminal()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == TALKING

Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o leave
  public abstract void leave() throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Takes a TerminalConnection which is active in a telephone call and places it back into the bridged state. Bridging situations exists when another Terminal which shares an address with this Terminal is active on a telephone call. If this Terminal is the only remaining Terminal which is active on the telephone call with respect to its Address, then the Connection to that address moves into the DISCONNECTED state as well as all of the associated TerminalConnection objects.

This TerminalConnection object must be in the TALKING state and the Provider must be IN_SERVICE. These pre-conditions are given below:

  1. ((this.getTerminal()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == TALKING

The post-conditions for this method are as follows. Note that there are two possible outcomes: one in which this TerminalConnection moves back into the BRIDGED state and one in which the entire Connection moves to DISCONNECTED if it is the only remanining active TerminalConnection.

  1. ((this.getTerminal()).getProvider()).getState() == IN_SERVICE
  2. if for all (this.getTerminal()).getTerminalConnections(), this TerminalConnection is the only one in the non-BRIDGED or non-DROPPED state, then this.getState() == DROPPED and this.getConnection() == DISCONNECTED.
  3. if for all (this.getTerminal()).getTerminalConnections(), there is exists a TerminalConnection in the TALKING state besides this TerminalConnection, then this.getState() == BRIDGED

Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.

All Packages  Class Hierarchy  This Package  Previous  Next  Index