java.telephony.call.html

JTAPI_html 用于JTAPI的HTML文档.

  </dl>
</dl>
<a name="getProvider()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="getProvider"><b>getProvider</b></a>
<pre>
  public abstract <a href="java.telephony.Provider.html#_top_">Provider</a> getProvider() throws <a href="java.telephony.PlatformException.html#_top_">PlatformException</a>
</pre>
<dl>
  <dd> Returns the provider associated with the call. The Provider object does
not change throughout the lifetime of the Call object. This method returns
the same value no matter what the Call state is. If the Call state is
Call.INVALID, this method returns the proper Provider object, however the
Provider object has lost its reference (see Provider.getCalls()) to this
Call object to faciliate the garbage collection of the Call object.
<p>
  <dl>
    <dt> <b>Returns:</b>
    <dd> The Provider associated with the call.
    <dt> <b>Throws:</b> <a href="java.telephony.PlatformException.html#_top_">PlatformException</a>
    <dd> A platform-specific exception occurred.
  </dl>
</dl>
<a name="getState()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="getState"><b>getState</b></a>
<pre>
  public abstract int getState() throws <a href="java.telephony.PlatformException.html#_top_">PlatformException</a>
</pre>
<dl>
  <dd> Returns the current state of the telephone call. The state will be
one of the state constants defined above.
<p>
  <dl>
    <dt> <b>Returns:</b>
    <dd> The current state of the call, either IDLE, ACTIVE, or INVALID.
    <dt> <b>Throws:</b> <a href="java.telephony.PlatformException.html#_top_">PlatformException</a>
    <dd> A platform-specific exception occurred.
  </dl>
</dl>
<a name="connect(java.telephony.Terminal, java.telephony.Address, java.lang.String)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="connect"><b>connect</b></a>
<pre>
  public abstract <a href="java.telephony.Connection.html#_top_">Connection</a>[] connect(<a href="java.telephony.Terminal.html#_top_">Terminal</a> origterm,
                                       <a href="java.telephony.Address.html#_top_">Address</a> origaddr,
                                       <a href="java.lang.String.html#_top_">String</a> dialedDigits) throws <a href="java.telephony.ResourceUnavailableException.html#_top_">ResourceUnavailableException</a>, <a href="java.telephony.PrivilegeViolationException.html#_top_">PrivilegeViolationException</a>, <a href="java.telephony.InvalidPartyException.html#_top_">InvalidPartyException</a>, <a href="java.telephony.InvalidArgumentException.html#_top_">InvalidArgumentException</a>, <a href="java.telephony.InvalidStateException.html#_top_">InvalidStateException</a>, <a href="java.telephony.MethodNotSupportedException.html#_top_">MethodNotSupportedException</a>, <a href="java.telephony.PlatformException.html#_top_">PlatformException</a>
</pre>
<dl>
  <dd> Connect a pair of connections to a call. The Call must be in the Call.IDLE
state and its Provider must be in the Provider.IN_SERVICE state. Because
the Call must be in the Call.IDLE state for the success of this method,
the Call must by definition have no existing Connections associated with
it.
<p>
The first argument is the originating Terminal for the telephone call.
The second argument represents the Address from which the call is placed.
The originating address must be one of the addresses associated with the
originating Terminal, otherwise an exception is thrown. The third
argument is the string address to which the phone call is being placed.
This is also known as the destination address and must be a valid and
complete telephone address.
<p>
The pre-condition predicates for this method indicate which statements
must be true in order for this method to succeed. However, these
predicates do not guarantee the success of this method.
<p>
<OL>
<LI>(this.getProvider()).getState() == Provider.IN_SERVICE
<LI>this.getState() == Call.IDLE
</OL>
<p>
The post-condition predicates for the Call.connect() method are as
follows. Note that the eventual outcome of this method is described by
a number of scenarios below. These post-conditions only reflect the state
immediately after the <EM>Call.connect()</EM> returns.
<p>
<OL>
<LI>(this.getProvider()).getState() == Provider.IN_SERVICE
<LI>this.getState() == Call.ACTIVE
<LI>Let Connection c[] = this.getConnections()
<LI>c.length == 2
<LI>c[0].getState() == Connection.IDLE
<LI>c[1].getState() == Connection.IDLE
</OL>
<p>
Two scenarios of the eventual outcome of this method are given below.
Note, what is termed the "normal" operation of this method results in an
active telephone call. A sequence of discrete call model changes is given
by a list of discrete steps each labelled with a number. Changes in the
call model falling under the same number are seen by the application as
happening at once. These two scenarios do not represent all the possible
outcomes of the <EM>Call.connect</EM> method. These scenarios just
represent two typical scenarios.
<p>
Scenario 1: The "normal" operation of this method, where the result is
two ends participating in an active telephone call.
<p>
<OL>
<LI>The Call.connect() is method invoked with the given arguments.
<LI>Exactly two connections are created, each in the Connection.IDLE
   state. The first connection created represents the originating end of
  the call. The second connection created represents the destination end
  of the call.
<p>
   The Call.connect() method returns, returning a two-element array of
   Connections. The first element at index 0 represents the originating
   Connection. The second element at index 1 represents the destination
   Connection. Both Connections are in the Connection.IDLE state.
<p>
   The following events are delivered to the application via a
   CallObserver on this Call: a <EM>java.telephony.events.CallActiveEv</EM>, a
   <EM>java.telephony.events.ConnCreatedEv</EM> for each of the two Connections
   created.
<p>
<LI>Once the Provider begins to place the telephone call, the originating
   Connection moves from the Connection.IDLE state into the
   Connection.CONNECTED state. A TerminalConnection is created in the
   TerminalConnection.ACTIVE state between the originating Terminal and
   the Call.
<p>
   The following events are delivered to the application via a
   CallObserver on this Call: a <EM>java.telephony.events.ConnConnectedEv</EM>
   for the originating Connection, a
   <EM>java.telephony.events.TermConnCreatedEv</EM> for the new
   TerminalConnection created, and a
   <EM>java.telephony.events.TermConnActiveEv</EM> for the new Terminal
   Connection.
<p>
  Depending upon the configuration of the switch, additional
  TerminalConnections may be created. These TerminalConnections will be
  associated with Terminals which have the originating Address as one of
  their Addresseses. Unfortunately, there is no way for the implementation
  to tell which TerminalConnections will be created in advance, only that
  the number cannot be greater than the number of Terminals associated
  with the originating Address and each TerminalConnection must go to
  one of those Terminals associated with the originating Address. If such
  a Terminal Connection is created, it will be in the
  TerminalConnection.PASSIVE state.
<p>
  Additional events are delivered because of the above paragraph: a
  <EM>java.telephony.events.TermConnCreateEv</EM> for all additional
  Terminal Connections created, and a
  <EM>java.telephony.events.TermConnPassiveEv</EM> for each of those Terminal
  Connections.
<LI>The destination Connection moves from the Connection.IDLE state into
   the TerminalConnection.INPROGRESS state.
<p>
   The following events are delivered to the application via the
   CallObserver interface: a <EM>java.telephony.events.ConnInProgressEv</EM>
   for the destination Connection.
<LI>The destination Connection moves from the Connection.INPROGRESS state
   to the Connection.ALERTING state. TerminalConnection objects are
   created between the Call and every Terminal object associated with the
   destination Address in the TerminalConnection.RINGING state.
<p>
   The following events are delivered to the application via a CallObserver
   on this Call: a <EM>java.telephony.events.ConnAlertingEv</EM> for the
   destination Connection, a <EM>java.telephony.events.TermConnCreatedEv</EM>
   for all Terminal Connections created to Terminals with the destination
   Address, a <EM>java.telephony.events.TermConnRingingEv</EM> for all those
   new TerminalConnections.
<p>
   The following events are delivered to the application via the
   CallObserver on this Call: a <EM>java.telephony.events.ConnConnectedEv</EM>
   for the destination Connection, and a
   <EM>java.telephony.events.TermConnActiveEv</EM> for the TerminalConnection
   which answered the telephone call.
<p>
   For all other TerminalConnections in the TerminalConnection.RINGING
   state on the destination side, either one of two things will happen
   depending upon the configuration of the switch. Unfortunately, the
   implementation is unable to determine the behavior of the switch
   beforehand. In one situation, these TerminalConnections move from
   the TerminalConnection.RINGING state to the TerminalConnection.PASSIVE
   state. In the second situation, these TerminalConnections move from the
   TerminalConnection.RINGING state to the TerminalConnection.DROPPED
   state.
<p>
   Because of the paragraph above, the following events will be delivered
   to the application via the CallObserver interface on this Call:
   a <EM>java.telephony.events.TermConnPassiveEv</EM> in one situation, or
   a <EM>java.telephony.events.TermConnDroppedEv</EM> in the other situation.
</OL>
<p>
The post-condition predicates for scenario 1 are as follows. These
post-conditions state what is true about the call model after the final
step of scenario 1 completes.
<p>
<OL>
<LI>this.getState() == Call.ACTIVE
<LI>(this.getProvider()).getState() == Provider.IN_SERVICE
<LI>Let Connection c[] = this.getConnections()
<LI>c[0].getState == Connection.CONNECTED
<LI>c[1].getState == Connection.CONNECTED
<LI>Let TerminalConnection origtc[] = c[0].getTerminalConnections()
<LI>There exists an i, such that origtc[i].getState() ==
TerminalConnection.ACITVE.
<LI>Let TerminalConnection desttc[] = c[1].getTerminalConnections()
<LI>There exists an i, such that desttc[i].getState() ==
TerminalConnection.ACTIVE.
</OL>
<p>
Scenario 2: The desired telephone call is placed however the completion
of the call is impossible because of a failure. For example, this
scenario will occur if the destination address is busy. In this scenario
the destination Connection never reaches the ALERTING state. (i.e. the
destination party is never alerted to this telephone call)
<p>
<OL>
<LI>The Call.connect() is method invoked with the given arguments.
<LI>Exactly two connections are created, each in the Connection.IDLE
   state. The first connection created represents the originating end of
  the call. The second connection created represents the destination end
  of the call.
<p>
   The Call.connect() method returns, returning a two-element array of