callcontrolterminalconnection.java

Java Telephony API .java程序

/*
#pragma ident "@(#)CallControlTerminalConnection.java	1.13      97/01/22     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.callcontrol;
import  java.telephony.*;

/**
 * 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.
 * <p>
 * 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.
 * <p>
 * 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:
 * <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 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.
 * <p>
 * The TALKING state indicates that the phone is off-hook and the party is
 * active and talking on the telephone call.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * 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.
 * <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 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.
 * <p>
 * <UL>
 * <LI>IDLE ---> IDLE
 * <LI>RINGING ---> RINGING
 * <LI>ACTIVE ---> TALKING | HELD
 * <LI>PASSIVE ---> INUSE | BRIDGED
 * <LI>DROPPED ---> DROPPED
 * <LI>UNKNOWN ---> UNKNOWN
 * </UL>
 */

public interface CallControlTerminalConnection extends TerminalConnection {

  /**
   * The IDLE state variable.
   */
  public static final int IDLE = 0x60;


  /**
   * The RINGING state variable.
   */
  public static final int RINGING = 0x61;


  /**
   * The TALKING state variable.
   */
  public static final int TALKING = 0x62;


  /**
   * The HELD state variable.
   */
  public static final int HELD = 0x63;


  /**
   * The BRIDGED state variable.
   */
  public static final int BRIDGED = 0x64;


  /**
   * The INUSE state variable.
   */
  public static final int INUSE = 0x65;


  /**
   * The DROPPED state variable.
   */
  public static final int DROPPED = 0x66;


  /**
   * The UNKNOWN state variable.
   */
  public static final int UNKNOWN = 0x67;


  /**
   * Returns the call control state of the TerminalConnection object.
   * <p>
   * @return The current state of the TerminalConnection object.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public int getCallControlState()
    throws 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.
   * <p>
   * This TerminalConnection must be in the TALKING state and the Provider must
   * be IN_SERVICE. The pre-conditions are given below:
   * <p>
   * <OL>
   * <LI>(this.getTerminal()).getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == TALKING
   * </OL>
   * <p>
   * The post-conditions for this method are as follows:
   * <OL>
   * <LI>(terminal.getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == HELD
   * </OL>
   * <p>
   * @exception InvalidStateException The state of some object is not valid
   * as designated by the pre-conditions for this method.
   * @exception MethodNotSupportedException This method is not supported by
   * the implementation.
   * @exception PrivilegeViolationException The application does not have
   * the proper authority to invoke this method.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is not available.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void hold()
    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.
   * <p>
   * This TerminalConnection must be in the HELD state and the Provider must
   * be IN_SERVICE. These pre-conditions are given below:
   * <p>
   * <OL>
   * <LI>((this.getTerminal()).getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == HELD
   * </OL>
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>((this.getTerminal()).getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == TALKING
   * </OL>
   * <p>
   * @exception InvalidStateException The state of some object is not valid
   * as designated by the pre-conditions for this method.
   * @exception MethodNotSupportedException This method is not supported by
   * the implementation.
   * @exception PrivilegeViolationException The application does not have
   * the proper authority to invoke this method.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is not available.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void unhold()
    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.
   * <p>
   * This TerminalConnection must be in the BRIDGED state and the Provider
   * must be IN_SERVICE. These pre-conditions are given below:
   * <p>
   * <OL>
   * <LI>((this.getTerminal()).getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == BRIDGED
   * </OL>
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>((this.getTerminal()).getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == TALKING
   * </OL>
   * <p>
   * @exception InvalidStateException The state of some object is not valid
   * as designated by the pre-conditions for this method.
   * @exception MethodNotSupportedException This method is not supported by
   * the implementation.
   * @exception PrivilegeViolationException The application does not have
   * the proper authority to invoke this method.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is not available.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void join()
    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.
   * <p>
   * This TerminalConnection object must be in the TALKING state and the
   * Provider must be IN_SERVICE. These pre-conditions are given below:
   * <p>
   * <OL>
   * <LI>((this.getTerminal()).getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == TALKING
   * </OL>
   * <p>
   * 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.
   * <p>
   * <OL>
   * <LI>((this.getTerminal()).getProvider()).getState() == IN_SERVICE
   * <LI>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.
   * <LI>if for all (this.getTerminal()).getTerminalConnections(), there is
   * exists a
   * TerminalConnection in the TALKING state besides this TerminalConnection,
   * then this.getState() == BRIDGED
   * </OL>
   * <p>
   * @exception InvalidStateException The state of some object is not valid
   * as designated by the pre-conditions for this method.
   * @exception MethodNotSupportedException This method is not supported by
   * the implementation.
   * @exception PrivilegeViolationException The application does not have
   * the proper authority to invoke this method.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is not available.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void leave()
    throws InvalidStateException,
           MethodNotSupportedException, PrivilegeViolationException,
           ResourceUnavailableException, PlatformException;
}