Interface java.telephony.callcontrol.CallControlConnection
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.telephony.callcontrol.CallControlConnection

public interface CallControlConnection
extends Object
extends Connection
The CallControlConnection interface extends the core Connection interface. The CallControlConnection interface provides greater details about the state of the Connection object. For many of the core Connection object states, the CallControlConnection interfaces often provides several sub- states of the core states. These sub-states provide more information to application about what is going on. The method getCallControlState() returns this more detailed state. Typically, applications with either monitor the core Connection states or the CallControlConnection states.

The Connection states presented by this interface are: IDLE, OFFERING, QUEUED, NETWORK_REACHED, NETWORK_ALERTING, ALERTING, INITIATED, DIALING, ESTABLISHED, DISCONNECTED, FAILED, BUSY, UNKNOWN.

The real-world definitions for these states follow. Note that these definitions are not technical nor absolute, however, they give an idea to the reader about what these states means:

The IDLE state is defined similiarly here as it is in the core. The IDLE state is the initial and transitory state for new Connection objects.

The OFFERING state is particular to ISDN and indicates that a Call is being offered. Typically, applications must accept or reject this offered call.

The QUEUED state indicates that a Connection is queued at a particular address. This may result when someone enables the queueing mechanism on an address and the address is busy when a telephone call comes in.

The NETWORK_REACHED state indicates that the outgoing telephone call has reached the network, however, further events may not be received. It is up to the application whether to treat this as a connected call.

The NETWORK_ALERTING state indicates that the outgoing telephone call has previously reached the network, however, further information obtained from the switch indicates that this call is now alerting at some destination endpoint.

The ALERTING state has the same definition as in the core.

The INITIATED state indicates that an originating Connection's telephone is off-hook, however, dialing has not yet begun.

The DIALING state applies to originating Connections and indicates that the process of dialing has begun but has not yet completed.

The ESTABLISHED state has a similar definition as CONNECTED does in the core. It indicates that a Connection has reached its final active state in the call.

The DISCONNECTED state has the same definition as in the core.

The FAILED state has the same definition as in the core.

The UNKNOWN state has the same definition as in the core.

These CallControlConnection states are defined in terms of the core Connection states. In other words, if the core Connection is in a particular state, then the CallControlConnection must be in one of possible several states. This relationship is defined below, where the core Connection states are on the left, and the CallControlConnection states are on the right.


Variable Index

 o ALERTING
The ALERTING state variable.
 o DIALING
The DIALING state variable.
 o DISCONNECTED
The DISCONNECTED state variable.
 o ESTABLISHED
The ESTABLISHED state variable.
 o FAILED
The FAILED state variable.
 o IDLE
The IDLE state variable.
 o INITIATED
The INITIATED state variable.
 o NETWORK_ALERTING
the NETWORK_ALERTING state variable.
 o NETWORK_REACHED
The NETWORK_REACHED state variable.
 o OFFERING
The OFFERING state variable.
 o QUEUED
The QUEUED state variable.
 o UNKNOWN
The UNKNOWN state variable.

Method Index

 o accept()
Accepts a telephone call.
 o addToAddress(String)
Appends additional address information onto an existing Connection.
 o getCallControlState()
Returns the current CallControl state of the Connection.
 o park(String)
Parks an active Connection to another Address.
 o redirect(String)
Redirects a telephone call to another telephone number.
 o reject()
Rejects a telephone call.

Variables

 o IDLE
  public final static int IDLE
The IDLE state variable.
 o OFFERING
  public final static int OFFERING
The OFFERING state variable.
 o QUEUED
  public final static int QUEUED
The QUEUED state variable.
 o ALERTING
  public final static int ALERTING
The ALERTING state variable.
 o INITIATED
  public final static int INITIATED
The INITIATED state variable.
 o DIALING
  public final static int DIALING
The DIALING state variable.
 o NETWORK_REACHED
  public final static int NETWORK_REACHED
The NETWORK_REACHED state variable.
 o NETWORK_ALERTING
  public final static int NETWORK_ALERTING
the NETWORK_ALERTING state variable.
 o ESTABLISHED
  public final static int ESTABLISHED
The ESTABLISHED state variable.
 o DISCONNECTED
  public final static int DISCONNECTED
The DISCONNECTED state variable.
 o FAILED
  public final static int FAILED
The FAILED state variable.
 o UNKNOWN
  public final static int UNKNOWN
The UNKNOWN state variable.

Methods

 o getCallControlState
  public abstract int getCallControlState() throws PlatformException
Returns the current CallControl state of the Connection. The return value will be one of states defined above.

Returns:
The current CallControl state of the Connection.
Throws: PlatformException
A platform-specific exception occurred.
 o accept
  public abstract void accept() throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Accepts a telephone call. This method is associated most commonly with ISDN-type protocols which support the OFFERING state. Incoming telephony calls are sometimes first "offered" to an address for acceptance. Only after a call is accepted does the standard notions of alerting take place. This method returns successfully when the call has been accepted and this Connection has moved into the ALERTING state, otherwise an exception is thrown to signal an error.

This Connection object must be in the OFFERING state. The Provider must also be IN_SERVICE. These pre-conditions are given below:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == OFFERING.

The post-conditions are given below:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == ALERTING.

Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o reject
  public abstract void reject() throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Rejects a telephone call. This method is associated most commonly with ISDN-type protocols which support the OFFERING state. Incoming telephony calls are sometimes first "offered" to an address for acceptance. Only after a call is accepted does the standard notions of alerting take place. A call may also be rejected, where the call does not proceed to the alerting stage. This method returns when this Connection successfully moves into the DISCONNECTED state, otherwise, an exception is thrown to signal an error.

This Connection object must be in OFFERING state. The Provider must also be IN_SERVICE. These pre-conditions are given below:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == OFFERING.

The post-conditions are given below:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == DISCONNECTED.

Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o redirect
  public abstract CallControlConnection redirect(String destinationAddress) throws InvalidStateException, InvalidPartyException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Redirects a telephone call to another telephone number. This feature is very similar to a transfer feature, however, the application may use the redirect() method when the Connection is either in the ALERTING or OFFERING CallControlConnection states. The telephone address provided must be valid and complete.

The Connection must be in the OFFERING or ALERTING state. The first argument, destinationAddress, must be a valid telephone number to dial. The Connection must also be associated with this Address object and the Provider must be IN_SERVICE. These pre-conditions are given below:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == OFFERING or ALERTING
  3. destinationAddress must be a valid telephone number.

If successful, this method creates a new Connection associated with the Address object, as given by the destinationAddress string. This new Connection is in the IDLE state and is returned by this method. The Connection given as an argument moves to the DISCONNECTED state when this method returns. All of its TerminalConnections move to the DROPPED state as well. These post-conditions are given as follows, where 'connection' is the argument, and 'newconnection' is the return value.

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == DISCONNECTED.
  3. newconnection.getCallControlState() == IDLE
  4. Let TerminalConnection tc[] = this.getTerminalConnections()
  5. For all i, tc[i].getCallControlState() == DROPPED

The newconnection object acts similar to a destination connection when a telephone call is first placed. The Call.connect() method provides the scenarios for this destination Connection and the possible state changes it may undergo.

Parameters:
desintationAddress - The Connection is rerouted to this address
Returns:
The new Connection associated with the Address object of the new address.
Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: InvalidPartyException
The party to which this call is redirected is not valid.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
Throws: Exception
An implementation-specific exception occurred.
 o addToAddress
  public abstract void addToAddress(String additionalAddress) throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Appends additional address information onto an existing Connection. This method is used when part of a telephone number has been dialed and the application may complete the address with this method.

This Connection must be in the DIALING or INITIATED state and the Provider must also be IN_SERVICE. These pre-conditions are given below:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == DIALING | INITIATED.

The post-conditions of this method depend upon whether the provided additional addressing information is enough to complete the address. This is determined by the switch. If the additional addressing information is enough, the Connection moves from the DIALING state into the ESTABLISHED state. If not, the Connection remains in the DIALING state. The following post-conditions reflect this:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == DIALING if the addressing information was not enough as determined by the switch.
  3. this.getCallControlState() == ESTABLISHED if the addressing information was sufficient to complete the address, determined by the switch

Parameters:
additionalAddress - The additional addressing information.
Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o park
  public abstract CallControlConnection park(String destAddress) throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, InvalidPartyException, ResourceUnavailableException, PlatformException
Parks an active Connection to another Address. "Parking" a Connection transfers that Connection to another address and drops it from the current telephone call. The Call Parking feature is very much like transfering a telephone call except the new address does not alert. The new Connection is in a special QUEUED state. Applications may then use the pickup() method to "unpark" this call. The telephone address provided must be valid and complete.

This Connection must be in the ESTABLISHED state. The destAddress parameter must be a complete, valid telephone number which can be dialed. The Provider must also be IN_SERVICE. These pre- conditions are given below:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. this.getCallControlState() == ESTABLISHED
  3. destAddress must be a valid and complete telephone number.

This method moves the connection into the DISCONNECTED state and creates a new connection attached to an Address object which corresponds to the destAddress argument. This new connection is in the CallControlConnection QUEUED state and is returned by this method. ALl of the TerminalConnections which are part of this Connection move to the DROPPED state. The post conditions for this method are given below, where 'newconnection' is the Connection returned by this method.

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. newconnection.getCallControlState() == QUEUED
  3. this.getCallControlState() == DISCONNECTED
  4. For all termconn = this.getTerminalConnections(), termconn.getState() == DROPPED

Parameters:
destAddress - The address at which this connection is to be parked.
Returns:
The new Connection.
Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: InvalidPartyException
The party to which to party the Connection is invalid.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.

All Packages  Class Hierarchy  This Package  Previous  Next  Index