callcontrolcall.java

Java Telephony API .java程序

   * termconn
   * <LI>termconn.getState() != DROPPED
   * <LI>termconn == call.getTransferController()
   * </OL>
   * <p>
   * @param termconn The TerminalConnection to use as the transfer 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 setTransferController(TerminalConnection termconn)
    throws InvalidArgumentException, InvalidStateException,
      MethodNotSupportedException, ResourceUnavailableException,
      PlatformException;

  
  /**
   * Gets 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 two telephone Call objects, this
   * TerminalConnection and the Terminal's TerminalConnection which is part
   * of the second call are dropped in the merged call.
   * <p>
   * When a Call is initially created, the transfer controller is set
   * to null. This method returns non-null only if the application has
   * previously successfully invoked the setTransferController() method.
   * If a TerminalConnection, which is currently the transfer controller, 
   * moves into the DROPPED state in the Call, the transfer 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 transfer
   * controller, null if one is not set.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallControlTerminalConnection getTransferController()
    throws PlatformException;


  /**
   * Controls whether this Call object is permitted or able to perform
   * the conferencing feature. If the 'enable' argument is true, this
   * method attempts to turn on the conferencing ability. If 'false' this
   * method turns disallows the conferencing feature. If the implementation
   * is unable to support conferencing, a setConferenceEnable(true) will
   * throw an exception.
   * <p>
   * This method must be called when the Call object is first create and
   * in the IDLE state. The provider must also be in service. The pre-
   * conditions are as follows:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == IDLE
   * </OL>
   * <p>
   * The post-conditions are as follows, given an exception is not thrown
   * and the variable 'enable' represents the value of the parameter passed
   * to this method.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == IDLE
   * <LI>enable = call.getConferenceEnable();
   * </OL>
   * <p>
   * @param enable True turns conferencing on, false turns conferencing off.
   * @exception InvalidArgumentException The Connection object provided is
   * not associated with this Address 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 PrivilegeViolationException The application does not have
   * the proper authority to invoke this method.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void setConferenceEnable(boolean enable)
    throws InvalidArgumentException, InvalidStateException,
      MethodNotSupportedException, PrivilegeViolationException,
      PlatformException;

  
  /**
   * Return true if conferencing is enabled, false otherwise. Applications
   * may use this method initially to obtain the default value set by the
   * implementation and may attempt to change this value using the
   * CallControlCall.setConferenceEnable() method.
   * <p>
   * @return True if conferencing is enabled, false otherwise.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public boolean getConferenceEnable()
    throws PlatformException;


  /**
   * Controls whether this Call object is permitted or able to perform
   * the transfering feature. If the 'enable' argument is true, this
   * method attempts to turn on the transfering ability. If 'false' this
   * method turns disallows the transfering feature. If the implementation
   * is unable to support transfering, a setTransferEnable(true) will
   * throw an exception.
   * <p>
   * This method must be called when the Call object is first create and
   * in the IDLE state. The provider must also be in service. The pre-
   * conditions are as follows:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == IDLE
   * </OL>
   * <p>
   * The post-conditions are as follows, given an exception is not thrown
   * and the variable 'enable' represents the value of the parameter passed
   * to this method.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == IDLE
   * <LI>enable = call.getTransferEnable();
   * </OL>
   * <p>
   * @param enable True turns transfering on, false turns transfering off.
   * @exception InvalidArgumentException The Connection object provided is
   * not associated with this Address 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 PrivilegeViolationException The application does not have
   * the proper authority to invoke this method.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void setTransferEnable(boolean enable)
    throws InvalidArgumentException, InvalidStateException,
      MethodNotSupportedException, PrivilegeViolationException,
      PlatformException;

  
  /**
   * Return true if transfering is enabled, false otherwise. Applications
   * may use this method initially to obtain the default value set by the
   * implementation and may attempt to change this value using the
   * CallControlCall.setTransferEnable() method.
   * <p>
   * @return True if transfering is enabled, false otherwise.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public boolean getTransferEnable()
    throws PlatformException;


  /**
   * Begins a consultation Call with the existing Call. A consultation
   * Call is a new telephone Call placed to a telephony number address
   * and is associated with the current telephony Call. The purpose of
   * creating a consultation call is to either simply consult with another
   * party or eventually to either conference in or transfer to with the
   * existing party. The creation of the new Call behaves in a similar
   * manner as Call.connect(), however the consult() method establishes
   * a special association between the new Call and the current telephone
   * Call. The consult() method
   * exists because it is often a switch feature and establishes the
   * special association between the current telephone Call. The telephone
   * number address provided must be valid and complete.
   * <p>
   * As mentioned above, the purpose of creating a consulation Call is
   * often to perform a transfer() or conference() on these two Calls.
   * Applications must specify their purpose by first telling the switch
   * whether they intend to perform a conference() or transfer() or both
   * using the setConferenceEnable() and setTransferEnable() methods on
   * this object.
   * <p>
   * The originator of this new consultation call is given by a
   * TerminalConnection which must be part of the current Call object and
   * must be in the active state. The destination address for this new
   * call is given by the second argument. Therefore, the new call placed is
   * similar to the Call.connect() method in that the originating Terminal
   * is termconn.getTerminal() and the origination Address is
   * (termconn.getConnection()).getAddress().
   * <p>
   * This method places termconn in the HELD state and create a new Call
   * object. This Call object has two connection, one each for the
   * originating side and the destination side. Both of these Connections
   * are in the IDLE state. This new Call object is returned by the consult()
   * method. The Provider must also be IN_SERVICE. The pre-conditions of this
   * method are given below:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn is element of call.getConnections().getTerminalConnections()
   * <LI>termconn.getState() == ACTIVE
   * </OL>
   * <p>
   * The post-conditions for this method are as follows, where the Call object
   * returned is denoted by 'newcall'.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn.getState() == HELD
   * <LI>newcall.getState() == ACTIVE
   * <LI>Let c = newcall.getConnections() such that c.length == 2
   * <LI>c[0].getState == IDLE
   * <LI>c[1].getState == IDLE
   * </OL>
   * <p>
   * An application can expect that this new Call object will exhibit the
   * same Connection and TerminalConnection state transition scenarios as
   * Calls placed using Call.connect() and as described in the documentation
   * for that method.
   * <p>
   * @param termconn The controlling TerminalConnection for the consultation
   * call.
   * @param address The destination telephone number address.
   * @return The new consultation Call object.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is unavailable.
   * @exception PrivilegeViolationException The application does not have
   * the proper authority to place a consultation telephone call.
   * @exception InvalidArgumentException An argument provided is not valid
   * either by not providing enough information for consult() or is
   * inconsistent with another argument.
   * @exception InvalidStateException Some object required by this method is
   * not is a valid state as designated by the pre-conditions for this method.
   * @exception MethodNotSupportedException The implementation does not
   * support this method.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallControlCall consult(TerminalConnection termconn, String address)
    throws InvalidStateException, InvalidArgumentException,
      MethodNotSupportedException, ResourceUnavailableException,
      PrivilegeViolationException, PlatformException;


  /**
   * This overloaded version of consult() is similar to the other version
   * of consult, except it does not take a destination string address as
   * an argument. Instead, it creates a Call object with one Connection in
   * the CallControlConnection.INITIATED state. Applications may use the
   * <EM>CallControlConnection.addToAddress()</EM> method to dial the
   * destination digits.
   * <p>
   * This method places termconn in the HELD state and create a new Call
   * object. This new Call object is returned by the consult() method. The
   * Provider must also be IN_SERVICE. The pre-conditions of this
   * method are given below:
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn is element of call.getConnections().getTerminalConnections()
   * <LI>termconn.getState() == ACTIVE
   * </OL>
   * <p>
   * The post-conditions for this method are as follows, where the Call object
   * returned is denoted by 'newcall'.
   * <p>
   * <OL>
   * <LI>(call.getProvider()).getState() == IN_SERVICE
   * <LI>call.getState() == ACTIVE
   * <LI>termconn.getState() == HELD
   * <LI>newcall.getState() == ACTIVE
   * <LI>Let c = newcall.getConnections() such that c.length == 1
   * <LI>c[0].getState == INITIATED
   * </OL>
   * <p>
   * @param termconn The controlling TerminalConnection for the consultation
   * call.
   * @return The new consultation Call object.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is unavailable.
   * @exception PrivilegeViolationException The application does not have
   * the proper authority to place a consultation telephone call.
   * @exception InvalidArgumentException An argument provided is not valid
   * either by not providing enough information for consult() or is
   * inconsistent with another argument.
   * @exception InvalidStateException Some object required by this method is
   * not is a valid state as designated by the pre-conditions for this method.
   * @exception MethodNotSupportedException The implementation does not
   * support this method.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallControlCall consult(TerminalConnection termconn)
    throws InvalidStateException, InvalidArgumentException,
      MethodNotSupportedException, ResourceUnavailableException,
      PrivilegeViolationException, PlatformException;
}