terminalconnection.java

Java Telephony API .java程序

/*
#pragma ident "@(#)TerminalConnection.java	1.1      96/11/01     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.TerminalConnectionCapabilities;

/**
 * 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.
 * <p>
 * There are six states on the TerminalConnection object: IDLE, RINGING,
 * PASSIVE, ACTIVE, DROPPED, and UNKNOWN.
 * <p>
 * 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.
 * <p>
 * The RINGING state indicates the a Terminal is ringing, indicating that the
 * Terminal has an incoming Call.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * The DROPPED state indicates that a particular Terminal has permanently left
 * the telephone call.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * <UL>
 * <LI>IDLE ---> PASSIVE, RINGING, ACTIVE, DROPPED, UNKNOWN
 * <LI>PASSIVE ---> ACTIVE, DROPPED, UNKNOWN
 * <LI>RINGING ---> DROPPED, PASSIVE, ACTIVE, UNKNOWN
 * <LI>ACTIVE ---> PASSIVE, DROPPED, UNKNOWN
 * <LI>DROPPED ---> no state transition allowed.
 * <LI>UNKNOWN ---> IDLE, PASSIVE, RINGING, ACTIVE, DROPPED
 * </UL>
 * <p>
 * These TerminalConnection states also depend upon the Connection states. In
 * the description of the <EM>Call.connect()</EM> method these
 * TerminalConnections are created and transition states during certain
 * stages outlined in the <EM>Call.connect()</EM> 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.
 * <p>
 * <UL>
 * <LI>IDLE ---> no connection states may exist
 * <LI>CONNECTED ---> PASSIVE | ACTIVE | DROPPED 
 * <LI>INPROGRESS ---> no connection states may exist
 * <LI>ALERTING ---> RINGING
 * <LI>DISCONNECTED ---> DROPPED
 * <LI>FAILED ---> DROPPED
 * <LI>UNKNOWN ---> UNKNOWN
 * </UL>
 * <p>
 * A TerminalConnection may answer incoming telephone calls with the
 * <EM>answer()</EM> 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 <EM>answer()</EM> method.
 * <p>
 * @see java.telephony.CallObserver
 * @see java.telephony.TerminalObserver.
 */


public interface TerminalConnection {

  /**
   * The IDLE state is the initial state for all TerminalConnection objects.
   */
  public static final int IDLE = 0x40;


  /**
   * The RINGING state indicates the a Terminal is ringing, indicating that the
   * Terminal has an incoming Call.
   */
  public static final int RINGING = 0x41;


  /**
   * 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.
   */
  public static final int PASSIVE = 0x42;


  /**
    * 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.
   */
  public static final int ACTIVE = 0x43;


  /**
   * The DROPPED state indicates that a particular Terminal has permanently
   * left the telephone call.
   */
  public static final int DROPPED = 0x44;


  /**
   * The UNKNOWN state indicates that the implementation is unable to determine
   * the state of the TerminalConnection.
   */
  public static final int UNKNOWN = 0x45;


  /**
   * Returns the state of the TerminalConnection object.
   * <p>
   * @return The current state of the TerminalConnection object.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public int getState()
    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.
   * <p>
   * @return The Terminal object associated with this TerminalConnection.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Terminal getTerminal()
    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.
   * <p>
   * @return The Connections associated with this TerminalConnection. 
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Connection getConnection()
    throws 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.
   * <p>
   * The pre-condition predicates for this method are:
   * <OL>
   * <LI>((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
   * <LI>this.getState() == TerminalConnection.RINGING
   * <LI>(this.getConnection()).getState() == Connection.ALERTING
   * </OL>
   * <p>
   * The post-condition predicates for this method are, indicating the
   * successful completetion of this invocation:
   * <OL>
   * <LI>((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
   * <LI>this.getState() == TerminalConnection.ACTIVE
   * <LI>(this.getConnection()).getState() == Connection.CONNECTED
   * </OL>
   * <p>
   * 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.
   * <p>
   * 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 <EM>answer()</EM> 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.
   * <p>
   * 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 <EM>java.telephony.events.TermConnActiveEv</EM>
   * for this TerminalConnection, a <EM>java.telephony.events.ConnConnectedEv</EM>
   * for the Connection associated with this TerminalConnection, and either
   * <EM>java.telephony.events.TermConnPassiveEv</EM> or a
   * <EM>java.telephony.events.TermConnDroppedEv</EM> for the other Terminal
   * Connections associated with this TerminalConnection's Connection.
   * <p>
   * @see java.telephony.events.TermConnActiveEv
   * @see java.telephony.events.TermConnPassiveEv
   * @see java.telephony.events.TermConnDroppedEv.
   * @see java.telephony.events.ConnConnectedEv
   * <p>
   * @exception PrivilegeViolationException The application did not have
   * proper authority to answers the telephone call.
   * @exception ResourceUnavailableException The neccessary resources to
   * answer the telephone call were not available when the method was invoked.
   * @exception MethodNotSupportedException This method is currently not
   * supported by this implementation.
   * @exception InvalidStateException An object was not in the proper state,
   * violating the pre-conditions of this method.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void answer()
    throws PrivilegeViolationException, ResourceUnavailableException,
      MethodNotSupportedException, InvalidStateException, 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.
  * <p>
  */
  public TerminalConnectionCapabilities getTerminalConnectionCapabilities(Terminal terminal, Address address)
    throws InvalidArgumentException, PlatformException;
}