javax.telephony.callcontrol
Interface CallControlConnection

All Superinterfaces:

Connection

public interface CallControlConnection

extends Connection

Introduction

The CallControlConnection interface extends the core Connection interface and provides additional features and greater detail about the Connection state. Applications may query a Connection object using the instanceof operator to see whether it supports this interface.

CallControlConnection State

This interface defines states for the Connection which provide greater detail beyond the states defined in the Connection interface. The states defined by this interface are related to the states defined in the core package in certain, specific ways, as defined below. Applications may obtain the CallControlConnection state via the getCallControlState() method defined on this interface. This method returns one of the integer state constants defined in this interface.

Below is a description of each CallControlConnection state in real-world terms. These real-world descriptions only serve to provide a more intuitive understanding of what is going on. Several methods in this specification state pre-conditions based upon the CallControlConnection state. Some of these states are identical to those defined in the core package.

CallControlConnection.IDLE	This state has the same definition as in the core package. It is the initial CallControlConnection state for all new Connections. Connections typically do not stay in this state for long, but quickly transition to another state.
CallControlConnection.OFFERED	This state indicates than an incoming call is being offered to the Address associated with the Connection. Typically, applications must either accept or reject this offered call before the called party is alerted to the incoming telephone call.
CallControlConnection.QUEUED	This state indicates that a Connection is queued at the particular Address associated with the Connection. For example, some telephony platforms permit the "queueing" of incoming telephone call to an Address when the Address is busy.
CallControlConnection.NETWORK_REACHED	This state indicates that an outgoing telephone call has reached the network. Applications may not receive further events about this leg of the telephone call, depending upon the ability of the telephone network to provide additional progress information. Applications must decide whether to treat this as a connected telephone call.
CallControlConnection.NETWORK_ALERTING	This state indicates that an outgoing telephone call is alerting at the destination end, which was previously only known to have reached the network. Typically, Connections transition into this state from the CallControlConnection.NETWORK_REACHED state. This state results from additional progress information being sent from the telephone network.
CallControlConnection.ALERTING	This state has the same definition as in the core package. It implies that the Address is being notified of an incoming call.
CallControlConnection.INITIATED	This state indicates the originating end of a telephone call has begun the process of placing a telephone call, but the dialing of the destination telephone address has not yet begun. Typically, a telephone associated with the Address has gone "off-hook".
CallControlConnection.DIALING	This state indicates the originating end of a telephone call has begun the process of dialing a destination telephone address, but has not yet completed dialing.
CallControlConnection.ESTABLISHED	This state is similar to that of Connection.CONNECTED. It indicates that the endpoint has reached its final, active state in the telephone call.
CallControlConnection.DISCONNECTED	This state has the same definition as in the core package. It implies the Connection object is no longer part of the telephone call.
CallControlConnection.FAILED	This state has the same definition as in the core package. It indicates that a particular leg of a telephone call has failed for some reason, perhaps because the party was busy.
CallControlConnection.UNKNOWN	This state has the same definition as in the core package. It indicates the implementation is unable to determine the current call control package state of the Connection object. Typically, methods are invalid on this object when it is in this state.

State Transitions

Similar to the Connection state transition diagram, the CallControlConnection state must transition according to rules illustrated in the finite state diagram below. An implementation must guarantee that CallControlConnection state must abide by this transition diagram.

Note there is a general left-to-right progression of the state transitions. The asterisk next to a state transition, as in the core package, implies a transition to/from another state, except where noted.

Core vs. CallControl Package States

There is a strong relationship between the CallControlConnection states and the Connection states. If an implementation supports the call control package, it must ensure this relationship is properly maintained.

Since the states defined in the CallControlConnection interface provide more detail to the states defined in the Connection interface, each state in the Connection interface corresponds to a state defined in the CallControlConnection interface. Conversely, each CallControlConnection state corresponds to exactly one Connection state. This arrangement permits applications to view either the core state or the call control state and still see a consistent view.

The following table outlines the relationship between the core package Connection states and the call control package Connection states.

If the call control package state is...	then the core package state must be...
CallControlConnection.IDLE	Connection.IDLE
CallControlConnection.QUEUED	Connection.INPROGRESS
CallControlConnection.OFFERED	Connection.INPROGRESS
CallControlConnection.ALERTING	Connection.ALERTING
CallControlConnection.INITIATED	Connection.CONNECTED
CallControlConnection.DIALING	Connection.CONNECTED
CallControlConnection.NETWORK_REACHED	Connection.CONNECTED
CallControlConnection.NETWORK_ALERTING	Connection.CONNECTED
CallControlConnection.ESTABLISHED	Connection.CONNECTED
CallControlConnection.DISCONNECTED	Connection.DISCONNECTED
CallControlConnection.FAILED	Connection.FAILED
CallControlConnection.UNKNOWN	Connection.UNKNOWN

Observers and Events

All events pertaining to the CallControlConnection interface are reported via the CallObserver.callChangedEvent() method. The application observer object must also implement the CallControlCallObserver interface to express interest in the call control package events.

Observers which are registered on a Call receive events when the CallControlConnection state changes. Note that when the CallControlConnection state changes, it sometimes results in the Connection state changing (according to the table above). In these instances, both the proper call control and core package events are delivered to the observer.

The CallControlConnection state events defined in this package are: CallCtlConnOfferedEv, CallCtlConnQueuedEv, CallCtlConnAlertingEv, CallCtlConnInitiatedEv, CallCtlConnDialingEv, CallCtlConnNetworkReachedEv, CallCtlConnNetworkAlertingEv, CallCtlConnFailedEv, CallCtlConnEstablishedEv, CallCtlConnUnknownEv, and CallCtlConnDisconnectedEv.

See Also:

Connection, CallObserver, CallControlCallObserver, CallCtlCallEv, CallCtlConnEv, CallCtlConnAlertingEv, CallCtlConnDialingEv, CallCtlConnDisconnectedEv, CallCtlConnEstablishedEv, CallCtlConnFailedEv, CallCtlConnInitiatedEv, CallCtlConnNetworkAlertingEv, CallCtlConnNetworkReachedEv, CallCtlConnOfferedEv, CallCtlConnQueuedEv, CallCtlConnUnknownEv

Field Summary

static int	ALERTING The CallControlConnection.ALERTING state has the same definition as in the core package.
static int	DIALING The CallControlConnection.DIALING state indicates the originating end of a telephone call has begun the process of dialing a destination telephone address, but has not yet completed.
static int	DISCONNECTED The CallControlConnection.DISCONNECTED state has the same definition as in the core package.
static int	ESTABLISHED The CallControlConnection.ESTABLISHED state is similar to that of Connection.CONNECTED.
static int	FAILED The CallControlConnection.FAILED state has the same definition as in the core package.
static int	IDLE The CallControlConnection.IDLE state has the same definition as in the core package.
static int	INITIATED The CallControlConnection.INITIATED state indicates the originating end of a telephone call has begun the process of placing a telephone call, but the dialing of the destination telephone address has not yet begun.
static int	NETWORK_ALERTING The CallControlConnection.NETWORK_ALERTING state indicates that an outgoing telephone call is alerting at the destination end, which was previously only known to have reached the network.
static int	NETWORK_REACHED The CallControlConnection.NETWORK_REACHED state indicates that an outgoing telephone call has reached the network.
static int	OFFERED The CallControlConnection.OFFERED state indicates than an incoming call is being offered to the Address associated with the Connection.
static int	OFFERING Deprecated. Since JTAPI v1.2.
static int	QUEUED The CallControlConnection.QUEUED state indicates that a Connection is queued at the particular Address associated with the Connection.
static int	UNKNOWN The CallControlConnection.UNKNOWN state has the same definition as in the core package.

Fields inherited from interface javax.telephony.Connection

CONNECTED, INPROGRESS

Method Summary

void	accept() Accepts a telephone call incoming to an Address.
void	addToAddress(java.lang.String additionalAddress) Appends additional address information onto an existing Connection.
int	getCallControlState() Returns the current call control state of the Connection.
Connection	park(java.lang.String destinationAddress) Parks a Connection at a destination telephone address.
Connection	redirect(java.lang.String destinationAddress) Redirects an incoming telephone call at an Address to another telephone address.
void	reject() Rejects a telephone call incoming to an Address.

Methods inherited from interface javax.telephony.Connection

disconnect, getAddress, getCall, getCapabilities, getConnectionCapabilities, getState, getTerminalConnections

Field Detail

IDLE

public static final int IDLE

The CallControlConnection.IDLE state has the same definition as in the core package. It is the initial CallControlConnection state for all new Connections. Connections typically do not stay in this state for long, quickly transitioning to another state.

OFFERED

public static final int OFFERED

The CallControlConnection.OFFERED state indicates than an incoming call is being offered to the Address associated with the Connection. Typically, applications must either accept or reject this offered call before the called party is alerted to the incoming telephone call.

Since:

JTAPI v1.2

QUEUED

public static final int QUEUED

The CallControlConnection.QUEUED state indicates that a Connection is queued at the particular Address associated with the Connection. A queued call is not active on a call. For example, some telephony platforms permit the "queueing" of incoming telephone call to an Address when the Address is busy.

ALERTING

public static final int ALERTING

The CallControlConnection.ALERTING state has the same definition as in the core package. It means that the Address is being notified of an incoming call.

INITIATED

public static final int INITIATED

The CallControlConnection.INITIATED state indicates the originating end of a telephone call has begun the process of placing a telephone call, but the dialing of the destination telephone address has not yet begun. Typically, a telephone associated with the Address has gone "off-hook".

DIALING

public static final int DIALING

The CallControlConnection.DIALING state indicates the originating end of a telephone call has begun the process of dialing a destination telephone address, but has not yet completed.

NETWORK_REACHED

public static final int NETWORK_REACHED

The CallControlConnection.NETWORK_REACHED state indicates that an outgoing telephone call has reached the network. Applications may not receive further events about this leg of the telephone call, depending upon the ability of the telephone network to provide additional progress information. Applications must decide whether to treat this as a connected telephone call.

NETWORK_ALERTING

public static final int NETWORK_ALERTING

The CallControlConnection.NETWORK_ALERTING state indicates that an outgoing telephone call is alerting at the destination end, which was previously only known to have reached the network. Typically, Connections transition into this state from the CallControlConnection.NETWORK_REACHED state. This state results from additional progress information being sent from a telephone network that was capable of transmitting that information.

ESTABLISHED

public static final int ESTABLISHED

The CallControlConnection.ESTABLISHED state is similar to that of Connection.CONNECTED. It indicates that the endpoint has reached its final, active state in the telephone call.

DISCONNECTED

public static final int DISCONNECTED

The CallControlConnection.DISCONNECTED state has the same definition as in the core package. It indicates that the Connection object is no longer part of the telephone call.

FAILED

public static final int FAILED

The CallControlConnection.FAILED state has the same definition as in the core package. It indicates that a Connection is no longer able to participate in a call. It is a final state in the life of a Connection. It indicates that a particular leg of a telephone call has failed for some reason, perhaps because the party was busy.

UNKNOWN

public static final int UNKNOWN

The CallControlConnection.UNKNOWN state has the same definition as in the core package. It indicates that the state of the Connection is not known to its Provider. Typically, methods are invalid on this object when it is in this state.

OFFERING

public static final int OFFERING

Deprecated. Since JTAPI v1.2.

The CallControlConnection.OFFERING state has been deprecated in JTAPI v1.2. It has the same meaning as the new CallControlConnection.OFFERED state. This constant has been replaced to be more tense-consistent with the event name.

Method Detail

getCallControlState

public int getCallControlState()

Returns the current call control state of the Connection. The return value will be one of integer state constants defined above.

Returns:

The current call control state of the Connection.

accept

public void accept()
            throws InvalidStateException,
                   MethodNotSupportedException,
                   PrivilegeViolationException,
                   ResourceUnavailableException

Accepts a telephone call incoming to an Address. Telephone calls into an Address may first be offered to that address for acceptance before the standard notion of "alerting" takes place. This method is valid on a Connection in the CallControlConnection.OFFERED state. If successful, this method moves the Connection into the CallControlConnection.ALERTING state. This method waits until the telephone call has been accepted or an error occurs and an exception is thrown.

Pre-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.OFFERED

Post-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.ALERTING
3. CallCtlConnAlertingEv/ConnAlertingEv is delivered for this Connection

Throws:

InvalidStateException - Either the Provider is not "in service" or the Connection is not "offered".

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

ConnAlertingEv, CallCtlConnAlertingEv

reject

public void reject()
            throws InvalidStateException,
                   MethodNotSupportedException,
                   PrivilegeViolationException,
                   ResourceUnavailableException

Rejects a telephone call incoming to an Address. Telephone calls into an Address may first be offered to that address for acceptance before the standard notion of "alerting" takes place. This method is valid on a Connection in the CallControlConnection.OFFERED state. If successful, this method moves the Connection into the CallControlConnection.DISCONNECTED state. This method waits until the telephone call has been rejected or an error occurs and an exception is thrown.

Pre-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.OFFERED

Post-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.DISCONNECTED
3. CallCtlConnDisconnectedEv/ConnDisconnectedEv is delivered for this Connection

Throws:

InvalidStateException - Either the Provider is not "in service" or the Connection is not "offered".

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

ConnDisconnectedEv, CallCtlConnDisconnectedEv

redirect

public Connection redirect(java.lang.String destinationAddress)
                    throws InvalidStateException,
                           InvalidPartyException,
                           MethodNotSupportedException,
                           PrivilegeViolationException,
                           ResourceUnavailableException

Redirects an incoming telephone call at an Address to another telephone address. This method is very similar to the transfer feature, however, applications may invoke this method before first answering the telephone call. This method redirects the telephone call to another telephone address string provided as the argument to this method. This telephone address string must be valid and complete.

This Connection must either be in the CallControlConnection.OFFERED state or the CallControlConnection.ALERTING state. If successful, this method moves the Connection to the CallControlConnection.DISCONNECTED state. Additionally, any TerminalConnections associated with this Connection will move to the CallControlTerminalConnection.DROPPED state.

A new Connection is created and returned corresponding to the new destination leg of the telephone call. Note that this Connection may be null in the case the Call has been redirected outside of the Provider's domain and can no longer be tracked. The new Connection (if not null) must at least be in the CallControlConnection.IDLE state. The Connection may progress beyond this state before this method returns, which should be reflected by the proper events. This Connection behaves similarly to the destination Connection as described in Call.connect() and undergoes similar possible state change scenarios.

Pre-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.OFFERED or CallControlConnection.ALERTING
3. destinationAddress must be a valid and complete telephone address

Post-conditions:

1. Let newconnection be the new Connection created and returned
2. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
3. this.getCallControlState() == CallControlConnection.DISCONNECTED
4. newconnection element of (this.getCall()).getConnections()
5. newconnection.getCallControlState() at least CallControlConnection.IDLE
6. Let tc[] = this.getTerminalConnections() before this method is invoked
7. tc[i].getCallControlState() == CallControlTerminalConnection.DROPPED, for all i.
8. CallCtlConnDisconnected/ConnDisconnectedEv is delivered for this Connection
9. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for all tc[i]
10. ConnCreatedEv is delivered for newconnection

Parameters:

destinationAddress - The Connection is redirected to this telephone address

Returns:

The Connection associated with the new leg of the Call.

Throws:

InvalidStateException - Either the Provider is not "in service" or the Connection is not "offered" or "alerting".

InvalidPartyException - The destination address to which this call is redirected is not valid and/or complete.

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

ConnCreatedEv, ConnDisconnectedEv, TermConnDroppedEv, CallCtlConnDisconnectedEv, CallCtlTermConnDroppedEv

addToAddress

public void addToAddress(java.lang.String additionalAddress)
                  throws InvalidStateException,
                         MethodNotSupportedException,
                         PrivilegeViolationException,
                         ResourceUnavailableException

Appends additional address information onto an existing Connection. This method is used when part of a telephone address string has been dialed and additional addressing information is needed in order to complete the dialing process and place the telephone call. The additional addressing information is provided as the argument to this method.

This Connection must either be in the CallControlConnection.DIALING state or the CallControlConnection.INITIATED state. If successful, this moves the Connection into one of two states. If the information provided completes the addressing information, as determined by the telephony platform, the Connection moves into the CallControlConnection.ESTABLISHED state and the telephone call is placed. If additional addressing information is still required, the Connection moves into the CallControlConnection.DIALING state if not already there.

Pre-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.DIALING or CallControlConnection.INITIATED

Post-conditions Outcome 1: The addressing information is complete.

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.ESTABLISHED
3. CallCtlConnEstablishedEv is delivered for this Connection

Post-conditions Outcome 2: The addressing information is not complete.

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.DIALING
3. CallCtlConnDialingEv is delivered for this Connection

Parameters:

additionalAddress - The additional addressing information.

Throws:

InvalidStateException - Either the Provider is not "in service" or the Connection is not "initiated" or "dialing".

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

CallCtlConnDialingEv, CallCtlConnEstablishedEv

park

public Connection park(java.lang.String destinationAddress)
                throws InvalidStateException,
                       MethodNotSupportedException,
                       PrivilegeViolationException,
                       InvalidPartyException,
                       ResourceUnavailableException

Parks a Connection at a destination telephone address. This method is similar to the transfer feature, except the Connection at the new destination Address is in a special queued state. Parking a Connection at a destination Address drops the Connection from the Call and creates and returns a new Connection at the specified destination address in the CallControlConnection.QUEUED state.

The new destination telephone address string is given as an argument to this method and must be a valid and complete telephone address. The CallControlTerminal.pickup() method permits applications to "unpark" the new Connection.

The Connection must be in the CallControlConnection.ESTABLISHED state. If this method is successful, this Connection moves to the CallControlConnection.DISCONNECTED state. All of its associated TerminalConnections move to the CallControlTerminalConnection.DROPPED state.

Pre-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getCallControlState() == CallControlConnection.ESTABLISHED
3. destinationAddress must be a valid and complete telephone address.

Post-conditions:

1. Let newconnection be the new Connection created and returned
2. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
3. newconnection element of (this.getCall()).getConnections()
4. newconnection.getCallControlState() == CallControlConnection.QUEUED
5. this.getCallControlState() == CallControlConnection.DISCONNECTED
6. Let tc[] = this.getTerminalConnections() before this method is invoked
7. tc[i].getCallControlState() == CallControlTerminalConnection.DROPPED, for all i
8. ConnCreatedEv is delivered for newconnection
9. CallCtlConnQueuedEv/ConnInProgressEv is delivered for newconnection
10. CallCtlConnDisconnected/ConnDisconnectedEv is delivered for this Connection
11. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for all tc[i]

Parameters:

destinationAddress - The telephone address string at which this connection is to be parked.

Returns:

The new Connection which is parked at the new destination Address.

Throws:

InvalidStateException - Either the Provider was not "in service" or the Connection was not "established".

MethodNotSupportedException - This method is not supported by the implementation.

InvalidPartyException - The party to which to party the Connection is invalid.

PrivilegeViolationException - The application does not have the proper authority to invoke this method.

ResourceUnavailableException - An internal resource necessary for the successful invocation of this method is not available.

See Also:

ConnCreatedEv, ConnInProgressEv, ConnDisconnectedEv, TermConnDroppedEv, CallCtlConnQueuedEv, CallCtlConnDisconnectedEv, CallCtlTermConnDroppedEv