callcontrolcall.java

Java Telephony API .java程序

/*
#pragma ident "@(#)CallControlCall.java	1.29      97/02/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.callcontrol;
import  java.telephony.*;

/**
 * The CallControlCall interface extends the core Call interface. The
 * CallControlCall interface provides more functionality on the Call object
 * for the purposes of the CallControl package.
 * <p>
 * Particularly, it provides the addParty() method call to conference
 * in an additional party, the drop() method to drop the entire Call, the
 * conference() method to conference two calls together, the transfer()
 * method to transfer a telephone call, and the consult() method to begin
 * a consultation telephone Call.
 */

public interface CallControlCall extends Call {

  /**
   * Returns the calling Address associated with this call. The calling
   * Address is defined as the Address which placed the telephone call.
   * <p>
   * If the calling address is unknown or not yet known, this method returns
   * null.
   * <p>
   * @return The calling Address.
   * @exception PlatformException Some platform-specific exception occured.
   */
  public CallControlAddress getCallingAddress()
    throws PlatformException;


  /**
   * Returns the calling Terminal associated with this Call. The calling
   * Terminal is defined as the Terminal which placed the telephone call.
   * <p>
   * If the calling Terminal is unknown or not yet know, this method returns
   * null.
   * <p>
   * @return The calling Terminal.
   * @exception PlatformException Some platform-specific exception occured.
   */
  public CallControlTerminal getCallingTerminal()
    throws PlatformException;


  /**
   * Returns the called Address associated with this Call. The called
   * Address is defined as the Address to which the call has been originally
   * placed.
   * <p>
   * If the called address is unknown or not yet known, this method returns
   * null.
   * <p>
   * @returns The called Address.
   * @exception PlatformException Some platform-specific exception occured.
   */
  public CallControlAddress getCalledAddress()
    throws PlatformException;


  /**
   * Returns the last redirected Address associated with this Call.
   * The last redirected Address is the Address at which the current telephone
   * call was placed immediately before the current Address. This is common
   * if a Call is forwarded to several Addresses before being answered.
   * <p>
   * If the the last redirected address is unknown or not yet known, this
   * method returns null.
   * <p>
   * @returns The last redirected Address for this telephone Call.
   * @exception PlatformException Some platform-specific exception occured.
   */
  public CallControlAddress getLastRedirectedAddress()
    throws PlatformException;


  /**
   * Adds an additional party to an existing telephone Call. This is sometimes
   * called a "single-step conference" because a party is conferenced into a
   * telephone call directly. The telephony address provided must be
   * complete and valid.
   * <p>
   * The Call must be ACTIVE before this method is valid. This Call must also
   * have at least two Connections in the CONNECTED state. An addition
   * restriction requires that at most one other Connection may be in either
   * the INPROGRESS state or ALERTING state. The Provider must also be
   * IN_SERVICE. The pre-conditions for this method are given by the following:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>c = call.getConnections() && c.length >= 2
   * <LI>c = call.getConnections() && two connections.getState() == CONNECTED
   * <LI>there exists at most one c = call.getConnections() such that 
   * c.getState() equals ALERTING or INPROGRESS.
   * </OL>
   * <p>
   * This method creates a new Connection and associates it with the Call and
   * the Address object associated with the new party. This Connection is
   * in the IDLE state and is the return value for this method. The
   * post-conditions which are true when this method returns are as follows,
   * where 'c' is the returned connection.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>c.getState() == IDLE
   * </OL>
   * <p>
   * In a typical scenario, this new Connection has the same sequence of state
   * transitions as a destination Connection when the method Call.connect()
   * is invoked. Documentation of that method provides detail of the possible
   * state transition scenarios of the new Connection created by this method.
   * <p>
   * On some platforms, switch limitations impose restrictions on the number of
   * connections of a particular state in a call. For instance, it is common to
   * restrict the number of ALERTING connections to at most one.  If any
   * operation is attempted that would violate one of these restrictions.
   * As a result, one precondition for this method is that there cannot be
   * another connection in either the INPROGRESS or ALERTING state. Although
   * some systems may not enforce this requirement, for consistency the Java
   * Telephony API chose this conservative requirement.
   * <p>
   * @param newParty The telephone number address of the party to be added.
   * @return The new Connection associated with the added party.
   * @exception InvalidStateException The state of some object is not valid
   * as designated by the pre-conditions for this method.
   * @exception InvalidPartyException The new party to be added to the call
   * is invalid.
   * @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 CallControlConnection addParty(String newParty)
    throws InvalidStateException, InvalidPartyException,
           MethodNotSupportedException, PrivilegeViolationException,
           ResourceUnavailableException, PlatformException;
    
  
  /**
   * Drops the entire Call. This method is equivalent to using the
   * disconnect() method on each Connections which is part of the Call. There
   * are some Connections which the application does not possess the proper
   * authority to drop. In this case, the drop() method performs no action
   * on these. As a result of dropping some of the Connection, the other
   * Connections which the application cannot control may drop automatically
   * as a result. If all Connections succeed in moving to the DISCONNECTED
   * state, the call becomes INVALID. This method returns when it can
   * successfully drop as many Connections are possible. All of the
   * TerminalConnections associated with the dropped Connections will move
   * into the DROPPED state. 
   * <p>
   * The pre-conditions for this method are:
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * </OL>
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>if all connections = call.getConnections() and
   * connections.getState() == DISCONNECTED, then call.getState() == INVALID
   * <LI>for all connections = call.getConnections and connections.getState()
   * == DISCONNECTED, for all termconns = connections.getTerminalConnections(),
   * termconns.getState() == DROPPED.
   * </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 and it can drop none of the
   * Connections.
   * @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 drop()
      throws InvalidStateException, MethodNotSupportedException,
	PrivilegeViolationException, ResourceUnavailableException,
	PlatformException;


  /**
   * Takes the originating end of a telephone call off-hook. This method
   * permits application to simply take the originating terminal of a telephone
   * call off-hook, so that users may manually dial telephone number digits
   * or applications may supply digits with the
   * <EM>CallControlConnection.addToAddress()</EM> method. This is in contrast
   * to the <EM>Call.connect()</EM> method which requires the complete
   * destination address string.
   * <p>
   * This Call object must be in the IDLE state prior to the invocation of
   * this method. This method creates a Connection to the originating Address
   * in the CallControlConnection.INITIATED state and returns this Connection
   * at the successful completion of this method. This method also creates
   * a TerminalConnection associated with the originating Terminal in the
   * CallControlTerminalConnection.TALKING state.
   * <p>
   * The pre-conditions for this method are:
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * <LI>this.getState() == Call.IDLE
   * </OL>
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * <LI>Let Connnection c = this.offHook(Address, Terminal)
   * <LI>c.getCallControlState() == CallControlConnection.INITIATED
   * <LI>Let TerminalConnection tc[] = c.getTerminalConnections()
   * <LI>tc.length == 1
   * <LI>tc[0].getCallControlState() == CallControlTerminalConnection.TALKING;
   * <LI>tc element of origterminal.getTerminalConnections()
   * <LI>c element of origaddress.getConnections()
   * <LI>c element of this.getConnections()
   * </OL>
   * <p>
   * @param origaddress The originating Address object.
   * @param origterminal The originating Terminal object.
   * @return The Connection associated with the originating end of the
   * telephone call.
   * @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 and it can drop none of the
   * Connections.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is not available.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallControlConnection offHook(Address origaddress, Terminal origterminal)
    throws InvalidStateException, MethodNotSupportedException,
      PrivilegeViolationException, ResourceUnavailableException,
      PlatformException;


  /**
   * Merges two Calls together resulting in the union of the parties involved
   * with both calls belong to a single telephone call. The telephone Call
   * provided as the argument has its Connections move to this Call object,
   * and the Call object argument becomes invalid.
   * <p>
   * In order for a conference action to be successful, there must exist
   * a Terminal object which is part of both telephone Calls. Furthermore,
   * this Terminal object will have two TerminalConnections associated with
   * it which are each part of one of the Calls. An application may have
   * specified on such TerminalConnections on this call to be the "conference
   * controller". If the application did not make such a selection, the
   * implementation chooses a suitable Terminal and TerminalConnection. We
   * shall call the TerminalConnection on this Call acting as the conference
   * controller (whether selected by the application or not) as "conftermconn"
   * and its Terminal as "confterm". The TerminalConnection associated with
   * confterm and the second Call object, we shall call "scndtermconn". The
   * following are the initial pre-condition predicates for this method:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>conftermconn element of call.getConnections().getTerminalConnections()
   * <LI>conftermconn element of confterm.getTerminalConnections()
   * <LI>scndtermconn element of
   * othercall.getConnections().getTerminalConnections()
   * <LI>scndtermconn element of confterm.getTerminalConnections()
   * </OL>
   * <p>
   * These two TerminalConnections must be in a particular state. Specifically,
   * conftermconn must be in the CallControlTerminalConnection.ACTIVE state
   * and scndtermconn must be in the CallControlTerminalConnection.HELD state.
   * These additional pre-conditions are listed below:
   * <p>
   * <OL>
   * <LI>conftermconn.getState() == ACTIVE
   * <LI>scndtermcomm.getState() == HELD
   * </OL>
   * <p>
   * The conference() method "merges" these two telephone Calls together by
   * taking all of the Connections and TerminalConnections on otherCall and
   * creating new Connections and TerminalConnections with the same Address
   * and Terminal objects, respectively, in the same state as in oldCall. The
   * conftermconn and scndtermconn are the exception. The scndtermconn
   * TerminalConnection in otherCall moves to the DROPPED state. Let c equal
   * some Connections in otherCall and tc equal some TerminalConnection in
   * otherCall. Then, for all Connection's c and TerminalConnections tc
   * (with the exception tc = scndtermconn), the following post-conditions
   * indicate the result of the conference method. The construct new(c) and
   * new(tc) mean to create a new Connection and TerminalConnection object
   * with the same Address and TerminalConnection references.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>new(c) element of call.getConnections()