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

Interface java.telephony.Call

public interface Call
extends Object
A Call represents a telephone call. A call can have zero or more Connections: a two-party call has two connections, and a conference call can have three or more connections. Each Connection represents an association between the Call and an Address.

Applications create instances of a Call object with the Provider.createCall() method. After this method returns, the returned Call object has zero Connections associated with it and is in the Call.IDLE state. The Call object maintains a reference to its Provider object throughout the lifetime of the Call object. This Provider object does not change throughout the lifetime of the Call object.

Call objects maintain an array of Connection objects which are associated with the Call. A Call maintains a reference to a Connection object only if it is not in the Connection.DISCONNECTED state. Therefore, if a Call has a reference to a Connection, then that implies the Connection is not in the Connection.DISCONNECTED state. When Connections in a Call move into the Connection.DISCONNECTED state (e.g. when a party hangs up), the Call loses the reference to that Connection object.

A Call object in the Call.IDLE state has zero Connections associated with it. All Call objects begin in the Call.IDLE state.

The Call object is in the Call.ACTIVE state when it has one or more Connections associated with it. A Call may have Connections associated with it through some external action or through an application successfully invoking the Call.connect() method.

The Call object is in the Call.INVALID state when it has zero Connections associated with it, but previously has Connections associated with it. A Call in Call.INVALID state once had Connections which all have moved to the Connection.DISCONNECTED state. A Call object in the Call.INVALID state cannot be used further and should be deferenced by the application for garbage collection. The Provider also loses its reference to the Call object when the Call moves into the Call.INVALID state. This implies that the Call object is no longer returns by Provider.getCalls().

The predicates for the Call states are as follows. The purpose of the predicates is to states truths about each Call state.

The IDLE state (this.getState() == Call.IDLE)

  1. this.getConnections() == null

The ACTIVE state (this.getState() == Call.ACTIVE)

  1. Let Connection conn[] = this.getConnections()
  2. conn != null && conn.length >= 1
  3. For all i, conn[i].getState() != Connection.DISCONNECTED

The INVALID state (this.getState() == Call.INVALID)

  1. this.getConnections() == null

When the call is in the IDLE state, the call can be initialized by setting optional parameters that influence the subsequent behavior of the call. Various JTAPI extension packages provide methods to set such parameters.

The CallObserver interface reports all events pertaining to the Call object. This not only includes state changes in the Call object, but also includes state changes in all Connections associated with the Call object, and state changes in all TerminalConnections associated with those Connections. The CallObserver interface also reports when new Connections and TerminalConnections are created in the Call. Applications instantiate an object which implements the CallObserver interface and uses the Call.addObserver() to begin the delivery of events to that observer.

See Also:
CallObserver

Variable Index

 o ACTIVE
The Call.ACTIVE state indicates the Call has one or more Connections, none of which are in the Connection.DISCONNECTED state.
 o IDLE
The Call.IDLE state indicates the Call has zero Connections.
 o INVALID
The Call.INVALID state indicates the Call has lost all of its Connections.

Method Index

 o addObserver(CallObserver)
Adds an observer to the Call.
 o connect(Terminal, Address, String)
Connect a pair of connections to a call.
 o getCallCapabilities(Terminal, Address)
Gets the CallCapabilities object with respect to a Terminal and an Address.
 o getConnections()
Returns the Connections associated with this call.
 o getObservers()
Returns a list of all CallObservers associated with this call object.
 o getProvider()
Returns the provider associated with the call.
 o getState()
Returns the current state of the telephone call.
 o removeObserver(CallObserver)
Removes the given observer from the Call.

Variables

 o IDLE
  public final static int IDLE
The Call.IDLE state indicates the Call has zero Connections. It is the initial state of all Call objects.
 o ACTIVE
  public final static int ACTIVE
The Call.ACTIVE state indicates the Call has one or more Connections, none of which are in the Connection.DISCONNECTED state.
 o INVALID
  public final static int INVALID
The Call.INVALID state indicates the Call has lost all of its Connections. A Call in this state cannot be used further.

Methods

 o getConnections
  public abstract Connection[] getConnections() throws InvalidStateException, PlatformException
Returns the Connections associated with this call. Because of the conditions mentioned above, none of the Connections returned will be in the Connection.DISCONNECTED state. Also, if the Call is in the Call.IDLE state or the Call.INVALID state, this method returns null. Otherwise, it returns one or more Connections. The Provider must be in the Provider.IN_SERVICE state for this method to be valid.

The pre-conditions for this method are listed below:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE

The post-conditions for this method are listed below:

  1. Let Connectionp[] conn = Call.getConnections()
  2. if this.getState() == Call.IDLE then conn = null
  3. if this.getState() == Call.INVALID then conn = null
  4. if this.getState() == Call.ACTIVE then conn.length >= 1
  5. For all i, conn[i].getState() != Connection.DISCONNECTED

Returns:
An array of the Connections associated with the call.
Throws: InvalidStateException
The Provider is not in the Provider.IN_SERVICE state.
Throws: PlatformException
A platform-specific exception occurred.
 o getProvider
  public abstract Provider getProvider() throws PlatformException
Returns the provider associated with the call. The Provider object does not change throughout the lifetime of the Call object. This method returns the same value no matter what the Call state is. If the Call state is Call.INVALID, this method returns the proper Provider object, however the Provider object has lost its reference (see Provider.getCalls()) to this Call object to faciliate the garbage collection of the Call object.

Returns:
The Provider associated with the call.
Throws: PlatformException
A platform-specific exception occurred.
 o getState
  public abstract int getState() throws PlatformException
Returns the current state of the telephone call. The state will be one of the state constants defined above.

Returns:
The current state of the call, either IDLE, ACTIVE, or INVALID.
Throws: PlatformException
A platform-specific exception occurred.
 o connect
  public abstract Connection[] connect(Terminal origterm,
                                       Address origaddr,
                                       String dialedDigits) throws ResourceUnavailableException, PrivilegeViolationException, InvalidPartyException, InvalidArgumentException, InvalidStateException, MethodNotSupportedException, PlatformException
Connect a pair of connections to a call. The Call must be in the Call.IDLE state and its Provider must be in the Provider.IN_SERVICE state. Because the Call must be in the Call.IDLE state for the success of this method, the Call must by definition have no existing Connections associated with it.

The first argument is the originating Terminal for the telephone call. The second argument represents the Address from which the call is placed. The originating address must be one of the addresses associated with the originating Terminal, otherwise an exception is thrown. The third argument is the string address to which the phone call is being placed. This is also known as the destination address and must be a valid and complete telephone address.

The pre-condition predicates for this method indicate which statements must be true in order for this method to succeed. However, these predicates do not guarantee the success of this method.

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. this.getState() == Call.IDLE

The post-condition predicates for the Call.connect() method are as follows. Note that the eventual outcome of this method is described by a number of scenarios below. These post-conditions only reflect the state immediately after the Call.connect() returns.

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. this.getState() == Call.ACTIVE
  3. Let Connection c[] = this.getConnections()
  4. c.length == 2
  5. c[0].getState() == Connection.IDLE
  6. c[1].getState() == Connection.IDLE

Two scenarios of the eventual outcome of this method are given below. Note, what is termed the "normal" operation of this method results in an active telephone call. A sequence of discrete call model changes is given by a list of discrete steps each labelled with a number. Changes in the call model falling under the same number are seen by the application as happening at once. These two scenarios do not represent all the possible outcomes of the Call.connect method. These scenarios just represent two typical scenarios.

Scenario 1: The "normal" operation of this method, where the result is two ends participating in an active telephone call.

  1. The Call.connect() is method invoked with the given arguments.
  2. Exactly two connections are created, each in the Connection.IDLE state. The first connection created represents the originating end of the call. The second connection created represents the destination end of the call.

    The Call.connect() method returns, returning a two-element array of Connections. The first element at index 0 represents the originating Connection. The second element at index 1 represents the destination Connection. Both Connections are in the Connection.IDLE state.

    The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.CallActiveEv, a java.telephony.events.ConnCreatedEv for each of the two Connections created.

  3. Once the Provider begins to place the telephone call, the originating Connection moves from the Connection.IDLE state into the Connection.CONNECTED state. A TerminalConnection is created in the TerminalConnection.ACTIVE state between the originating Terminal and the Call.

    The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.ConnConnectedEv for the originating Connection, a java.telephony.events.TermConnCreatedEv for the new TerminalConnection created, and a java.telephony.events.TermConnActiveEv for the new Terminal Connection.

    Depending upon the configuration of the switch, additional TerminalConnections may be created. These TerminalConnections will be associated with Terminals which have the originating Address as one of their Addresseses. Unfortunately, there is no way for the implementation to tell which TerminalConnections will be created in advance, only that the number cannot be greater than the number of Terminals associated with the originating Address and each TerminalConnection must go to one of those Terminals associated with the originating Address. If such a Terminal Connection is created, it will be in the TerminalConnection.PASSIVE state.

    Additional events are delivered because of the above paragraph: a java.telephony.events.TermConnCreateEv for all additional Terminal Connections created, and a java.telephony.events.TermConnPassiveEv for each of those Terminal Connections.

  4. The destination Connection moves from the Connection.IDLE state into the TerminalConnection.INPROGRESS state.

    The following events are delivered to the application via the CallObserver interface: a java.telephony.events.ConnInProgressEv for the destination Connection.

  5. The destination Connection moves from the Connection.INPROGRESS state to the Connection.ALERTING state. TerminalConnection objects are created between the Call and every Terminal object associated with the destination Address in the TerminalConnection.RINGING state.

    The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.ConnAlertingEv for the destination Connection, a java.telephony.events.TermConnCreatedEv for all Terminal Connections created to Terminals with the destination Address, a java.telephony.events.TermConnRingingEv for all those new TerminalConnections.

    The following events are delivered to the application via the CallObserver on this Call: a java.telephony.events.ConnConnectedEv for the destination Connection, and a java.telephony.events.TermConnActiveEv for the TerminalConnection which answered the telephone call.

    For all other TerminalConnections in the TerminalConnection.RINGING state on the destination side, either one of two things will happen depending upon the configuration of the switch. Unfortunately, the implementation is unable to determine the behavior of the switch beforehand. In one situation, these TerminalConnections move from the TerminalConnection.RINGING state to the TerminalConnection.PASSIVE state. In the second situation, these TerminalConnections move from the TerminalConnection.RINGING state to the TerminalConnection.DROPPED state.

    Because of the paragraph above, the following events will be delivered to the application via the CallObserver interface on this Call: a java.telephony.events.TermConnPassiveEv in one situation, or a java.telephony.events.TermConnDroppedEv in the other situation.

The post-condition predicates for scenario 1 are as follows. These post-conditions state what is true about the call model after the final step of scenario 1 completes.

  1. this.getState() == Call.ACTIVE
  2. (this.getProvider()).getState() == Provider.IN_SERVICE
  3. Let Connection c[] = this.getConnections()
  4. c[0].getState == Connection.CONNECTED
  5. c[1].getState == Connection.CONNECTED
  6. Let TerminalConnection origtc[] = c[0].getTerminalConnections()
  7. There exists an i, such that origtc[i].getState() == TerminalConnection.ACITVE.
  8. Let TerminalConnection desttc[] = c[1].getTerminalConnections()
  9. There exists an i, such that desttc[i].getState() == TerminalConnection.ACTIVE.

Scenario 2: The desired telephone call is placed however the completion of the call is impossible because of a failure. For example, this scenario will occur if the destination address is busy. In this scenario the destination Connection never reaches the ALERTING state. (i.e. the destination party is never alerted to this telephone call)

  1. The Call.connect() is method invoked with the given arguments.
  2. Exactly two connections are created, each in the Connection.IDLE state. The first connection created represents the originating end of the call. The second connection created represents the destination end of the call.

    The Call.connect() method returns, returning a two-element array of Connections. The first element at index 0 represents the originating Connection. The second element at index 1 represents the destination Connection. Both Connections are in the Connection.IDLE state.

    The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.CallActiveEv, a java.telephony.events.ConnCreatedEv for each of the two Connections created.

  3. Once the Provider begins to place the telephone call, the originating Connection moves from the Connection.IDLE state into the Connection.CONNECTED state. A TerminalConnection is created in the TerminalConnection.ACTIVE state between the originating Terminal and the Call.

    The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.ConnConnectedEv for the originating Connection, a java.telephony.events.TermConnCreatedEv for the new TerminalConnection created, and a java.telephony.events.TermConnActiveEv for the new Terminal Connection.

    Depending upon the configuration of the switch, additional TerminalConnections may be created. These TerminalConnections will be associated with Terminals which have the originating Address as one of their Addresseses. Unfortunately, there is no way for the implementation to tell which TerminalConnections will be created in advance, only that the number cannot be greater than the number of Terminals associated with the originating Address and each TerminalConnection must go to one of those Terminals associated with the originating Address. If such a Terminal Connection is created, it will be in the TerminalConnection.PASSIVE state.

    Additional events are delivered because of the above paragraph: a java.telephony.events.TermConnCreateEv for all additional Terminal Connections created, and a java.telephony.events.TermConnPassiveEv for each of those Terminal Connections.

  4. The destination Connection moves from the Connection.IDLE state into the TerminalConnection.INPROGRESS state.

    The following events are delivered to the application via the CallObserver interface: a java.telephony.events.ConnInProgressEv for the destination Connection.

  5. The destination Connection moves from the Connection.INPROGRESS state into the Connection.FAILED state.

    The following events are delivered to the application via the CallObserver interface: a java.telephony.events.ConnFailedEv for the destination Connection.

The post condition predicates for scenario 2 are as follows. These post-conditions state what is true about the call model after the final step of scenario 1 completes.

  1. this.getState() == Call.ACTIVE
  2. (this.getProvider()).getState() == Provider.IN_SERVICE
  3. Let Connection c[] = this.getConnections()
  4. c[0].getState() == Connection.CONNECTED
  5. c[1].getState() == Connection.FAILED
  6. Let TerminalConnection origtc[] = c[0].getTerminalConnections()
  7. There exists an i, such that origtc[i].getState() == TerminalConnection.ACITVE.

Parameters:
origterm - The originating Terminal for this telephone call.
origaddr - The originating Address for this telephone call.
destaddr - The destination Address for this telephone call.
Throws: ResourceUnavailableException
An internal resource neccessary for placing the phone call is unavailable.
Throws: PrivilegeViolationException
The application does not have the proper authority to place a telephone call.
Throws: InvalidPartyException
Either the originator or the destination does not represent a valid party required to place a telephone call.
Throws: InvalidArgumentException
An argument provided is not valid either by not providing enough information for connect() or is inconsistent with another argument.
Throws: InvalidStateException
Some object required by this method is not is a valid state as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
The implementation does not support this method.
Throws: PlatformException
A platform-specific exception occurred.
See Also:
CallActiveEv, ConnAlertingEv, ConnConnectedEv, ConnCreatedEv, ConnInProgressEv, TermConnActiveEv, TermConnCreatedEv, TermConnDroppedEv, TermConnPassiveEv, TermConnRingingEv

 o addObserver
  public abstract void addObserver(CallObserver observer) throws ResourceUnavailableException, PlatformException
Adds an observer to the Call. The CallObserver reports all Call-related state changes as events as well as all Connection state changes and TerminalConnection state changes. The Call object will report events to this CallObserver object for the lifetime of the Call object or until the observer is removed with the Call.removeObserver() method or until the Call moves into the Call.INVALID state. The Call must be either in the Call.IDLE state or Call.ACTIVE state as a pre-condition for this method.

By default, when an observer is added to a telephone call, the first batch of events may be a "snapshot". That is, if the observer was added certain state changes in the call, the first batch of events will inform the application of the current state of the call. Note that these snapshot events do NOT provide a history of all events on the call. Rather they provide the minimum neccessary event to bring the application up-to-date with the current state of the call.

If an application attempts to add an instance of an observer already present on this Call, then repeated attempts to add the instance of the observer will silently fail, i.e. multiple instances of an observer are not added and no exception will be thrown.

There are no pre-conditions for this method.

The post-condition predicates for this method are:

  1. observer is an element of this.getObservers()

Parameters:
observer - The observer being added.
Throws: ResourceUnavailableException
The resource limit for the numbers of observers has been exceeded.
Throws: PlatformException
A platform-specific exception occurred.
 o getObservers
  public abstract CallObserver[] getObservers() throws PlatformException
Returns a list of all CallObservers associated with this call object. If no observers are on this Call object, then this method returns null.

There are no pre-conditions for this method.

The post-conditions for this method are:

  1. Let CallObserver[] obs = this.getObservers()
  2. obs == null or obs.length >= 1

Returns:
An array of CallObserver objects associated with this Call.
Throws: PlatformException
A platform-specific exception occurred.
 o removeObserver
  public abstract void removeObserver(CallObserver observer) throws PlatformException
Removes the given observer from the Call. If successful, the observer will no longer receive events generated by this call object.

Also, if an observer is not part of the Call, then this method fails silently, i.e. no observer is removed an no exception is thrown.

There are no pre-conditions for this method.

The post-condition predicates for this method are:

  1. observer is not an element of this.getObservers()

Parameters:
observer - The observer which is being removed.
Throws: PlatformException
A platform-specific exception occurred.
 o getCallCapabilities
  public abstract CallCapabilities getCallCapabilities(Terminal terminal,
                                                       Address address) throws InvalidArgumentException, PlatformException
Gets the CallCapabilities object with respect to a Terminal and an Address. If null is passed as a Terminal parameter, the general/provider-wide Call capabilities are returned.


All Packages  Class Hierarchy  This Package  Previous  Next  Index