callcontroladdress.java

Java Telephony API .java程序

/*
#pragma ident "@(#)CallControlAddress.java	1.15      97/01/22     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 CallControlAddress interface extends the core Address interface. It
 * provides additional methods which perform more advanced features on a
 * per-address basis.
 * <p>
 * These additional methods include setting the forwarding characteristics,
 * the do-not-disturb characteristics, and the message waiting characteristics.
 */

public interface CallControlAddress extends Address {

  /**
   * Sets the forwarding characteristics for this telephony Address. This
   * forwarding command cancels all previous forwarding instructions. This
   * method takes an array of CallControlForwarding object. Each object
   * describe a different rule for different types of forwarding.
   * <p>
   * @param instructions An array of address forwarding instructions
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void setForwarding(CallControlForwarding[] instructions)
    throws PlatformException;


  /**
   * Returns an array of forwarding instructions currently set for this 
   * telephone Address. If there are no instructions, this method returns null.
   * <p>
   * @return An array of address forwarding instructions, null if there are 
   * none.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallControlForwarding[] getForwarding()
    throws PlatformException;


  /**
   * Cancels all of the forwarding instructions on this Address. When this
   * method completes, the getForwarding() will return null.
   * <p>
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void cancelForwarding()
    throws PlatformException;


  /**
   * Returns true if the do-not-disturb feature is on, false otherwise. The
   * Provider must be IN_SERVICE
   * <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 address. 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>(address.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>(address.getProvider()).getState() == IN_SERVICE
   * <LI>address.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;


  /**
   * Returns true if message waiting is turned on, false otherwise. The
   * Provider must be IN_SERVICE.
   * <p>
   * @return True if message waiting is on, false if it is off.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public boolean getMessageWaiting()
    throws PlatformException;


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