Interface java.telephony.events.Ev
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.telephony.events.Ev

public interface Ev
extends Object
The Ev interface is the parent of all the specific event interfaces. All JTAPI events must extends this interface.

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.

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.

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.

The getID() method returns an event id. All JTAPI events have an event id which matches the object type.

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.

The java.telephony.events.Ev interfaces supports the getMetaCode() 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.

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.

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 isNewMetaEvent() to moniter the start of each new meta-code group.

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:

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.

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.

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.

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.

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.

The two meta-codes pertaining to a mutli-call actions are as follows:

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.

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.


Variable Index

 o CAUSE_CALL_CANCELLED
Cause code indicating the user has terminated call without going on-hook
 o CAUSE_DEST_NOT_OBTAINABLE
Cause code indicating the destination is not available
 o CAUSE_INCOMPATIBLE_DESTINATION
Cause code indicating that a call has encountered an incompatible destination
 o CAUSE_LOCKOUT
Cause code indicating that a call encountered inter digit timeout while dialing
 o CAUSE_NETWORK_CONGESTION
Cause code indicating call encountered network congestion
 o CAUSE_NETWORK_NOT_OBTAINABLE
Cause code indicating call could not reach a destination network
 o CAUSE_NEW_CALL
Cause code indicating that a new call
 o CAUSE_NORMAL
Cause code indicating normal operation
 o CAUSE_RESOURCES_NOT_AVAILABLE
Cause code indicating resouces were not available
 o CAUSE_SNAPSHOT
Cause code indicating that the event is part of a snapshot of the current state of the call.
 o CAUSE_UNKNOWN
Cause code indicating the cause was unknown
 o META_CALL_ADDITIONAL_PARTY
Meta-code description for addition of a party to call.
 o META_CALL_ENDING
Meta-code description for the entire call ending.
 o META_CALL_MERGING
Meta-code description for an action of merging two calls.
 o META_CALL_PROGRESS
 o META_CALL_REMOVING_PARTY
Meta-code description for a party leaving the call.
 o META_CALL_STARTING
 o META_CALL_TRANFERRING
Meta-code description for an action of transfering one call to another.

Method Index

 o getCause()
Returns the cause associated with this event.
 o getID()
Returns the id of event.
 o getMetaCode()
Returns the meta-code associated with this event.
 o getObserved()
Returns the object that is being observed.
 o isNewMetaEvent()

Variables

 o CAUSE_NORMAL
  public final static int CAUSE_NORMAL
Cause code indicating normal operation
 o CAUSE_UNKNOWN
  public final static int CAUSE_UNKNOWN
Cause code indicating the cause was unknown
 o CAUSE_CALL_CANCELLED
  public final static int CAUSE_CALL_CANCELLED
Cause code indicating the user has terminated call without going on-hook
 o CAUSE_DEST_NOT_OBTAINABLE
  public final static int CAUSE_DEST_NOT_OBTAINABLE
Cause code indicating the destination is not available
 o CAUSE_INCOMPATIBLE_DESTINATION
  public final static int CAUSE_INCOMPATIBLE_DESTINATION
Cause code indicating that a call has encountered an incompatible destination
 o CAUSE_LOCKOUT
  public final static int CAUSE_LOCKOUT
Cause code indicating that a call encountered inter digit timeout while dialing
 o CAUSE_NEW_CALL
  public final static int CAUSE_NEW_CALL
Cause code indicating that a new call
 o CAUSE_RESOURCES_NOT_AVAILABLE
  public final static int CAUSE_RESOURCES_NOT_AVAILABLE
Cause code indicating resouces were not available
 o CAUSE_NETWORK_CONGESTION
  public final static int CAUSE_NETWORK_CONGESTION
Cause code indicating call encountered network congestion
 o CAUSE_NETWORK_NOT_OBTAINABLE
  public final static int CAUSE_NETWORK_NOT_OBTAINABLE
Cause code indicating call could not reach a destination network
 o CAUSE_SNAPSHOT
  public final static int CAUSE_SNAPSHOT
Cause code indicating that the event is part of a snapshot of the current state of the call.
 o META_CALL_STARTING
  public final static int META_CALL_STARTING
 o META_CALL_PROGRESS
  public final static int META_CALL_PROGRESS
 o META_CALL_ADDITIONAL_PARTY
  public final static int META_CALL_ADDITIONAL_PARTY
Meta-code description for addition of a party to call. This includes adding a connection to the call.
 o META_CALL_REMOVING_PARTY
  public final static int META_CALL_REMOVING_PARTY
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.
 o META_CALL_ENDING
  public final static int META_CALL_ENDING
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.
 o META_CALL_MERGING
  public final static int META_CALL_MERGING
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.
 o META_CALL_TRANFERRING
  public final static int META_CALL_TRANFERRING
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.

Methods

 o getCause
  public abstract int getCause()
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.

Returns:
s The cause of the event.
 o getMetaCode
  public abstract int getMetaCode()
Returns the meta-code associated with this event. The meta-code provides a higher-level description of the event.

Returns:
The meta-code for this event.
 o isNewMetaEvent
  public abstract boolean isNewMetaEvent()
 o getID
  public abstract int getID()
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.

Returns:
s The id of the event.
 o getObserved
  public abstract Object getObserved()
Returns the object that is being observed.

Returns:
s The object that is being observed.

All Packages  Class Hierarchy  This Package  Previous  Next  Index