callcontrolterminal.java

Java Telephony API .java程序

/*
#pragma ident "@(#)CallControlTerminal.java	1.17      97/02/07     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 CallControlTerminal interface extends the core Terminal interface. This
 * interface provides additional Terminal-related functionality for the
 * Call Control package.
 * <p>
 * The CallControlTerminal permits applications to place a Terminal on hold
 * or take a Terminal off of hold with respect to one of its telephone calls.
 * The CallControlTerminal interface provides the pickup() method for the 
 * Call Pickup feature.
 */

public interface CallControlTerminal extends Terminal {

  /**
   * Returns true if the do-not-disturb feature is on, false otherwise.
   * <p>
   * @return True if do not disturb is on, false if it is off.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public boolean getDoNotDisturb()
    throws PlatformException;


  /**
   * Specifices whether the do not disturb feature should be turned on for
   * this terminal. If the first argument, enable, is true, do not disturb is
   * turned on. If enable is false, do not disturb is turned off.
   * <p>
   * The Provider must in IN_SERVICE as a pre-condition for the method.
   * <OL>
   * <LI>(terminal.getProvider()).getState() == IN_SERVICE
   * </OL>
   * <p>
   * If this method returns successfully without throwing an exception, the
   * Provider is still IN_SERVICE and the do not disturb state is set to
   * the argument 'enable' as given in the post-conditions below:
   * <p>
   * <OL>
   * <LI>(terminal.getProvider()).getState() == IN_SERVICE
   * <LI>terminal.getDoNotDisturb() == enable
   * </OL>
   * <p>
   * @param enable True to turn do not disturb on, false to turn message
   * waiting off.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void setDoNotDisturb(boolean enable)
    throws PlatformException;


 /**
   * pickup() is analogous to TerminalConnection.answer(). The difference is that
   * for answer(), the Terminal that "answers" the Call is the one specified by
   * the TerminalConnection object. For pickup(), "this" Terminal is the one
   * answering the Call. pickup() picks the call from the specified Connection and
   * pulls it to "this" Terminal using the specified Address. Picking up a call changes
   * the state of the Connection from QUEUED or ALERTING to DISCONNECTED (if the Address specified
   * is different than the Address of the Connection) or CONNECTED (if the Address
   * specified is that same as the Address of the Connection). If the Addresses ARE
   * different, a new Connection (to the specified Address) is added to the Call in
   * the CONNECTED state. The TerminalConnections from the original Connection are
   * placed into the DISCONNECTED state. The proper TerminalConnections in the new 
   * Connection are created, including the
   * one to "this" Terminal. That TerminalConnection will be in the ACTIVE state and
   * is returned by pickup().
   * <p>
   * @param pickConnection The Connection to be picked.
   * @param terminalAddress The Address associated with the Terminal.
   * @returns The new TerminalConnection associated with the Terminal.
   * @exception InvalidArgumentException One of the arguments provided 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.
   */
  public TerminalConnection pickup(Connection pickConnection, Address terminalAddress)
    throws InvalidArgumentException, InvalidStateException,
           MethodNotSupportedException, PrivilegeViolationException,
           ResourceUnavailableException, PlatformException, Exception;

  /**
   * pickup() is analogous to TerminalConnection.answer(). The difference is that
   * for answer(), the Terminal that "answers" the Call is the one specified by
   * the TerminalConnection object. For pickup(), "this" Terminal is the one
   * answering the Call. pickup() picks the call from the specified TerminalConnection and
   * pulls it to "this" Terminal using the specified Address. Picking up a call changes
   * the state of the Connection that contains the specified TerminalConnection
   * from QUEUED or ALERTING to DISCONNECTED (if the Address specified
   * is different than the Address of the Connection) or CONNECTED (if the Address
   * specified is that same as the Address of the Connection). If the Addresses ARE
   * different, a new Connection (to the specified Address) is added to the Call in
   * the CONNECTED state.  The TerminalConnections from the original Connection are
   * placed into the DISCONNECTED state. The proper TerminalConnections in the new
   * Connection are created, including the
   * one to "this" Terminal. That TerminalConnection will be in the ACTIVE state and
   * is returned by pickup().
   * <p>
   * @param pickTermConn The TerminalConnection to be picked.
   * @param terminalAddress The Address associated with the Terminal.
   * @returns The new TerminalConnection associated with the Terminal.
   * @exception InvalidArgumentException One of the arguments provided 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.