call.java

Java Telephony API .java程序

/*
#pragma ident "@(#)Call.java	1.2      96/11/02     SMI"

 * Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Permission to use, copy, modify, and distribute this software
 * and its documentation for NON-COMMERCIAL purposes and without
 * fee is hereby granted provided that this copyright notice
 * appears in all copies. Please refer to the file "copyright.html"
 * for further important copyright and licensing information.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
 * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
 * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
 */

package java.telephony;
import  java.telephony.capabilities.CallCapabilities;

/**
 * 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.
 * <p>
 * Applications create instances of a Call object with the
 * <EM>Provider.createCall()</EM> 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.
 * <p>
 * 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.
 * <p>
 * A Call object in the Call.IDLE state has zero Connections associated with it.
 * All Call objects begin in the Call.IDLE state.
 * <p>
 * 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 <EM>Call.connect()</EM> method.
 * <p>
 * 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 <EM>Provider.getCalls()</EM>.
 * <p>
 * The predicates for the Call states are as follows. The purpose of the
 * predicates is to states truths about each Call state.
 * <p>
 * The IDLE state (this.getState() == Call.IDLE)
 * <OL>
 * <LI>this.getConnections() == null
 * </OL>
 * <p>
 * The ACTIVE state (this.getState() == Call.ACTIVE)
 * <OL>
 * <LI>Let Connection conn[] = this.getConnections()
 * <LI>conn != null && conn.length >= 1
 * <LI>For all i, conn[i].getState() != Connection.DISCONNECTED
 * </OL>
 * <p>
 * The INVALID state (this.getState() == Call.INVALID)
 * <OL>
 * <LI>this.getConnections() == null
 * </OL>
 * <p>
 * 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.
 * <p>
 * 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
 * <EM>Call.addObserver()</EM> to begin the delivery of events to that
 * observer.
 * <p>
 * @see java.telephony.CallObserver 
 */

public interface Call {

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


  /**
   * 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.
   * <p>
   * The pre-conditions for this method are listed below:
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * </OL>
   * <p>
   * The post-conditions for this method are listed below:
   * <OL>
   * <LI>Let Connectionp[] conn = Call.getConnections()
   * <LI>if this.getState() == Call.IDLE then conn = null
   * <LI>if this.getState() == Call.INVALID then conn = null
   * <LI>if this.getState() == Call.ACTIVE then conn.length >= 1
   * <LI>For all i, conn[i].getState() != Connection.DISCONNECTED
   * </OL>
   * <p>
   * @return An array of the Connections associated with the call.
   * @exception InvalidStateException The Provider is not in the 
   * Provider.IN_SERVICE state.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Connection[] getConnections()
    throws InvalidStateException, 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.
   * <p>
   * @return The Provider associated with the call.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Provider getProvider()
    throws PlatformException;


  /**
   * Returns the current state of the telephone call. The state will be
   * one of the state constants defined above.
   * <p>
   * @return The current state of the call, either IDLE, ACTIVE, or INVALID.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public int getState()
    throws 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.
   * <p>
   * 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.
   * <p>
   * 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.
   * <p>
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * <LI>this.getState() == Call.IDLE
   * </OL>
   * <p>
   * 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 <EM>Call.connect()</EM> returns.
   * <p>
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * <LI>this.getState() == Call.ACTIVE
   * <LI>Let Connection c[] = this.getConnections()
   * <LI>c.length == 2
   * <LI>c[0].getState() == Connection.IDLE
   * <LI>c[1].getState() == Connection.IDLE
   * </OL>
   * <p>
   * 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 <EM>Call.connect</EM> method. These scenarios just
   * represent two typical scenarios.
   * <p>
   * Scenario 1: The "normal" operation of this method, where the result is
   * two ends participating in an active telephone call.
   * <p>
   * <OL>
   * <LI>The Call.connect() is method invoked with the given arguments.
   * <LI>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.
   * <p>
   *    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.
   * <p>
   *    The following events are delivered to the application via a
   *    CallObserver on this Call: a <EM>java.telephony.events.CallActiveEv</EM>, a
   *    <EM>java.telephony.events.ConnCreatedEv</EM> for each of the two Connections
   *    created.
   * <p>
   * <LI>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.
   * <p>
   *    The following events are delivered to the application via a
   *    CallObserver on this Call: a <EM>java.telephony.events.ConnConnectedEv</EM>
   *    for the originating Connection, a
   *    <EM>java.telephony.events.TermConnCreatedEv</EM> for the new
   *    TerminalConnection created, and a
   *    <EM>java.telephony.events.TermConnActiveEv</EM> for the new Terminal
   *    Connection.
   * <p>
   *   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.
   * <p>
   *   Additional events are delivered because of the above paragraph: a
   *   <EM>java.telephony.events.TermConnCreateEv</EM> for all additional
   *   Terminal Connections created, and a