ev.java

Java Telephony API .java程序

/*
#pragma ident "@(#)Ev.java	1.7      96/11/03     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.events;

/**
 * The Ev interface is the parent of all the specific event interfaces.
 * All JTAPI events must extends this interface.
 * <p>
 * The event system is designed to notify event observers when objects in
 * the call model are changed by the telephony resource (telco switch, ISDN
 * line, phone card, IP connection, etc.).  The call model itself describes
 * the state of the switch, and the event system describes the last change to
 * that model.
 * <p>
 * Whenever the call model changes, events are sent to all appropriate
 * observers. Evs occur in the same order as changes made to the call
 * model.
 * <p>
 * The getCause() method returns a cause code. All JTAPI events
 * have a cause code associated with them. The cause codes listed here are
 * only an initial listing, more will be added later.
 * <p>
 * The getID() method returns an event id. All JTAPI events have an event
 * id which matches the object type.
 * <p>
 * There are four objects which can receive events: Provider, Terminal,
 * Address, and Call. All events are grouped into one of these four types
 * of events. See ProvEv, TermEv, AddrEv, and CallEv
 * for a listing of event types within each of those groups.
 * <p>
 * The <STRONG>java.telephony.events.Ev</STRONG> interfaces supports the
 * <EM>getMetaCode()</EM> method which returns the "meta-code" for the
 * event. The meta-code describes the higher-level action going on as the
 * call changes state. Since events represent singular changes in a paritular
 * object in a call model and many changes in the call model result in a
 * number of events being generated, it may be difficult for the application
 * to figure out the higher-level action taking place. The meta-code is
 * present on the event for provide this information.
 * <p>
 * In one batch of events delivered to applications, there may be several
 * groupings of these events belonging to the same higher-level action and
 * can be described by the same meta-code. Implementations are contrained
 * that they must deliver all events belonging to the same higher-level meta-
 * code consecutively. That is, if an event batch contains events with a
 * meta-code of META_CALL_REMOVING_PARTY and events with a meta-code of
 * META_CALL_ADDING_PARTY, these two groups of events must be together in
 * the array of events sent to the observer.
 * <p>
 * It is possible for two event batches with the same meta-code to arrive
 * contiguously in time.  Applications which need to disambiguate these 
 * batches can use the <EM>isNewMetaEvent()</EM> to moniter the start of
 * each new meta-code group.
 * <p>
 * There are five types of meta-codes which pertain to individual calls,
 * and two which pertain to a mutli-call action. The five meta-codes which
 * pertain to individual calls are:
 * <p>
 * META_CALL_STARTING: Indicates that a new active call has been presenting to
 * the application, either by an application creating a call and performing
 * an action on it, or by an incoming call to an object being observed by
 * the application.
 * <p>
 * META_CALL_PROGRESS: Indicates that the objects belonging to a call have
 * changed state, with the exception of Connections moving to DISCONNECTED.
 * For example, when a remote party answers a telephone call and the
 * corresponding Connection moves into the CONNECTED state, the meta-code
 * both the resulting batch of events is META_CALL_PROGRESS.
 * <p>
 * META_CALL_ADDING_PARTY: Indicates that a party has been addeed to the call.
 * A "party" corresponds to a Connection being added. Note that if a
 * TerminalConnection is added, it is listed as a META_CALL_PROGRESS.
 * <p>
 * META_CALL_REMOVING_PARTY: Indicates that a party (i.e. Connection) has
 * been removed from the call by moving into the DISCONNECTED state and all
 * of its TerminalConnections (if any) have moving into the DROPPED state.
 * <p>
 * META_CALL_ENDING: Indicates that an entire telephone call has ended, which
 * implies the call has moved into the INVALID state and all of its
 * Connections and associated TerminalConnections have moved into the
 * DISCONNECTED and DROPPED state, respectively.
 * <p>
 * The two meta-codes pertaining to a mutli-call actions are as follows:
 * <p>
 * META_CALL_MERGING: Indicates that a party has moved from one call to
 * another as part of the two calls merging. A common example is when two
 * telephone calls are conferenced.
 * <p>
 * META_CALL_TRANFERRING: Indicates that a party has moved from one call to
 * another as part of one call being transferred to another. The differs from
 * META_CALL_MERGING because a common party to both calls drops off both
 * calls.
 */

public interface Ev {

  /**
   * Cause code indicating normal operation
   */
  public static final int CAUSE_NORMAL = 100;

  /**
   * Cause code indicating the cause was unknown
   */
  public static final int CAUSE_UNKNOWN = 101;

  /**
   * Cause code indicating the user has terminated
   * call without going on-hook
   */
  public static final int CAUSE_CALL_CANCELLED = 102;

  /**
   * Cause code indicating the destination is not
   * available
   */
  public static final int CAUSE_DEST_NOT_OBTAINABLE = 103;

  /**
   * Cause code indicating that a call has encountered
   * an incompatible destination
   */
  public static final int CAUSE_INCOMPATIBLE_DESTINATION = 104;

  /**
   * Cause code indicating that a call encountered inter
   * digit timeout while dialing
   */
  public static final int CAUSE_LOCKOUT = 105;

  /**
   * Cause code indicating that a new call
   */
  public static final int CAUSE_NEW_CALL = 106;

  /**
   * Cause code indicating resouces were not available
   */
  public static final int CAUSE_RESOURCES_NOT_AVAILABLE = 107;

  /**
   * Cause code indicating call encountered network congestion
   */
   public static final int CAUSE_NETWORK_CONGESTION = 108;

  /**
   * Cause code indicating call could not reach a destination network
   */
   public static final int CAUSE_NETWORK_NOT_OBTAINABLE = 109;

  /**
   * Cause code indicating that the event is part of a snapshot of the
   * current state of the call.
   */
  public static final int CAUSE_SNAPSHOT = 110;


  /*
   * Meta-code description for the initiation or starting of a call. This
   * implies that the call is a new call and in the active state with at least
   * one Connection added to it.
   */
  public static final int META_CALL_STARTING = 0x80;


  /*
   * Meta-code description for the progress of a call. This indicates an
   * update in state of certain objects in the call, or the addition of
   * TerminalConnections (but not Connections).
   */
  public static final int META_CALL_PROGRESS = 0x81;


  /**
   * Meta-code description for addition of a party to call. This includes
   * adding a connection to the call.
   */
  public static final int META_CALL_ADDITIONAL_PARTY = 0x82;


  /**
   * Meta-code description for a party leaving the call. This includes
   * exactly one Connection moving to the DISCONNECTED state and all of
   * its TerminalConnections moving to the DROPPED state.
   */
  public static final int META_CALL_REMOVING_PARTY = 0x83;


  /**
   * Meta-code description for the entire call ending. This includes
   * the call going to INVALID, all of the Connections moving to the
   * DISCONNECTED state and all of the TerminalConnections moving to the
   * DROPPED state.
   */
  public static final int META_CALL_ENDING = 0x84;


  /**
   * Meta-code description for an action of merging two calls. This
   * involves the removal of one party from one call and the addition
   * of the same party to another call. For this meta-code, the events
   * may either be the addition of a party or the removal of a party
   * for this particular call.
   */
  public static final int META_CALL_MERGING = 0x85;


  /**
   * Meta-code description for an action of transfering one call to another.
   * This involves the removal of parties from one call and the addition
   * to another call, and the common party dropping off completely.
   */
  public static final int META_CALL_TRANFERRING = 0x86;
 

  /**
   * Returns the cause associated with this event. Every event has a cause.
   * The various cause values are defined as public static final variablies
   * in this interface.
   * <p>
   * @returns The cause of the event.
   */
  public int getCause();


  /**
   * Returns the meta-code associated with this event. The meta-code provides
   * a higher-level description of the event.
   * <p>
   * @return The meta-code for this event.
   */
  public int getMetaCode();

  /* Returns TRUE when this event is the start of a meta-code group.
   * <EM>isNewMetaEvent</EM> is used to distinguish two contiguous
   * groups of events bearing the same meta-code.
   * <p>
   * @return Boolean
   */
  public boolean isNewMetaEvent();


  /**
   * Returns the id of event. Every event has an id.
   * The defined id of each event matches the object type of each
   * event. The defined id allows applications to switch on event
   * id rather than having to use multiple "if instanceOf" statements.
   * <p>
   * @returns The id of the event.
   */
  public int getID();


  /**
   * Returns the object that is being observed.
   * <p>
   * @returns The object that is being observed.
   */
   public Object getObserved();
}