callcontrolcall.java

Java Telephony API .java程序

   * <LI>new(c).getState() == c.getState()
   * <LI>new(tc) element of (call.getConnections()).getTerminalConnections()
   * <LI>new(tc).getState() == tc.getState()
   * </OL>
   * <p>
   * Finally, the Connections and TerminalConnections in otherCall move to
   * DISCONNECTED and DROPPED respectively, and otherCall becomes INVALID.
   * <p>
   * <OL>
   * <LI>c.getState() == DISCONNECTED
   * <LI>tc.getState() == DROPPED
   * <LI>otherCall.getState() == INVALID
   * </OL>
   * <p>
   * @param otherCall The second Call which to merge with this Call object.
   * @exception InvalidArgumentException The Call object provided is
   * not valid for the conference
   * @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 conference(Call otherCall)
    throws InvalidStateException, InvalidArgumentException,
           MethodNotSupportedException, PrivilegeViolationException,
           ResourceUnavailableException, PlatformException;

  
  /**
   * This flavor of the transfer() method transfer all parties currently
   * associated with the Call to another telephone Call. Here, all parties
   * associated with the Call provided as the argument are moved to this
   * Call object.
   * <p>
   * There must be a Terminal which is part of both calls on the same Address.
   * This Terminal has a TerminalConnection to each of the telephone calls. If
   * more than one such Terminal exists, the implementation choose are suitable
   * one. If no such Terminal exists, this method throws an exception. Let
   * us call the TerminalConnection associated with this call 'termconn' and
   * the TerminalConnection associated with otherCall, 'scndtermconn'. 
   * <p>
   * These two TerminalConnections (and the Terminal) drop off of the Call
   * once the transfer takes place. The fact that this Terminal drops from the
   * call is a distinguishing feature between this transfer() method and
   * conference(). The TerminalConnections must either be in the TALKING or
   * HELD state (these are CallControlTerminalConnection states). The Provider
   * must be IN_SERVICE. These pre-conditions are listed below:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>otherCall.getState() == ACTIVE
   * <LI>termconn element of (call.getConnections()).getTerminalConnections()
   * <LI>termconn.getState() == TALKING or HELD
   * <LI>scndtermconn element of
   * (otherCall.getConnections()).getTerminalConnections()
   * <LI>scndtermconn.getState() == TALKING or HELD
   * </OL>
   * <p>
   * This method moves the termconn and scndtermconn into the DROPPED state,
   * and if it is the only TerminalConnection on the Connection, the
   * Connection moves to the DISCONNECTED state. The sncdtermconn object
   * also moves into the TerminalConnection state and does not get moved to
   * this Call object. All other Connections and TerminalConnections which are
   * part of otherCall are moved to this Call object in the same state as
   * they were in otherCall. New Connection objects are created, and the old
   * Connection and TerminalConnection objects on otherCall move to
   * DISCONNECTED and DROPPED, respectively. The otherCall object becomes
   * INVALID. The post-conditions of this method are as follows:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn.getState() == DROPPED
   * <LI>(termconn.getConnection()).getTerminalConnections is of length 1, then
   * (termconn.getConnection()).getState() == DISCONNECTED
   * <LI>scndtermconn.getState() == DROPPED
   * <LI>For all connections in otherCall.getConnections(),call.getConnections()
   * has an element in the same state and the same Address reference.
   * <LI>For all terminalconnection in 
   * (otherCall.getConnections()).getTerminalConnections(), this call object
   * has the same number of TerminalConnections minus scndtermconn in the
   * same state and associated with the same Connection and Terminal.
   * <LI>For all connections in otherCall.getConnections(),
   * connections.getState() == DISCONNECTED
   * <LI>For all terminalconnections in connections.getTerminalConnections(),
   * terminalconnections.getState() == DROPPED
   * <LI>otherCall.getState() == INVALID
   * </OL>
   * <p>
   * @param otherCall The other Call which to transfer to this Call.
   * @exception InvalidArgumentException The TerminalConnection
   * controlling the transfer is not valid or does not exists or the other
   * telephone call is not valid.
   * @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.
   * @exception Exception An implementation-specific exception occurred.
   * <p>
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void transfer(Call otherCall)
    throws InvalidStateException, InvalidArgumentException,
      InvalidPartyException, MethodNotSupportedException,
      PrivilegeViolationException, ResourceUnavailableException,
      PlatformException;


  /**
   * This flavor of the transfer() method transfer all parties currently
   * associated with the Call to another telephony number address. Typically,
   * the participants of call will hear the new address alerting. The telephone
   * address provided must be valid and complete.
   * <p>
   * The transfer() method is associated with some TerminalConnection which
   * is part of the current telephony Call. This TerminalConnection specifies
   * from which Terminal is transfer is being invoked. This Terminal and
   * TerminalConnection drop off from the call once transferred. This special
   * TerminalConnection is called the "transfer controller" and is optionally
   * set by the setTransferController() method. If applications do not select
   * a transfer controller, then the implementations will select a suitable
   * one. For the purposes of this method, this transfer controller
   * TerminalConnection will be denoted as 'termconn'.
   * <p>
   * The transfer controller must be in the ACTIVE state and be part of this
   * telephone call. The Provider must also be IN_SERVICE. The pre-conditions
   * for this method are:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn element of (call.getConnections()).getTerminalConnections()
   * <LI>termconn.getState() == ACTIVE
   * </OL>
   * <p>
   * This method moves the termconn into the DROPPED state, and if it is
   * the only TerminalConnection on the Connection, the Connection moves to
   * the DISCONNECTED state. The transfer() method then creates a new
   * Connection in the IDLE state to an Address object corresponding to
   * the string telephone number address provided. The transfer() method
   * returns this new Connection. The post-conditions of this method are
   * as follows, given the returned Connection is denoted by 'connection':
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn.getState() == DROPPED
   * <LI>(termconn.getConnection()).getTerminalConnections is of length 1, then
   * (termconn.getConnection()).getState() == DISCONNECTED
   * <LI>if connection != null, connection is an element of call.getConnections()
   * <LI>if connection != null, then connection.getState() == IDLE
   * </OL>
   * <p>
   * An application can expect the new connection to transition through the
   * Connection states similiar to a destination Connection does after a
   * Call.connect() is invoked.
   * <p>
   * Note that the new Connection created and returned may be null. This
   * Connection will be null in the case that the Call has transferred out of
   * the Provider's domain.
   * <p>
   * @param address The destination address where the Call is being
   * transferred.
   * @return The new Connection associated with the destination or null.
   * @exception InvalidArgumentException The TerminalConnection provided as
   * controlling the transfer is not valid or part of this telephone Call.
   * @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 transfer to 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 transfer(String address)
    throws InvalidArgumentException, InvalidStateException,
      InvalidPartyException, MethodNotSupportedException,
      PrivilegeViolationException, ResourceUnavailableException,
      PlatformException;

  
  /**
   * Sets the TerminalConnection which is current acting as the "conference
   * controller." The conference controller is a TerminalConnection on a
   * telephone Call object whose Terminal is also part of another telephone
   * call. When performing a conference of two telephone Call objects, this
   * TerminalConnection and the Terminal's TerminalConnection which is part
   * of the second call are merged into one in the merged Call object.
   * <p>
   * The Call must be in the ACTIVE state in order for this method not to
   * throw an exception. The TerminalConnection supplied as the conference
   * controller must be in the Call and must not be in the DROPPED state. The
   * Provider must also be IN_SERVICE. These pre-conditions are given below.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn union (call.getConnections()).getTerminalConnections() ==
   * termconn
   * <LI>termconn.getState() != DROPPED
   * </OL>
   * <p>
   * If these pre-conditions are met, this method sets the given
   * TerminalConnection as the conference controller, where the following
   * post-conditions are met:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn union (call.getConnections()).getTerminalConnections() ==
   * termconn
   * <LI>termconn.getState() != DROPPED
   * <LI>termconn == call.getConferenceController()
   * </OL>
   * <p>
   * @param termconn The TerminalConnection to use as the conference controller
   * @exception InvalidArgumentException The TerminalConnection object
   * provided is not associated with this Call object.
   * @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 ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is not available.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void setConferenceController(TerminalConnection termconn)
    throws InvalidArgumentException, InvalidStateException,
      MethodNotSupportedException, ResourceUnavailableException,
      PlatformException;

  
  /**
   * Gets the TerminalConnection which is current acting as the "conference
   * controller." The conference controller is a TerminalConnection on a
   * telephone Call object whose Terminal is also part of another telephone
   * call. When performing a conference of two telephone Call objects, this
   * TerminalConnection and the Terminal's TerminalConnection which is part
   * of the second call are merged into one in the merged Call object.
   * <p>
   * When a Call is initially created, the conference controller is set
   * to null. This method returns non-null only if the application has
   * previously successfully invoked the setConferenceController() method.
   * If a TerminalConnection, which is currently the conference controller, 
   * moves into the DROPPED state in the Call, the conference controller is
   * then set to null once again.
   * <p>
   * This method requires that the Provider is IN_SERVICE and the call is
   * either IDLE or ACTIVE. The pre-conditions are listed below.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == IDLE or call.getState() == ACTIVE
   * </OL>
   * <p>
   * The post conditions for this method ensure that the returned
   * TerminalConnection, if not null, is in the call and not in the DROPPED
   * state as given below, where 'termconn' is the TerminalConnection returned
   * from this method:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == IDLE or call.getState() == ACTIVE
   * <LI>if termconn != null, then termconn is an element of
   * (call.getConnections()).getTerminalConnections()
   * <LI>if termconn != null, then termconn.getState() != DROPPED
   * </OL>
   * <p>
   * @return The current TerminalConnection acting as the conference
   * controller, null if one is not set.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallControlTerminalConnection getConferenceController()
    throws PlatformException;


  
  /**
   * Sets the TerminalConnection which is current acting as the "transfer
   * controller." The transfer controller is a TerminalConnection on a
   * telephone Call object whose Terminal is also part of another telephone
   * call. When performing a transfer of telephone Call objects, this
   * TerminalConnection and the Terminal's TerminalConnection which is part
   * of the second call are dropped.
   * <p>
   * The Call must be in the ACTIVE state in order for this method not to
   * throw an exception. The TerminalConnection supplied as the terminal
   * controller must be in the Call and must not be in the DROPPED state. The
   * Provider must also be IN_SERVICE. These pre-conditions are given below.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn union (call.getConnections()).getTerminalConnections() ==
   * termconn
   * <LI>termconn.getState() != DROPPED
   * </OL>
   * <p>
   * If these pre-conditions are met, this method sets the given
   * TerminalConnection as the transfer controller, where the following
   * post-conditions are met:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn union (call.getConnections()).getTerminalConnections() ==