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.
- IDLE ---> IDLE
- INPROGRESS ---> QUEUED, OFFERING
- ALERTING ---> ALERTING
- CONNECTED ---> INITIATED, DIALING, NETWORK_REACHED, NETWORK_ALERTING, ESTABLISHED
- DISCONNECTED ---> DISCONNECTED
- FAILED ---> FAILED
- UNKNOWN ---> UNKNOWN
-
ALERTING
- The ALERTING state variable.
-
DIALING
- The DIALING state variable.
-
DISCONNECTED
- The DISCONNECTED state variable.
-
ESTABLISHED
- The ESTABLISHED state variable.
-
FAILED
- The FAILED state variable.
-
IDLE
- The IDLE state variable.
-
INITIATED
- The INITIATED state variable.
-
NETWORK_ALERTING
- the NETWORK_ALERTING state variable.
-
NETWORK_REACHED
- The NETWORK_REACHED state variable.
-
OFFERING
- The OFFERING state variable.
-
QUEUED
- The QUEUED state variable.
-
UNKNOWN
- The UNKNOWN state variable.
-
accept()
- Accepts a telephone call.
-
addToAddress(String)
- Appends additional address information onto an existing Connection.
-
getCallControlState()
- Returns the current CallControl state of the Connection.
-
park(String)
- Parks an active Connection to another Address.
-
redirect(String)
- Redirects a telephone call to another telephone number.
-
reject()
- Rejects a telephone call.
IDLE
public final static int IDLE
- The IDLE state variable.
OFFERING
public final static int OFFERING
- The OFFERING state variable.
QUEUED
public final static int QUEUED
- The QUEUED state variable.
ALERTING
public final static int ALERTING
- The ALERTING state variable.
INITIATED
public final static int INITIATED
- The INITIATED state variable.
DIALING
public final static int DIALING
- The DIALING state variable.
NETWORK_REACHED
public final static int NETWORK_REACHED
- The NETWORK_REACHED state variable.
NETWORK_ALERTING
public final static int NETWORK_ALERTING
- the NETWORK_ALERTING state variable.
ESTABLISHED
public final static int ESTABLISHED
- The ESTABLISHED state variable.
DISCONNECTED
public final static int DISCONNECTED
- The DISCONNECTED state variable.
FAILED
public final static int FAILED
- The FAILED state variable.
UNKNOWN
public final static int UNKNOWN
- The UNKNOWN state variable.
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.
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:
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- this.getCallControlState() == OFFERING.
The post-conditions are given below:
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- 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.
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:
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- this.getCallControlState() == OFFERING.
The post-conditions are given below:
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- 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.
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:
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- this.getCallControlState() == OFFERING or ALERTING
- 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.
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- this.getCallControlState() == DISCONNECTED.
- newconnection.getCallControlState() == IDLE
- Let TerminalConnection tc[] = this.getTerminalConnections()
- 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.
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:
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- 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:
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- this.getCallControlState() == DIALING if the addressing information was
not enough as determined by the switch.
- 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.
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:
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- this.getCallControlState() == ESTABLISHED
- 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.
- ((this.getCall()).getProvider()).getState() == IN_SERVICE
- newconnection.getCallControlState() == QUEUED
- this.getCallControlState() == DISCONNECTED
- 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