call.java

Java Telephony API .java程序

   *   <EM>java.telephony.events.TermConnPassiveEv</EM> for each of those Terminal
   *   Connections.
   * <LI>The destination Connection moves from the Connection.IDLE state into
   *    the TerminalConnection.INPROGRESS state.
   * <p>
   *    The following events are delivered to the application via the
   *    CallObserver interface: a <EM>java.telephony.events.ConnInProgressEv</EM>
   *    for the destination Connection.
   * <LI>The destination Connection moves from the Connection.INPROGRESS state
   *    to the Connection.ALERTING state. TerminalConnection objects are
   *    created between the Call and every Terminal object associated with the
   *    destination Address in the TerminalConnection.RINGING state.
   * <p>
   *    The following events are delivered to the application via a CallObserver
   *    on this Call: a <EM>java.telephony.events.ConnAlertingEv</EM> for the
   *    destination Connection, a <EM>java.telephony.events.TermConnCreatedEv</EM>
   *    for all Terminal Connections created to Terminals with the destination
   *    Address, a <EM>java.telephony.events.TermConnRingingEv</EM> for all those
   *    new TerminalConnections.
   * <p>

   *    The following events are delivered to the application via the
   *    CallObserver on this Call: a <EM>java.telephony.events.ConnConnectedEv</EM>
   *    for the destination Connection, and a
   *    <EM>java.telephony.events.TermConnActiveEv</EM> for the TerminalConnection
   *    which answered the telephone call.
   * <p>
   *    For all other TerminalConnections in the TerminalConnection.RINGING
   *    state on the destination side, either one of two things will happen
   *    depending upon the configuration of the switch. Unfortunately, the
   *    implementation is unable to determine the behavior of the switch
   *    beforehand. In one situation, these TerminalConnections move from
   *    the TerminalConnection.RINGING state to the TerminalConnection.PASSIVE
   *    state. In the second situation, these TerminalConnections move from the
   *    TerminalConnection.RINGING state to the TerminalConnection.DROPPED
   *    state.
   * <p>
   *    Because of the paragraph above, the following events will be delivered
   *    to the application via the CallObserver interface on this Call:
   *    a <EM>java.telephony.events.TermConnPassiveEv</EM> in one situation, or
   *    a <EM>java.telephony.events.TermConnDroppedEv</EM> in the other situation.
   * </OL>
   * <p>
   * The post-condition predicates for scenario 1 are as follows. These
   * post-conditions state what is true about the call model after the final
   * step of scenario 1 completes.
   * <p>
   * <OL>
   * <LI>this.getState() == Call.ACTIVE
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * <LI>Let Connection c[] = this.getConnections()
   * <LI>c[0].getState == Connection.CONNECTED
   * <LI>c[1].getState == Connection.CONNECTED
   * <LI>Let TerminalConnection origtc[] = c[0].getTerminalConnections()
   * <LI>There exists an i, such that origtc[i].getState() ==
   * TerminalConnection.ACITVE.
   * <LI>Let TerminalConnection desttc[] = c[1].getTerminalConnections()
   * <LI>There exists an i, such that desttc[i].getState() ==
   * TerminalConnection.ACTIVE.
   * </OL>
   * <p>
   * Scenario 2: The desired telephone call is placed however the completion
   * of the call is impossible because of a failure. For example, this
   * scenario will occur if the destination address is busy. In this scenario
   * the destination Connection never reaches the ALERTING state. (i.e. the
   * destination party is never alerted to this telephone call)
   * <p>
   * <OL>
   * <LI>The Call.connect() is method invoked with the given arguments.
   * <LI>Exactly two connections are created, each in the Connection.IDLE
   *    state. The first connection created represents the originating end of
   *   the call. The second connection created represents the destination end
   *   of the call.
   * <p>
   *    The Call.connect() method returns, returning a two-element array of
   *    Connections. The first element at index 0 represents the originating
   *    Connection. The second element at index 1 represents the destination
   *    Connection. Both Connections are in the Connection.IDLE state.
   * <p>
   *    The following events are delivered to the application via a CallObserver
   *    on this Call: a <EM>java.telephony.events.CallActiveEv</EM>, a
   *    <EM>java.telephony.events.ConnCreatedEv</EM> for each of the two Connections
   *    created.
   * <p>
   * <LI>Once the Provider begins to place the telephone call, the originating
   *    Connection moves from the Connection.IDLE state into the
   *    Connection.CONNECTED state. A TerminalConnection is created in the
   *    TerminalConnection.ACTIVE state between the originating Terminal and
   *    the Call.
   * <p>
   *    The following events are delivered to the application via a CallObserver
   *    on this Call: a <EM>java.telephony.events.ConnConnectedEv</EM> for the
   *    originating Connection, a <EM>java.telephony.events.TermConnCreatedEv</EM>
   *    for the new TerminalConnection created, and a
   *    <EM>java.telephony.events.TermConnActiveEv</EM> for the new Terminal
   *    Connection.
   * <p>
   *   Depending upon the configuration of the switch, additional
   *   TerminalConnections may be created. These TerminalConnections will be
   *   associated with Terminals which have the originating Address as one of
   *   their Addresseses. Unfortunately, there is no way for the implementation
   *   to tell which TerminalConnections will be created in advance, only that
   *   the number cannot be greater than the number of Terminals associated
   *   with the originating Address and each TerminalConnection must go to
   *   one of those Terminals associated with the originating Address. If such
   *   a Terminal Connection is created, it will be in the
   *   TerminalConnection.PASSIVE state.
   * <p>
   *   Additional events are delivered because of the above paragraph: a
   *   <EM>java.telephony.events.TermConnCreateEv</EM> for all additional
   *   Terminal Connections created, and a
   *   <EM>java.telephony.events.TermConnPassiveEv</EM> for each of those Terminal
   *   Connections. 
   *
   * <LI>The destination Connection moves from the Connection.IDLE state into
   *    the TerminalConnection.INPROGRESS state.
   * <p>
   *    The following events are delivered to the application via the
   *    CallObserver interface: a <EM>java.telephony.events.ConnInProgressEv</EM>
   *    for the destination Connection.
   * <LI>The destination Connection moves from the Connection.INPROGRESS state
   *    into the Connection.FAILED state.
   * <p>
   *    The following events are delivered to the application via the
   *    CallObserver interface: a <EM>java.telephony.events.ConnFailedEv</EM> for
   *    the destination Connection.
   * </OL>
   * <p>
   * The post condition predicates for scenario 2 are as follows. These
   * post-conditions state what is true about the call model after the final
   * step of scenario 1 completes.
   * <OL>
   * <LI>this.getState() == Call.ACTIVE
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * <LI>Let Connection c[] = this.getConnections()
   * <LI>c[0].getState() == Connection.CONNECTED
   * <LI>c[1].getState() == Connection.FAILED
   * <LI>Let TerminalConnection origtc[] = c[0].getTerminalConnections()
   * <LI>There exists an i, such that origtc[i].getState() ==
   * TerminalConnection.ACITVE.
   * </OL>
   * <p>
   * @see java.telephony.events.CallActiveEv
   * @see java.telephony.events.ConnAlertingEv
   * @see java.telephony.events.ConnConnectedEv
   * @see java.telephony.events.ConnCreatedEv
   * @see java.telephony.events.ConnInProgressEv
   * @see java.telephony.events.TermConnActiveEv
   * @see java.telephony.events.TermConnCreatedEv
   * @see java.telephony.events.TermConnDroppedEv
   * @see java.telephony.events.TermConnPassiveEv
   * @see java.telephony.events.TermConnRingingEv
   * <p>
   * @param origterm The originating Terminal for this telephone call.
   * @param origaddr The originating Address for this telephone call.
   * @param destaddr The destination Address for this telephone call.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for placing the phone call is unavailable.
   * @exception PrivilegeViolationException The application does not have
   * the proper authority to place a telephone call.
   * @exception InvalidPartyException Either the originator or the destination
   * does not represent a valid party required to place a telephone call.
   * @exception InvalidArgumentException An argument provided is not valid
   * either by not providing enough information for connect() 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 Connection[] connect(Terminal origterm, Address origaddr,
			      String dialedDigits)
    throws ResourceUnavailableException, PrivilegeViolationException,
      InvalidPartyException, InvalidArgumentException, InvalidStateException,
      MethodNotSupportedException, PlatformException;


  /**
   * Adds an observer to the Call. The CallObserver reports all Call-related
   * state changes as events as well as all Connection state changes and
   * TerminalConnection state changes.  The Call object will report events to
   * this CallObserver object for the lifetime of the Call object or until the
   * observer is removed with the <EM>Call.removeObserver()</EM> method or
   * until the Call moves into the Call.INVALID state. The Call must be either
   * in the Call.IDLE state or Call.ACTIVE state as a pre-condition for this
   * method.
   * <p>
   * By default, when an observer is added to a telephone call, the first
   * batch of events may be a "snapshot". That is, if the observer was added
   * certain state changes in the call, the first batch of events will inform
   * the application of the current state of the call. Note that these
   * snapshot events do NOT provide a history of all events on the call. Rather
   * they provide the minimum neccessary event to bring the application
   * up-to-date with the current state of the call.
   * <p>
   * If an application attempts to add an instance of an observer already
   * present on this Call, then repeated attempts to add the instance
   * of the observer will silently fail, i.e. multiple instances of an
   * observer are not added and no exception will be thrown.
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>observer is an element of this.getObservers()
   * </OL>
   * <p>
   * @param observer The observer being added.
   * @exception ResourceUnavailableException The resource limit for the
   * numbers of observers has been exceeded.
   * @exception PlatformException A platform-specific exception occurred.
   */ 
  public void addObserver(CallObserver observer)
    throws ResourceUnavailableException, PlatformException;


  /**
   * Returns a list of all CallObservers associated with this call object.
   * If no observers are on this Call object, then this method returns null.
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>Let CallObserver[] obs = this.getObservers()
   * <LI>obs == null or obs.length >= 1
   * </OL>
   * <p>
   * @return An array of CallObserver objects associated with this
   * Call.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallObserver[] getObservers()
    throws PlatformException;


  /**
   * Removes the given observer from the Call. If successful, the observer
   * will no longer receive events generated by this call object.
   * <p>
   * Also, if an observer is not part of the Call, then this method
   * fails silently, i.e. no observer is removed an no exception is thrown.
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>observer is not an element of this.getObservers()
   * </OL>
   * <p>
   * @param observer The observer which is being removed.
   * @exception PlatformException A platform-specific exception occurred.
   */ 
  public void removeObserver(CallObserver observer)
    throws PlatformException;


 /**
  * Gets the CallCapabilities object with respect to a Terminal and an
  * Address.
  * If null is passed as a Terminal parameter, the general/provider-wide Call 
  * capabilities are returned.
  * <p>
  */
  public CallCapabilities getCallCapabilities(Terminal terminal, Address address)
    throws InvalidArgumentException, PlatformException;
}