javax.telephony.callcontrol
Interface CallControlTerminalConnection

All Superinterfaces:

TerminalConnection

public interface CallControlTerminalConnection

extends TerminalConnection

Introduction

The CallControlTerminalConnection interface extends the core TerminalConnection interface with additional features and greater detail about the TerminalConnection state. Applications may query a TerminalConnection object using the instanceof operator to see whether it supports this interface.

CallControlTerminalConnection State

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

Below is a description of each CallControlTerminalConnection 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 CallControlTerminalConnection state. Some of these states are identical to those defined in the core package.

CallControlTerminalConnection.IDLE	This state has the same definition as in the core package. It is the initial CallControlTerminalConnection state for all new TerminalConnection objects. TerminalConnections typically do not stay in this state for long, quickly transitioning to another state.
CallControlTerminalConnection.RINGING	This state has the same definition as in the core package. It indicates that the associated Terminal is ringing and has an incoming telephone call.
CallControlTerminalConnection.TALKING	This state indicates that the Terminal is actively part of a Call, is typically "off-hook", and the party is communicating on the telephone call.
CallControlTerminalConnection.HELD	This state indicates that a Terminal is part of a Call, but is on hold. Other Terminals which are on the same Call and associated with the same Connection may or may not also be in this state.
CallControlTerminalConnection.BRIDGED	This state indicates that a Terminal is currently bridged into a Call. A Terminal may typically join a Call when it is bridged. A bridged Terminal is part of the telephone call, but not active. Typically, some hardware resource is occupied while a Terminal is bridged into a Call.
CallControlTerminalConnection.INUSE	This state indicates that a Terminal hardware resource is currently in use. The terminal is not available for the Call associated with this Terminal Connection, that is the Terminal may not join the call. This state is similar to the CallControlTerminalConnection.BRIDGED state except that the Terminal may not join the Call.
CallControlTerminalConnection.DROPPED	This state has the same definition as in the core package. It indicates that a particular Terminal has permanently left the Call.
CallControlTerminalConnection.UNKNOWN	This state has the same definition as in the core package. It indicates that the implementation is unable to determine the state of the TerminalConnection. TerminalConnections may transition into and out of this state at any time.

State Transitions

Similar to the TerminalConnection state transition diagram, the CallControlTerminalConnection state must transition according to the rules illustrated in the finite state diagram below. The implementation must guarantee that the CallControlTerminalConnection state abides by this transition diagram.

The asterisk next to a state transition, as in the core package, implies a transition to/from another state as designated by the direction of the transition arrow.

Core vs. CallControl Package States

There is a strong relationship between the TerminalConnection states and the CallControlTerminalConnection states. If an implementation supports the call control package, it must ensure this relationship is properly maintained.

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

The following table outlines the relationship between the core package TerminalConnection states and the call control package TerminalConnection states.

If the call control package state is...	then the core package state must be...
CallControlTerminalConnection.IDLE	TerminalConnection.IDLE
CallControlTerminalConnection.RINGING	TerminalConnection.RINGING
CallControlTerminalConnection.TALKING	TerminalConnection.ACTIVE
CallControlTerminalConnection.HELD	TerminalConnection.ACTIVE
CallControlTerminalConnection.INUSE	TerminalConnection.PASSIVE
CallControlTerminalConnection.BRIDGED	TerminalConnection.PASSIVE
CallControlTerminalConnection.DROPPED	TerminalConnection.DROPPED
CallControlTerminalConnection.UNKNOWN	TerminalConnection.UNKNOWN

Observers and Events

All events pertaining to the CallControlTerminalConnection interface are reported via the CallObserver.callChangedEvent() method. The application observer object must also implement the CallControlCallObserver interface to express interest in the call control package events. Applications receive TerminalConnection-related events in the call control package when the call control state changes.

Observers which are registered on a Call receive events when the CallControlTerminalConnection state changes. Note that when the CallControlTerminalConnection state changes, it sometimes results in the TerminalConnection state changing (according to the table above). In these instances, both the proper call control and core package events are delivered to the observer.

The CallControlTerminalConnection state events defined in this package are: CallCtlTermConnBridgedEv, CallCtlTermConnDroppedEv, CallCtlTermConnHeldEv, CallCtlTermConnInUseEv, CallCtlTermConnRingingEv, CallCtlTermConnTalkingEv, and CallCtlTermConnUnknownEv.

See Also:

TerminalConnection, CallObserver, CallControlCallObserver, CallCtlCallEv, CallCtlTermConnEv, CallCtlTermConnRingingEv, CallCtlTermConnTalkingEv, CallCtlTermConnHeldEv, CallCtlTermConnBridgedEv, CallCtlTermConnInUseEv, CallCtlTermConnDroppedEv, CallCtlTermConnUnknownEv

Field Summary

static int	BRIDGED The CallControlTerminalConnection.BRIDGED state indicates that a Terminal is currently bridged into a Call.
static int	DROPPED The CallControlTerminalConnection.DROPPED state has the same definition as in the core package.
static int	HELD The CallControlTerminalConnection.HELD state indicates that a Terminal is part of a Call, but is on hold.
static int	IDLE The CallControlTerminalConnection.IDLE state has the same definition as in the core package.
static int	INUSE The CallControlTerminalConnection.INUSE state indicates that a Terminal is part of a Call, but is not active.
static int	RINGING The CallControlTerminalConnection.RINGING state has the same definition as in the core package.
static int	TALKING The CallControlTerminalConnection.TALKING state indicates that a Terminal is actively part of a Call, is typically "off-hook", and the party is communicating on the telephone call.
static int	UNKNOWN The CallControlTerminalConnection.UNKNOWN state has the same definition as in the core package.

Fields inherited from interface javax.telephony.TerminalConnection

ACTIVE, PASSIVE

Method Summary

int	getCallControlState() Returns the call control state of the TerminalConnection.
void	hold() Places a TerminalConnection on hold with respect to the Call of which it is a part.
void	join() Makes a currently bridged TerminalConnection active on a Call.
void	leave() Places a currently active TerminalConnection in a bridged state on a Call.
void	unhold() Takes a TerminalConnection off hold with respect to the Call of which it is a part.

Methods inherited from interface javax.telephony.TerminalConnection

answer, getCapabilities, getConnection, getState, getTerminal, getTerminalConnectionCapabilities

Field Detail

IDLE

public static final int IDLE

The CallControlTerminalConnection.IDLE state has the same definition as in the core package. It is the initial CallControlTerminalConnection state for all new TerminalConnections. TerminalConnections typically do not stay in this state for long, but quickly transition to another state.

RINGING

public static final int RINGING

The CallControlTerminalConnection.RINGING state has the same definition as in the core package. It indicates that the associated Terminal is ringing and has an incoming telephone call.

TALKING

public static final int TALKING

The CallControlTerminalConnection.TALKING state indicates that a Terminal is actively part of a Call, is typically "off-hook", and the party is communicating on the telephone call.

HELD

public static final int HELD

The CallControlTerminalConnection.HELD state indicates that a Terminal is part of a Call, but is on hold. Other Terminals which are on the same Call and associated with the same Connection may or may not also be in this state.

BRIDGED

public static final int BRIDGED

The CallControlTerminalConnection.BRIDGED state indicates that a Terminal is currently bridged into a Call. A Terminal may typically join a telephone call when it is bridged. A bridged Terminal is part of the telephone call, but not active. Typically, some hardware resource is occupied while a Terminal is bridged into a Call.

INUSE

public static final int INUSE

The CallControlTerminalConnection.INUSE state indicates that a Terminal is part of a Call, but is not active. It may not Call, however the resource on the Terminal is currently in use. This state is similar to the CallControlTerminalConnection.BRIDGED state however, the Terminal may not join the Call.

DROPPED

public static final int DROPPED

The CallControlTerminalConnection.DROPPED state has the same definition as in the core package. It indicates that a particular Terminal has permanently left the Call.

UNKNOWN

public static final int UNKNOWN

The CallControlTerminalConnection.UNKNOWN state has the same definition as in the core package. It indicates that the implementation is unable to determine the state of the TerminalConnection. TerminalConnections may transition into and out of this state at any time.

Method Detail

getCallControlState

public int getCallControlState()

Returns the call control state of the TerminalConnection. The return values will be one of the integer state constants defined above.

Returns:

The current call control state of the TerminalConnection.

hold

public void hold()
          throws InvalidStateException,
                 MethodNotSupportedException,
                 PrivilegeViolationException,
                 ResourceUnavailableException

Places a TerminalConnection on hold with respect to the Call of which it is a part. Many Terminals may be on the same Call and associated with the same Connection. Any one of them may go "on hold" at any time, provided they are active in the Call. The TerminalConnection must be in the CallControlTerminalConnection.TALKING state. This method returns when the TerminalConnection has moved to the CallControlTerminalConnection.HELD state, or until an error occurs and an exception is thrown.

Pre-conditions:

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

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlTerminalConnection.HELD
3. CallCtlTermConnHeldEv is delivered for this TerminalConnection

Throws:

InvalidStateException - Either the Provider is not "in service" or the TerminalConnection is not "talking".

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

CallCtlTermConnHeldEv

unhold

public void unhold()
            throws InvalidStateException,
                   MethodNotSupportedException,
                   PrivilegeViolationException,
                   ResourceUnavailableException

Takes a TerminalConnection off hold with respect to the Call of which it is a part. Many Terminals may be on the same Call and associated with the same Connection. Any one of them may go "on hold" at any time, provided they are active in the Call. The TerminalConnection must be in the CallControlTerminalConnection.HELD state. This method returns successfully when the TerminalConnection moves into the CallControlTerminalConnection.TALKING state or until an error occurs and an exception is thrown.

Pre-conditions:

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

Post-conditions:

1. ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlTerminalConnection.TALKING
3. CallCtlTermConnTalkingEv is delivered for this TerminalConnection

Throws:

InvalidStateException - Either the Provider is not "in service" or the TerminalConnection is not "held".

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

CallCtlTermConnTalkingEv

join

public void join()
          throws InvalidStateException,
                 MethodNotSupportedException,
                 PrivilegeViolationException,
                 ResourceUnavailableException

Makes a currently bridged TerminalConnection active on a Call. Other Terminals, which share the same Address as this Terminal, may be active on the same Call. This situation is known as bridging. The TerminalConnection must be in the CallControlTerminalConnection.BRIDGED state. This method returns which the TerminalConnection has moved to the CallControlTerminalConnection.TALKING state or until an error occurs and an exception is thrown.

Pre-conditions:

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

Post-conditions:

1. ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlTerminalConnection.TALKING
3. CallCtlTermConnTalkingEv/TermConnActiveEv is delivered for this TerminalConnection

Throws:

InvalidStateException - Either the Provider is not "in service" or the TerminalConnection is not "bridged".

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

TermConnActiveEv, CallCtlTermConnTalkingEv

leave

public void leave()
           throws InvalidStateException,
                  MethodNotSupportedException,
                  PrivilegeViolationException,
                  ResourceUnavailableException

Places a currently active TerminalConnection in a bridged state on a Call. Other Terminals, which share the same Address as this Terminal, may remain active on the same Call. This situation where Terminals share an Address on a call is known as bridging. The TerminalConnection on which this method is invoked must be in the CallControlTerminalConnection.TALKING state.

There are two possible outcomes of this method depending upon the number of remaining, active TerminalConnections on the Call. If there are other active TerminalConnections, then this TerminalConnection moves into the CallControlTerminalConnection.BRIDGED state and this method returns. If there are no other active TerminalConnections, then this TerminalConnection moves into the CallControlTerminalConnection.DROPPED state. Its associated Connection moves into the CallControlConnection.DISCONNECTED state, i.e. the entire endpoint leaves the telephone call. This method waits until one of these two outcomes occurs or until an error occurs and an exception is thrown.

Pre-conditions:

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

Post-conditions Outcome 1: There are no other active TerminalConnections on this Call (no others which are either "held" or "talking"

1. ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
2. Let connection = this.getConnection()
3. Let tc[] = connection.getTerminalConnections() before this method is invoked
4. tc[i].getCallControlState() == CallControlTerminalConnection.DROPPED, for all i
5. connection.getCallControlState() == CallControlConnection.DISCONNECTED
6. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for all tc[i]
7. CallCtlConnDisconnectedEv/ConnDisconnectedEv is delivered for connection

Post-conditions Outcome 2: There are other active TerminalConnections on this Call (others which are either "held" or "talking"

1. ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlTerminalConnection.BRIDGED
3. CallCtlTermConnBridgedEv/TermConnPassiveEv is delivered for this TerminalConnection

Throws:

InvalidStateException - Either the Provider is not "in service" or the TerminalConnection is not "talking".

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

TermConnPassiveEv, TermConnDroppedEv, ConnDisconnectedEv, CallCtlTermConnBridgedEv, CallCtlTermConnDroppedEv, CallCtlConnDisconnectedEv