callctloverview.html

JTAPI_html 用于JTAPI的HTML文档.

<P>
In addition to the allowable transitions of Connection states in the Call
Control Package, the mapping of the Connection states to the
CallControlConnection states is important. This mapping implies that when
the CallControlConnection state is a certain states, it implies the
Connection state must be a certain state. Although applications should only
monitor one set of states, it is neccessary to provide this mapping to
maintain consistency.
</P>
<P>
The following chart describes the state of the Connection in the Call Control
Package (on the right) and the state of the Connection in the core package
(on the left). Note that applications may obtain the core Connection state
via the method Connection.getState() and applications may obtain the
Call Control Package Connection states via the
CallControlConnection.getCallControlState() method.
</P>
<IMG SRC="images/CallCtlConnRelation.gif" align="middle">

<BR>

<H3>CallControlTerminalConnection States</H3>

<IMG SRC="images/cyan-ball.gif">
IDLE state

<P>
<OL>
The IDLE state has the same meaning as in the TerminalConnection. It is the
initial state for all CallControlTerminalConnection objects.
</OL>
</P>


<IMG SRC="images/cyan-ball.gif">
RINGING state

<P>
<OL>
The RINGING state has the same meaning
as the TerminalConnection's RINGING state. It implies that a Terminal is ringing
because of an incoming telephone call.
</OL>
</P>

<IMG SRC="images/cyan-ball.gif">
BRIDGED state

<P>
<OL>
The BRIDGED state indicates that a
Terminal is bridged into an active telephone call. Although the Terminal
is not actively part of the telephone call is may become so by joining the
call. Although not actively part of the telephone call, the resource
associated with this bridge on the Terminal is being used.
</OL>
</P>


<IMG SRC="images/cyan-ball.gif">
INUSE state

<P>
<OL>
The INUSE state indicates that a
Terminal is not actively part of a call nor bridged into a call, but still
part of the telephone call. Although the Terminal cannot join the Call, the
resource on the Terminal associated with this Call is still being used.
</OL>
</P>


<IMG SRC="images/cyan-ball.gif">
TALKING state

<P>
<OL>
The TALKING state indicates that a
Terminal is actively part of a telephone call. It is similar to the
TerminalConnection's TALKING state, however that state has a more general
definition. The TALKING state implies that
Terminal is talking on the telephone call versus being held.
</OL>
</P>


<IMG SRC="images/cyan-ball.gif">
HELD state

<P>
<OL>
The HELD state indicates that a Terminal
is actively part of a telephone call, however it is currently on hold.
</OL>
</P>


<IMG SRC="images/cyan-ball.gif">
DROPPED state

<P>
<OL>
The DROPPED state has the same meaning
as the TerminalConnection's DROPPED state. The Terminal was once part of a
telephone call but no longer is. As in the core, this state is the final
state for all TerminalConnections in the Call Control Package.
</OL>
</P>


<IMG SRC="images/cyan-ball.gif">
UNKNOWN state

<P>
<OL>
The UNKNOWN state has the same meaning as the TerminalConnection's UNKNOWN
state.
</OL>
</P>

<BR>

<H3>State Transitions for the CallControlTerminalConnection Interface</H3>
<P>
In the overview of the core TerminalConnection states, a finite state machine
described the allowable transitions from one TerminalConnection state to the
other. This state diagram provides insight to the application developer on how
TerminalConnections may move from one state to another. The following diagram
is the analogous state diagram for the CallControlTerminalConnection states.
</P>
<IMG SRC="images/CallCtlTermConnStates.gif" align="middle">

<BR>

<H3>Relationshiop between TerminalConnection and
CallControlTerminalConnection States</H3>
<P>
In addition to the allowable transitions of TerminalConnection states in the Call Control Package, the mapping of the TerminalConnection states to the
CallControlTerminalConnection states is important. This mapping implies that
when the CallControlConnection state is a certain states, it implies the
TerminalConnection state must be a certain state. Although applications should
only monitor one set of states, it is neccessary to provide this mapping to
maintain consistency.
</P>
<P>
The following chart describes the state of the TerminalConnection in the Call
Control Package (on the right) and the state of the TerminalConnection in the
core package (on the left). Note that applications may obtain the core
TerminalConnection state via the method TerminalConnection.getState() and
applications may obtain the Call Control Package TerminalConnection states via
the CallControlTerminalConnection.getCallControlState() method.
</P>

<IMG SRC="images/CallCtlTermConnRelation.gif" align="middle">


<BR>

<H2>
<A NAME="CONNECT">Timeline for Telephone Calls</A>
<HR>
</H2>


<P>
The Overview document for the core Java Telephony API presented a timeline
diagram of the state transitions for Connections and TerminalConnections in
a likely scenario resulting from a Call.connect() invocation. These diagrams
are the best means to understand the API during different situations. In this
section, a similar diagram is presented describing the outcome of placing
a telephone call in terms of the CallControl states.
</P>
<P>
In the diagram below, time is the vertical axis where time increases going
down the page. The solid vertical lines denote various objects: Call, Terminal,
and Address. The solid horizontal lines between the Call and Address represent
a Connection and the dotted horizontal lines between the Address and Terminal
represent TerminalConnections. Each discrete change in the call model is
denoted by a number along the left-hand side of the page. More than one change
may occur to the call model during a single discrete step; the application
sees these changes as happening all at once.
</P>
<P>
In the scenario below, the originating side has one Terminal associated with
it and the destination side has two Terminals (denoted in the diagram as
'A' and 'B') associated with it. The switch is configured to bridge all
Terminals which are not actively part of a telephone call but share an address
which is active. This scenario shows how a telephone call is placed and
completed to one of the destination Terminals. Then, the second terminal joins
the call using the join() method from this package. Finally, the originator
hangs up his phone and the entire call becomes disconnected.
</P>
<IMG SRC="images/CallCtlConnect.gif" align="middle">

<BR><BR>

<H2>
<A NAME="OUTCALL">OutCall Code Example</A>
<HR>
</H2>

<P>
The following code example placing a telephone call using the core
Call.connect() method. It, however, looks for the states provided by the
Call Control package.
</P>

<PRE>
import java.telephony.*;
import java.telephony.events.*;
import java.telephony.callcontrol.*;
import java.telephony.callcontrol.events.*;

/*
 * The MyCallObserver class implements the CallControlCallObserver
 * interface and receives all events associated with the Call. 
 */

public class MyCallObserver implements CallControlCallObserver {

  public void callChangedEvent(CallEv[] evlist) {

    for (int i = 0; i < evlist.length; i++) {

      if (evlist[i] instanceof ConnEv) {

        String name = null;
        try {
          Connection connection = evlist[i].getConnection();
          Address addr = connection.getAddress();
          name = addr.getName();
        } catch (Exception excp) {
          // Handle Exceptions
        }

        String msg = "Connection to Address: " + name + " is ");

        if (evlist[i].getID() == CallCtlConnInitiatedEv.ID) {
          System.out.println(msg + "INITIATED");
        }
        else if (evlist[i].getID() == CallCtlConnDialingEv.ID) {
          System.out.println(msg + "DIALING");
        }
        else if (evlist[i].getID() == CallCtlConnEstablishedEv.ID) {
          System.out.println(msg + "ESTABLISHED");
        }
        else if (evlist[i].getID() == CallCtlConnAlertingEv.ID) {
          System.out.println(msg + "ALERTING");
        }
        else if (evlist[i].getID() == CallCtlConnDisconnectedEv.ID) {
          System.out.println(msg + "DISCONNECTED");
        }
      }
    }
  }
}


/*
 * Places a telephone call from 476111 to 5551212
 */
public class SampleOutcall {

  public static final void main(String args[]) {

    /*
     * Create a provider by first obtaining the default implementation of
     * JTAPI and then the default provider of that implementation.
     */
    Provider myprovider = null;
    try {
      JtapiPeer peer = JtapiPeerFactory.getJtapiPeer(null);
      myprovider = peer.getProvider(null);
    } catch (Exception excp) {
      System.out.println("Can't get Provider: " + excp.toString());
      System.exit(0);
    }

   /*
    * We need to get the appropriate objects associated with the
    * originating side of the telephone call. We ask the Address for a list
    * of Terminals on it and arbitrarily choose one.
    */
    Address origaddr = null;
    Terminal origterm = null;
    try {
      origaddr = myprovider.getAddress("4761111");

      /* Just get some Terminal on this Address */
      Terminal[] terminals = origaddr.getTerminals();
      if (terminals == null) {
        System.out.println("No Terminals on Address.");
        System.exit(0);
      }
      origterm = terminals[0];
    } catch (Exception excp) {
      // Handle exceptions;
    }


    /*
     * Create the telephone call object and add an observer.
     */
    Call mycall = null;
    try {
      mycall = myprovider.createCall();
      mycall.addObserver(new MyCallObserver());
    } catch (Exception excp) {
      // Handle exceptions
    }

    /*
     * Place the telephone call.
     */
    try {
      Connection c[] = mycall.connect(origterm, origaddr, "5551212");
    } catch (Exception excp) {
      // Handle all Exceptions
    }
  }
}
</PRE>

<BR>

<H2>
<A NAME="INCALL">InCall Code Example</A>
<HR>
</H2>


<P>
The following code example illustrates how an application answers a Call
at a particular Terminal. It shows how application accept calls when (and if)
they are offered to it. This code example greatly resembles the core InCall
code example.
</P>

<PRE>

import java.telephony.*;
import java.telephony.events.*;
import java.telephony.callcontrol.*;
import java.telephony.callcontrol.events.*;

/*
 * The MyObserver class implements the CallControlCallObserver and
 * recieves all Call-related events.
 */

public class MyObserver implements CallControlCallObserver {

  public void callChangedEvent(CallEv[] evlist) {

    for (int i = 0; i < evlist.length; i++) {

      if (evlist[i] instanceof TermConnEv) {
        TerminalConnection termconn = null;
        String name = null;

        try {
          TermConnEv tcev = (TermConnEv)evlist[i];
          TerminalConnection termconn = tcev.getTerminalConnection();
          Terminal term = termconn.getTerminal();
          String name = term.getName();
        } catch (Exception excp) {
          // Handle exceptions.
        }

        String msg = "TerminalConnection to Terminal: " + name + " is ";

        if (evlist[i].getID() == CallCtlTermConnTalkingEv.ID) {
          System.out.println(msg + "TALKING");
        }
        else if (evlist[i].getID() == CallCtlTermConnRingingEv.ID) {
          System.out.println(msg + "RINGING")

          /* Answer the telephone Call */
          try {
            termconn.answer();
          } catch (Exception excp) {
            // Handle Exceptions;
          }
        }
        else if (evlist[i].getID() == CallCtlTermConnDroppedEv.ID) {
          System.out.println(msg + "DROPPED");
        }
      }
    }
  }
}


/*
 * Create a provider and monitor a particular terminal for an incoming call.
 */
public class SampleIncall {

  public static final void main(String args[]) {
 
    /*
     * Create a provider by first obtaining the default implementation of
     * JTAPI and then the default provider of that implementation.
     */
    Provider myprovider = null;
    try {
      JtapiPeer peer = JtapiPeerFactory.getJtapiPeer(null);
      myprovider = peer.getProvider(null);
    } catch (Exception excp) {
      System.out.println("Can't get Provider: " + excp.toString());
      System.exit(0);
    }

    /*
     * Get the terminal we wish to monitor and add a call observer to that
     * Terminal. This will place a call observer on all call which come to
     * that terminal. We are assuming that Terminals are named after some
     * primary telephone number on them.
     */
    try {
      Terminal terminal = myprovider.getTerminal("4761111");
      terminal.addCallObserver(new MyCallObserver());
    }
  }
}