callcontrolconnection.java

Java Telephony API .java程序

/*
#pragma ident "@(#)CallControlConnection.java	1.19      97/02/06     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 CallControlConnection interface extends the core Connection interface.
 * The CallControlConnection interface provides greater details about the
 * state of the Connection object. For many of the core Connection object
 * states, the CallControlConnection interfaces often provides several sub-
 * states of the core states. These sub-states provide more information to
 * application about what is going on. The method getCallControlState() returns
 * this more detailed state. Typically, applications with either monitor
 * the core Connection states or the CallControlConnection states.
 * <p>
 * The Connection states presented by this interface are: IDLE, OFFERING,
 * QUEUED, NETWORK_REACHED, NETWORK_ALERTING, ALERTING, INITIATED, DIALING, 
 * ESTABLISHED, DISCONNECTED, FAILED, BUSY, UNKNOWN.
 * <p>
 * The real-world definitions for these states follow. Note that these
 * definitions are not technical nor absolute, however, they give an idea
 * to the reader about what these states means:
 * <p>
 * The IDLE state is defined similiarly here as it is in the core. The IDLE
 * state is the initial and transitory state for new Connection objects.
 * <p>
 * The OFFERING state is particular to ISDN and indicates that a Call is
 * being offered. Typically, applications must accept or reject this offered
 * call.
 * <p>
 * The QUEUED state indicates that a Connection is queued at a particular
 * address. This may result when someone enables the queueing mechanism on
 * an address and the address is busy when a telephone call comes in.
 * <p>
 * The NETWORK_REACHED state indicates that the outgoing telephone call has
 * reached the network, however, further events may not be received. It is
 * up to the application whether to treat this as a connected call.
 * <p>
 * The NETWORK_ALERTING state indicates that the outgoing telephone call has
 * previously reached the network, however, further information obtained from
 * the switch indicates that this call is now alerting at some destination
 * endpoint.
 * <p>
 * The ALERTING state has the same definition as in the core.
 * <p>
 * The INITIATED state indicates that an originating Connection's telephone
 * is off-hook, however, dialing has not yet begun.
 * <p>
 * The DIALING state applies to originating Connections and indicates that
 * the process of dialing has begun but has not yet completed.
 * <p>
 * The ESTABLISHED state has a similar definition as CONNECTED does in the core.
 * It indicates that a Connection has reached its final active state in the
 * call.
 * <p>
 * The DISCONNECTED state has the same definition as in the core.
 * <p>
 * The FAILED state has the same definition as in the core.
 * <p>
 * The UNKNOWN state has the same definition as in the core.
 * <p>
 * These CallControlConnection states are defined in terms of the core
 * Connection states. In other words, if the core Connection is in a particular
 * state, then the CallControlConnection must be in one of possible several
 * states. This relationship is defined below, where the core Connection states
 * are on the left, and the CallControlConnection states are on the right.
 * <p>
 * <UL>
 * <LI>IDLE ---> IDLE
 * <LI>INPROGRESS ---> QUEUED, OFFERING
 * <LI>ALERTING ---> ALERTING
 * <LI>CONNECTED ---> INITIATED, DIALING, NETWORK_REACHED, NETWORK_ALERTING, ESTABLISHED 
 * <LI>DISCONNECTED ---> DISCONNECTED
 * <LI>FAILED ---> FAILED
 * <LI>UNKNOWN ---> UNKNOWN
 * </UL>
 */

public interface CallControlConnection extends Connection {


  /**
   * The IDLE state variable.
   */
  public static final int IDLE = 0x50;


  /**
   * The OFFERING state variable.
   */
  public static final int OFFERING = 0x51;


  /**
   * The QUEUED state variable.
   */
  public static final int QUEUED = 0x52;


  /**
   * The ALERTING state variable.
   */
  public static final int ALERTING = 0x53;


  /**
   * The INITIATED state variable.
   */
  public static final int INITIATED = 0x54;


  /**
   * The DIALING state variable.
   */
  public static final int DIALING = 0x55;


  /**
   * The NETWORK_REACHED state variable.
   */
  public static final int NETWORK_REACHED = 0x56;


  /**
   * the NETWORK_ALERTING state variable.
   */
  public static final int NETWORK_ALERTING = 0x57;


  /**
   * The ESTABLISHED state variable.
   */
  public static final int ESTABLISHED = 0x58;


  /**
   * The DISCONNECTED state variable.
   */
  public static final int DISCONNECTED = 0x59;


  /**
   * The FAILED state variable.
   */
  public static final int FAILED = 0x5A;


  /**
   * The UNKNOWN state variable.
   */
  public static final int UNKNOWN = 0x5B;


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


  /**
   * Accepts a telephone call. This method is associated most commonly
   * with ISDN-type protocols which support the OFFERING state. Incoming
   * telephony calls are sometimes first "offered" to an address for
   * acceptance. Only after a call is accepted does the standard notions
   * of alerting take place. This method returns successfully when the
   * call has been accepted and this Connection has moved into the ALERTING
   * state, otherwise an exception is thrown to signal an error.
   * <p>
   * This Connection object must be in the OFFERING state. The Provider must
   * also be IN_SERVICE. These pre-conditions are given below:
   * <p>
   * <OL>
   * <LI>((this.getCall()).getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == OFFERING.
   * </OL>
   * <p>
   * The post-conditions are given below:
   * <OL>
   * <LI>((this.getCall()).getProvider()).getState() == IN_SERVICE
   * <LI>this.getCallControlState() == ALERTING.
   * </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.
   * @exception ResourceUnavailableException An internal resource neccessary
   * for the successful invocation of this method is not available.
   * @exception PlatformException A platform-specific exception occurred.