connection.java

Java Telephony API .java程序

   * one another are represented by two Connections in the Connection.CONNECTED
   * state.
   */
  public static final int CONNECTED = 0x33;


  /**
   * The Connection.DISCONNECTED state implies it is no longer part of the
   * telephone call, although its references to Call and Address still remain
   * valid. A Connection in the Connection.DISCONNECTED state is interpreted as
   * once previously belonging to this telephone call.
   */
  public static final int DISCONNECTED = 0x34;


  /**
   * The Connection.FAILED state indicates that a Connection to that end of the
   * call has failed for some reason. One reason why a Connection would be in
   * the Connection.FAILED state is because the party was busy.
   */
  public static final int FAILED = 0x35;


  /**
   * The Connection.UNKNOWN state implies that the implementation is unable to
   * determine the current state of the Connection. Typically, method are
   * invalid on Connections which are in the Connection.UNKNOWN state.
   * Connections may move in and out of the Connection.UNKNOWN state at any
   * time.
   */
  public static final int UNKNOWN = 0x36;


  /**
   * Returns the current state of the Connection. The return value will
   * be one of states defined above.
   * <p>
   * @return The current state of the Connection.
   * @exception PlatformException An platform-specific exception occurred.
   */
  public int getState()
    throws PlatformException;


  /**
   * Returns the Call object associated with this Connection. This Call
   * reference remains valid throughout the lifetime of the Connection object,
   * despite its current state. This Call reference does not change after this
   * object is created.
   * <p>
   * @return The call object associated with this Connection.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Call getCall()
    throws PlatformException;


  /**
   * Returns the Address object associated with this Connection. This Address
   * object reference remains valid throughout the lifetime of the Connection
   * object despite its current state. This Address reference does not change
   * after this object is created.
   * <p>
   * @return The Address associated with this Connection.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Address getAddress()
    throws PlatformException;


  /**
   * Returns an array of TerminalConnections associated with this Connection.
   * TerminalConnection objects represent the relationship between a Call
   * and a specific Terminal endpoint. There may be zero TerminalConnections
   * associated with this Connection. In that case, this method returns null.
   * Connection objects lose their reference to a TerminalConnection once the
   * TerminalConnection moves into the TerminalConnection.DROPPED state. The
   * Provider must be in the Provider.IN_SERVICE state for this method to be
   * valid.
   * <p>
   * The pre-conditions for this method are:
   * <OL>
   * <LI>((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
   * </OL>
   * <p>
   * The following post-conditions of this are:
   * <OL>
   * <LI>Let TerminalConnection tc[] = this.getTerminalConnections()
   * <LI>tc == null or tc.length >= 1
   * <LI>For all i, tc[i].getState() != TerminalConnection.DROPPED
   * </OL>
   * <p>
   * @return An array of TerminalConnection objects associated with this
   * Connection, null if there are no TerminalConnections
   * @exception InvalidStateException The Provider is not IN_SERVICE.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public TerminalConnection[] getTerminalConnections()
    throws InvalidStateException, PlatformException;


  /**
   * Drops a Connection from an active telephone call. The Connection's Address
   * is no longer associated with the telephone call. The Connection object
   * must either be in the Connection.CONNECTED, the Connection.ALERTING,
   * the Connection.INPROGRESS, or the Connection.FAILED states in order for
   * this method to succeed, although this pre-condition does not guarantee its
   * success. This method returns upon success when this Connection moves to
   * the Connection.DISCONNECTED state. Also, all of the TerminalConnections
   * associated with this Connection move to the TerminalConnection.DROPPED
   * state. These TerminalConnections are no longer reported by this
   * Connection. 
   * <p>
   * The pre-condition predicates for this method are:
   * <OL>
   * <LI>((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
   * <LI>this.getState() == Connection.CONNECTED or Connection.ALERTING
   * or Connection.FAILED or Connection.INPROGRESS
   * <LI>Let TerminalConnection tc[] = this.getTerminalConnections (see post-
   * conditions)
   * </OL>
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
   * <LI>this.getState() == Connection.DISCONNECTED
   * <LI>For all i, tc[i].getState() == TerminalConnection.DROPPED
   * <LI>this.getTerminalConnections() == null.
   * <LI>this is not an element of (this.getCall()).getConnections()
   * </OL>
   * <p>
   * When this method returns, the following events are reported on the
   * CallObserver interface for the Call associated with this Connection:
   * a <EM>java.telephony.events.ConnDisconnectedEv</EM> for this Connection, and a
   * <EM>java.telephony.events.TermConnDroppedEv</EM> for all of its Terminal
   * Connections.
   * <p>
   * @see java.telephony.events.ConnDisconnectedEv
   * @see java.telephony.events.TermConnDroppedEv
   * <p>
   * @exception PrivilegeViolationException The application does not have
   * the authority to drop the Connection.
   * @exception ResourceUnavailableException An internal resource required
   * to drop a connection is not available.
   * @exception MethodNotSupportedException This method is not supported by
   * the implementation.
   * @exception InvalidStateException Some object required for the successful
   * invocation of this method is not in the proper state as given by this
   * method's pre-conditions.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void disconnect()
    throws PrivilegeViolationException, ResourceUnavailableException,
      MethodNotSupportedException, InvalidStateException, PlatformException;


  /**
   * Gets the ConnectionCapabilities object with respect to a Terminal and
   * an Address.
   * If null is passed as a Terminal parameter, the general/provider-wide 
   * Connection capabilities are returned.
   * <p>
   * @exception PlatformException A platform-specific exception occurred.
   */
  public ConnectionCapabilities getConnectionCapabilities(Terminal terminal, Address address)
    throws InvalidArgumentException, PlatformException;
}