javax.telephony.callcontrol
Interface CallControlTerminal

All Superinterfaces:

Terminal

public interface CallControlTerminal

extends Terminal

Introduction

The CallControlTerminal interface extends the core Terminal interface with features like the ability to pickup a call at a terminal and the ability to specify that this terminal should not be disturbed. Applications may query a Terminal object using the instanceof operator to see whether it supports this interface.

Do Not Disturb

The CallControlTerminal interface defines the do not disturb attribute. The do not disturb attribute indicates to the telephony platform that this Terminal does not want to be bothered with incoming telephone calls. That is, if this feature is activated, the underlying telephone platform will not ring this Terminal for incoming telephone calls. Applications use the CallControlTerminal.setDoNotDisturb() method to activate or deactivate this feature and the CallControlTerminal.getDoNotDisturb() method to return the current state of this attribute.

Note that the CallControlAddress interface also carries the do not disturb attribute. This attribute associated with each are maintained independently. Maintaining a separate do not distrub attribute at terminal and address allows for control over the do not disturb feature at either the terminal or address level.

Picking Up Telephone Calls

The pickup feature permits applications to answer telephone calls which are not ringing at a particular Terminal. This feature is often used when a call is "queued" at an Address or a telephone is ringing at a Terminal across a room. Both the pickup() and the pickupFromGroup() methods defined on this interface provide this pickup feature to the application.

The CallControlTerminal.pickup() method has three versions and permits applications to answer a Call at a designated Address or Terminal. The CallControlTerminal.pickupFromGroup() method permits applications to answer a Call at some other Terminal in the same "pickup group".

Observers and Events

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

The following are those events associated with this interface:

CallCtlTermDoNotDisturbEv

Indicates the do-not-disturb attribute of this Terminal has changed.

See Also:

CallControlAddress, CallControlTerminalObserver, CallCtlTermDoNotDisturbEv

Method Summary

boolean	getDoNotDisturb() Returns true if the do-not-disturb feature is activated, false otherwise.
TerminalConnection	pickup(Address pickupAddress, Address terminalAddress) This method "picks up" a Call at this Terminal.
TerminalConnection	pickup(Connection pickupConnection, Address terminalAddress) This method "picks up" a Call at this Terminal.
TerminalConnection	pickup(TerminalConnection pickTermConn, Address terminalAddress) This method "picks up" a Call at this Terminal.
TerminalConnection	pickupFromGroup(Address terminalAddress) This method "picks up" a Call at this Terminal.
TerminalConnection	pickupFromGroup(java.lang.String pickupGroup, Address terminalAddress) This method "picks up" a Call at this Terminal.
void	setDoNotDisturb(boolean enable) Specifies whether the do-not-disturb feature should be activated or deactivated for this Terminal.

Methods inherited from interface javax.telephony.Terminal

addCallListener, addCallObserver, addObserver, addTerminalListener, getAddresses, getCallListeners, getCallObservers, getCapabilities, getName, getObservers, getProvider, getTerminalCapabilities, getTerminalConnections, getTerminalListeners, removeCallListener, removeCallObserver, removeObserver, removeTerminalListener

Method Detail

getDoNotDisturb

public boolean getDoNotDisturb()
                        throws MethodNotSupportedException

Returns true if the do-not-disturb feature is activated, false otherwise.

Returns:

True if do-not-disturb is activated, false if it is deactivated

Throws:

MethodNotSupportedException - This method is not supported by the given implementation.

setDoNotDisturb

public void setDoNotDisturb(boolean enable)
                     throws MethodNotSupportedException,
                            InvalidStateException

Specifies whether the do-not-disturb feature should be activated or deactivated for this Terminal. This feature only affects whether or not calls will be accepted at this Terminal. The setting of this attribute does not affect the do-not-disturb attribute associated with all Addresses associated with this Terminal. If 'enable' is true, do-not-disturb is activated if not already so. If 'enable' is false, do-not-disturb is deactivated if not already so.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getDoNotDisturb() == enable
3. CallCtlTermDoNotDisturbEv is delivered for this Terminal

Parameters:

enable - True to activated do-not-disturb, false to deactivate.

Throws:

MethodNotSupportedException - This method is not supported by the given implementation.

InvalidStateException - The Provider is not "in service".

See Also:

CallCtlTermDoNotDisturbEv

pickup

public TerminalConnection pickup(Connection pickupConnection,
                                 Address terminalAddress)
                          throws InvalidArgumentException,
                                 InvalidStateException,
                                 MethodNotSupportedException,
                                 PrivilegeViolationException,
                                 ResourceUnavailableException

This method "picks up" a Call at this Terminal. Picking up a Call is analogous to answering a Call at this Terminal (i.e. TerminalConnection.answer()), except the Call typically is not ringing at this Terminal. For example, this method is used to answer a "queued" Call or a Call which is ringing at another Terminal across the room.

This method takes a Connection and an Address as arguments. The Connection argument represents the destination end of the telephone call to be picked up. This Connection must be in either the CallControlConnection.QUEUED state or the CallControlConnection.ALERTING state. The Address argument chooses the Address associated with this Terminal on which to pick up the Call. A new TerminalConnection is created and returned which is in the CallControlTerminalConnection.TALKING state and associated with this Terminal.

The Address and Connection Arguments

The relationship between the Address and Connection arguments affects the resulting behavior of this method. There are two different situations: if the given Connection is associated with the given Address, and if the given Connection is not associated with the given Address (i.e. via the Connection.getAddress() method).

If the given Connection is associated with the given Address, this implies that the Connection was in the CallControlConnection.QUEUED state, or the Terminal did not ring for some reason even though the Connection is in the CallControlConnection.ALERTING state. In this case, the Connection moves to the CallControlConnection.ESTABLISHED state and the new TerminalConnection created is associated with the Connection.

If the given Connection is not associated with the given Address, this implies that the call is alerting at an entirely different endpoint from this Terminal. This scenario permits applications to pick up a telephone call which is ringing across the room. In this case, the Connection moves to the CallControlConnection.DISCONNECTED state. A new Connection is created and associated with the Address argument. It is in the CallControlConnection.ESTABLISHED state. The new TerminalConnection created is associated with this new Connection.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. (pickupConnection.getCall()).getState() == Call.ACTIVE
3. pickupConnection.getCallControlState() == CallControlConnection.QUEUED or CallControlConnection.ALERTING
4. terminaladdress element of this.getAddresses()

Post-conditions Outcome 1: If pickupConnection is associated with terminaladdress (i.e. pickupConnection.getAddress() == terminaladdress)

1. Let tc be the new TerminalConnection created and returned
2. tc.getCallControlState() == CallControlTerminalConnection.TALKING
3. pickupConnection.getCallControlState() == CallControlConnection.ESTABLISHED
4. tc.getConnection() == pickupConnection
5. TermConnCreatedEv is delivered for tc
6. CallCtlTermConnTalkingEv/TermConnActiveEv is delivered for tc
7. CallCtlConnEstablishedEv/ConnConnectedEv is delivered for pickupConnection

Post-conditions Outcome 2: If pickupConnection is not associated with terminaladdress (i.e. pickupConnection.getAddress() != terminaladdress)

1. Let tc be the new TerminalConnection created and returned
2. Let connection be the new Connection created
3. Let call = pickupConnection.getCall()
4. tc.getCallControlState() == CallControlTerminalConnection.TALKING
5. connection.getCallControlState() == CallControlConnection.ESTABLISHED
6. connection.getAddress() == terminaladdress
7. connection.getCall() == call
8. tc.getConnection() == connection
9. pickupConnection.getCallControlState() == CallControlConnection.DISCONNECTED
10. TermConnCreatedEv is delivered for tc
11. CallCtlTermConnTalkingEv/TermConnActiveEv is delivered for tc
12. ConnCreatedEv is delivered for connection
13. CallCtlConnEstablishedEv/ConnConnectedEv is delivered for connection
14. CallCtlConnDisconnectedEv/ConnDisconnectedEv is delivered for pickupConnection

Parameters:

pickupConnection - The Connection to be picked up

terminalAddress - The Address associated with the Terminal

Returns:

The new TerminalConnection associated with the Terminal

Throws:

InvalidArgumentException - Either the Connection or Address given as arguments is not valid.

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

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, TermConnCreatedEv, ConnConnectedEv, ConnDisconnectedEv, TermConnActiveEv, CallCtlTermConnTalkingEv, CallCtlConnEstablishedEv, CallCtlConnDisconnectedEv

pickup

public TerminalConnection pickup(TerminalConnection pickTermConn,
                                 Address terminalAddress)
                          throws InvalidArgumentException,
                                 InvalidStateException,
                                 MethodNotSupportedException,
                                 PrivilegeViolationException,
                                 ResourceUnavailableException

This method "picks up" a Call at this Terminal. Picking up a Call is analogous to answering a Call at this Terminal (i.e. TerminalConnection.answer()), except the Call typically is not ringing at this Terminal. For example, this method is used to answer a "queued" Call or a Call which is ringing at another Terminal across the room.

This method is similar to the CallControlTerminal.pickup(Connection, Address) method except an explicit TerminalConnection is given. Since an explicit TerminalConnection is given, this implies its Connection must be "alerting" since "queued" Connections may not have any associated TerminalConnections.

Parameters:

pickTermConn - The TerminalConnection to be picked up

terminalAddress - The Address associated with the Terminal

Returns:

The new TerminalConnection associated with the Terminal

Throws:

InvalidArgumentException - Either the Connection or Address given as arguments is not valid.

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

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.

pickup

public TerminalConnection pickup(Address pickupAddress,
                                 Address terminalAddress)
                          throws InvalidArgumentException,
                                 InvalidStateException,
                                 MethodNotSupportedException,
                                 PrivilegeViolationException,
                                 ResourceUnavailableException

This method "picks up" a Call at this Terminal. Picking up a Call is analogous to answering a Call at this Terminal (i.e. TerminalConnection.answer()), except the Call typically is not ringing at this Terminal. For example, this method is used to answer a "queued" Call or a Call which is ringing at another Terminal across the room.

This method is similar to the CallControlTerminal.pickup(Connection, Address) method except an Address is given instead of an explicit Connection. This method permits the implementation to choose a suitable Connection associated with 'pickupAddress'.

Parameters:

pickupAddress - The Address which is to be picked up

terminalAddress - The Address associated with the Terminal

Returns:

The new TerminalConnection associated with the Terminal

Throws:

InvalidArgumentException - Either the Connection or Address given as arguments is not valid.

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

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.

pickupFromGroup

public TerminalConnection pickupFromGroup(java.lang.String pickupGroup,
                                          Address terminalAddress)
                                   throws InvalidArgumentException,
                                          InvalidStateException,
                                          MethodNotSupportedException,
                                          PrivilegeViolationException,
                                          ResourceUnavailableException

This method "picks up" a Call at this Terminal. Picking up a Call is analogous to answering a Call at this Terminal (i.e. TerminalConnection.answer()), except the Call typically is not ringing at this Terminal. For example, this method is used to answer a "queued" Call or a Call which is ringing at another Terminal across the room.

This method takes two arguments: a string "pickup group" code and an Address associated with this Terminal. The Address argument chooses the Address associated with this Terminal on which to pick up the Call. A new TerminalConnection is created and returned which is in the CallControlTerminalConnection.TALKING state and associated with this Terminal.

The Pickup Group Code

The application designates the Call to pick up via a string code rather than giving a specific Connection endpoint. An administrator of the underlying telephony platform can create groups of endpoints associated with a particular group code. From the code, the implementations decides which particular Connection is to be picked up. Once the Connection has been determined, this method behavior similarly to the CallControlTerminal.pickup(Connection, Address) method.

Parameters:

pickupGroup - The pickup group

terminalAddress - The Address associated with the Terminal

Returns:

The new TerminalConnection associated with the Terminal

Throws:

InvalidArgumentException - Either the Connection or Address given as arguments is not valid.

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

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.

pickupFromGroup

public TerminalConnection pickupFromGroup(Address terminalAddress)
                                   throws InvalidArgumentException,
                                          InvalidStateException,
                                          MethodNotSupportedException,
                                          PrivilegeViolationException,
                                          ResourceUnavailableException

This method "picks up" a Call at this Terminal. Picking up a Call is analogous to answering a Call at this Terminal (i.e. TerminalConnection.answer()), except the Call typically is not ringing at this Terminal. For example, this method is used to answer a "queued" Call or a Call which is ringing at another Terminal across the room.

This method takes a single argument: an Address associated with this Terminal. The Address argument chooses the Address associated with this Terminal on which to pick up the Call. A new TerminalConnection is created and returned which is in the CallControlTerminalConnection.TALKING state and associated with this Terminal.

The Pickup Group Code

This method does not take the pickup group code as an argument. Instead, the implementation chooses a suitable Call to be picked up. This Call should have a Connection in either the CallControlConnection.ALERTING state or the CallControlConnection.QUEUED state. The Address associated with this Connection should belong to the same pickup group as the Address given as the argument. Once the Connection has been determined, this method behavior similarly to the CallControlTerminal.pickup(Connection, Address) method.

Parameters:

terminalAddress - The Address associated with the Terminal

Returns:

The new TerminalConnection associated with the Terminal

Throws:

InvalidArgumentException - Either the Connection or Address given as arguments is not valid.

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

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.