javax.telephony.callcontrol
Interface CallControlCall

All Superinterfaces:

Call

All Known Subinterfaces:

ITsapiCall, LucentCall, LucentCallEx, LucentV5Call, LucentV7Call

public interface CallControlCall

extends Call

Introduction

The CallControlCall interface extends the core Call interface. This interface provides additional methods on a Call.

Additional Call Information

This interface supports methods which return additional information regarding the Call. Specifically, it returns the calling address, calling terminal, called address, and last redirected address information.

The calling address, as returned by the CallControlCall.getCallingAddress() method is the Address which originally placed the Call. The calling terminal, as returned by the CallControlCall.getCallingTerminal() method is the Terminal which originally placed the Call. The called Address, as returned by the CallControlCall.getCalledAddress() method is the Address to which the Call was originally placed. The last redirected address, as returned by the CallControlCall.getLastRedirectedAddress() method is the Address to which this Call was placed before the current destination Address. For example, if a Call was forwarded from one Address to another, then the first Address is the last redirected Address for this call.

Each of these methods returns null if their values are unknown at the present time. During the lifetime of a Call, an implementation may learn this additional information, and return different values for some or all of these methods as a result.

Conferencing Telephone Calls

The conferencing feature supported by this interface permits two telephone calls to be "merged". That is, the two Calls are merged into a single Call with the union of all of the participants of the two Calls being placed on the single Call.

Applications invoke the CallControlCall.conference() method to perform the conferencing feature. This method is given the "second" Call as an argument. All participants are moved from the second Call to the Call on which the method is invoked. The second Call moves into the Call.INVALID state as a result.

In order for the conferencing feature to happen, there must be a common participant to both Calls, as represented by a single Terminal and two TerminalConnections, one on each of the two Calls. These two TerminalConnections are known as the conference controllers. In the real-world, one of the two telephone calls must be on hold with respect to the controlling Terminal, and hence, the TerminalConnection on the second Call must be in the CallControlTerminalConnection.HELD state. The two conference controlling TerminalConnections are merged into one as a result of this method.

Applications may control which TerminalConnection acts as the conference controller via the CallControlCall.setConferenceController() method. The CallControlCall.getConferenceController() method returns the current conference controller, null if there is none. If no conference controller is set, the implementation chooses a suitable TerminalConnection when the conferencing feature is invoked.

Transferring Telephone Calls

The transfer feature supported by this interface permits one Call to be "moved" to another Call. That is, all of the participants from one Call are moved to another Call, except for the transferring participant which drops off from both Calls.

Applications invoke the CallControlCall.transfer() method to perform the transfer feature. There are two overloaded versions of this method. The first method takes a second Call as an argument. This method acts similarly to CallControlCall.conference(), except the two TerminalConnections on each Call with a common Terminal are removed from both Calls. The second version takes a string telephone address as an argument. This method removes the transfer controller participant while placing the telephone call to the designated address. This latter version of the transfer feature is often known as a single-step transfer.

In order for the transfer feature to happen, there must be a participant which acts as the transfer controller. The transfer controller is a TerminalConnection around which the transfer is performed. In the first version of the CallControlCall.transfer() method, the transfer controller must be present on each of the two Calls and share a common Terminal. In the second version, the transfer controller only applies to the Call object on which the method is invoked (since there is no second Call involved). In both cases, the transfer controller participant is no longer part of any Call once the transfer feature is complete.

Applications may control which TerminalConnection acts as the transfer controller via the CallControlCall.setTransferController() method. The CallControlCall.getTransferController() method returns the current transfer controller, null if there is none. If no transfer controller is set, the implementation chooses a suitable TerminalConnection when the conferencing feature is invoked.

Consultation Calls

Consultation Calls are special types of telephony calls created (often temporarily) for a specific purpose. Consultation calls are created if a user wants to "consult" with another party briefly while currently on a Call, or are created for the purpose of conferencing or transferring with a Call. Consequently, consultation calls are always associated with another existing Call.

Applications invoke the CallControlCall.consult() method to perform the consultation feature. The instance on which the method is invoke is always the "idle" Call on which the consultation takes place. There are two overloaded versions of this method. The first method takes a TerminalConnection and a string telephone address as arguments. This consultation telephone call is associated with the Call of the TerminalConnection argument. This method places a telephone call from the same originating endpoint specified by the TerminalConnection argument to the designated telephone address string. The second version of this method only takes a TerminalConnection as an argument, and permits applications to use the CallControlConnection.addToAddress() method to dial the destination address string.

Additional CallControlCall Methods

The CallControlCall.addParty() method adds a single party to a Call given some telephone address string. The CallControlCall.drop() disconnects all parties from the Call and moves it into the Call.INVALID state. The CallControlCall.offHook() method takes an originating Address and Terminal pair "off hook" and permits applications to dial destination address digits one-by-one.

Observers and Events

All events pertaining to the CallControlCall 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. Applications receive events pertaining to the CallControlConnection and CallControlTerminalConnection interfaces via this observer as well.

All CallControlCall-related events must extend the CallCtlCallEv interface. There are no specific events pertaining to the CallControlCall interface, however.

See Also:

Call, CallObserver, CallControlCallObserver, CallCtlCallEv

Field Summary

Fields inherited from interface javax.telephony.Call

ACTIVE, IDLE, INVALID

Method Summary

Connection	addParty(java.lang.String newParty) Adds an additional party to an existing Call.
void	conference(Call otherCall) Merges two Calls together, resulting in the union of the participants of both Calls being placed on a single Call.
Connection	consult(TerminalConnection tc) Creates a consultation between this Call and an active Call.
Connection[]	consult(TerminalConnection tc, java.lang.String dialedDigits) Creates a consultation between this Call and an active Call.
void	drop() Drops the entire Call.
Address	getCalledAddress() Returns the called Address associated with this Call.
Address	getCallingAddress() Returns the calling Address associated with this call.
Terminal	getCallingTerminal() Returns the calling Terminal associated with this Call.
TerminalConnection	getConferenceController() Returns the TerminalConnection which currently acts as the conference controller.
boolean	getConferenceEnable() Return true if conferencing is enabled, false otherwise.
Address	getLastRedirectedAddress() Returns the last redirected Address associated with this Call.
TerminalConnection	getTransferController() Returns the TerminalConnection which currently acts as the transfer controller.
boolean	getTransferEnable() Return true if transferring is enabled, false otherwise.
Connection	offHook(Address origaddress, Terminal origterminal) Takes the originating end of a Call off-hook.
void	setConferenceController(TerminalConnection tc) Sets the TerminalConnection which acts as the conference controller for the Call.
void	setConferenceEnable(boolean enable) Controls whether the Call is permitted or able to perform the conferencing feature.
void	setTransferController(TerminalConnection tc) Sets the TerminalConnection which acts as the transfer controller for the Call.
void	setTransferEnable(boolean enable) Controls whether the Call is permitted or able to perform the transferring feature.
void	transfer(Call otherCall) This method moves all participants from one Call to another, with the exception of a selected common participant.
Connection	transfer(java.lang.String address) This overloaded version of this method transfers all participants currently on this Call, with the exception of the transfer controller participant, to another telephone address.

Methods inherited from interface javax.telephony.Call

addCallListener, addObserver, connect, getCallCapabilities, getCallListeners, getCapabilities, getConnections, getObservers, getProvider, getState, removeCallListener, removeObserver

Method Detail

getCallingAddress

public Address getCallingAddress()

Returns the calling Address associated with this call. The calling Address is the Address which originally placed the telephone call. If the calling address is unknown or not yet known, this method returns null.

Returns:

The calling Address.

getCallingTerminal

public Terminal getCallingTerminal()

Returns the calling Terminal associated with this Call. The calling Terminal is the Terminal which originally placed the telephone call. If the calling Terminal is unknown or not yet known, this method returns null.

Returns:

The calling Terminal.

getCalledAddress

public Address getCalledAddress()

Returns the called Address associated with this Call. The called Address is the Address to which the call had been originally placed. If the called address is unknown or not yet known, this method returns null.

Returns:

The called Address.

getLastRedirectedAddress

public Address getLastRedirectedAddress()

Returns the last redirected Address associated with this Call. The last redirected Address is the Address at which the current Call was placed immediately before the current Address. This is common if a Call is forwarded to several Addresses before being answered. If the last redirected address is unknown or not yet known, this method returns null.

Returns:

The last redirected Address for this telephone Call.

addParty

public Connection addParty(java.lang.String newParty)
                    throws InvalidStateException,
                           InvalidPartyException,
                           MethodNotSupportedException,
                           PrivilegeViolationException,
                           ResourceUnavailableException

Adds an additional party to an existing Call. This is sometimes called a "single-step conference" because a party is conferenced into a Call directly. The telephone address string provided as the argument must be complete and valid.

States of the Existing Connections

The Call must have at least two Connections in the CallControlConnection.ESTABLISHED state. An additional restriction requires that at most one other Connection may be in either the CallControlConnection.QUEUED, CallControlConnection.OFFERED, or CallControlConnection.ALERTING state.

Some telephony platforms impose restrictions on the number of Connections in a particular state. For instance, it is common to restrict the number of "alerting" Connections to at most one. As a result, this method requires that at most one other Connections is in the "queued", "offering", or "alerting" state. (Note that the first two states correspond to the core Connection "in progress" state). Although some systems may not enforce this requirement, for consistency, JTAPI specifies implementations must uphold the conservative requirement.

The New Connection

This method creates and returns a new Connection representing the new party. This Connection must at least be in the CallControlConnection.IDLE state. Its state may have progressed beyond "idle" before this method returns, and should be reflected by an event. This new Connection will progress as any normal destination Connection on a Call. Typical scenarios for this Connection are described by the Call.connect() method.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE
3. Let c[] = call.getConnections() where c.length >= 2
4. c[i].getCallControlState() == CallControlConnection.ESTABLISHED for at least two i
5. c[j].getCallControlState() == CallControlConnection.QUEUED, CallControlConnection.OFFERED, or CallControlConnection.ALERTING for at most one c[j]

Post-conditions:

1. Let connection be the Connection created and returned
2. (this.getProvider()).getState() == Provider.IN_SERVICE
3. this.getState() == Call.ACTIVE
4. connection.getCallControlState() at least CallControlConnection.IDLE
5. ConnCreatedEv is delivered for connection

Parameters:

newParty - The telephone address of the party to be added.

Returns:

The new Connection associated with the added party.

Throws:

InvalidStateException - Either the Provider is not "in service", the Call is not "active" or the proper conditions on the Connections does not exist. as designated by the pre-conditions for this method.

InvalidPartyException - The destination address string 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

drop

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

Drops the entire Call. This method is equivalent to using the Connection.disconnect() method on each Connection which is part of the Call. Typically, each Connection on the Call will move into the CallControlConnection.DISCONNECTED state, each TerminalConnection will move into the CallControlTerminalConnection.DROPPED state, and the Call will move into the Call.INVALID state.

There are some Connections for which the application does not possess the proper authority to disconnect. In this case, this method performs no action on these Connections. These Connections may disconnect naturally as a result of disconnecting other Connections, however. This method returns when it can successfully disconnect as many methods as it can. The application is notified via events whether the entire Call was successfully dropped.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. Let c[] = this.getConnections() before this method is invoked
3. If c[i].getCallControlState == CallControlConnection.DISCONNECTED, for all i, then this.getState() == Call.INVALID
4. CallCtlConnDisconnectedEv/ConnDisconnectedEv is delivered for all disconnected Connections
5. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for all dropped TerminalConnections
6. CallInvalidEv is delivered if all Connections were disconnected

Throws:

InvalidStateException - Either the Provider was not "in service" or the Call was not "active".

MethodNotSupportedException - This method is not supported by the implementation.

PrivilegeViolationException - The application does not have the proper authority to invoke this method and it can drop none of the Connections.

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

See Also:

ConnDisconnectedEv, TermConnDroppedEv, CallInvalidEv, CallCtlConnDisconnectedEv, CallCtlTermConnDroppedEv

offHook

public Connection offHook(Address origaddress,
                          Terminal origterminal)
                   throws InvalidStateException,
                          MethodNotSupportedException,
                          PrivilegeViolationException,
                          ResourceUnavailableException

Takes the originating end of a Call off-hook. This method permits applications to simply take the originating terminal of a Call off-hook so that users may manually dial telephone number digits or applications may supply digits with the CallControlConnection.addToAddress() method. This is in contrast to the Call.connect() method which requires the complete destination address string.

This method takes the originating Address and Terminal as arguments. This Call must be in the Call.IDLE state. This method creates and returns a Connection to the originating Address in the CallControlConnection.INITIATED state. This method also creates a TerminalConnection in the CallControlTerminalConnection.TALKING state and associated with the new Connection and originating Terminal.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE
3. Let connection be the Connection created and returned
4. Let terminalconnection be the TerminalConnection created
5. connection.getCallControlState() == CallControlConnection.INITIATED
6. Let tc[] = c.getTerminalConnections() where tc.length == 1
7. tc[0] == terminalconnection
8. tc[0].getCallControlState() == CallControlTerminalConnection.TALKING
9. tc[0] element of origterminal.getTerminalConnections()
10. connection element of origaddress.getConnections()
11. connection element of this.getConnections()
12. ConnCreatedEv is delivered for connection
13. TermConnCreatedEv is delivered for terminalconnection
14. CallActiveEv is delivered for this Call
15. CallCtlConnInitiatedEv/ConnConnectedEv is delivered for connection
16. CallCtlTermConnTalkingEv/TermConnActiveEv is delivered for terminalconnection

Parameters:

origaddress - The originating Address object.

origterminal - The originating Terminal object.

Returns:

The Connection associated with the originating end of the telephone call.

Throws:

InvalidStateException - Either the Provider was not "in service" or the Call was not "idle".

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, CallActiveEv, CallCtlConnInitiatedEv, CallCtlTermConnTalkingEv

conference

public void conference(Call otherCall)
                throws InvalidStateException,
                       InvalidArgumentException,
                       MethodNotSupportedException,
                       PrivilegeViolationException,
                       ResourceUnavailableException

Merges two Calls together, resulting in the union of the participants of both Calls being placed on a single Call. This method takes a Call as an argument, referred to hereafter as the "second" Call. All of the participants from the second call are moved to the Call on which this method is invoked.

The Conference Controller

In order for the conferencing feature to happen, there must be a common participant to both Calls, as represented by a single Terminal and two TerminalConnections, one on each of the two Calls. These two TerminalConnections are known as the conference controllers. In the real-world, one of the two Calls must be on hold with respect to the controlling Terminal, and hence, the TerminalConnection on the second Call must be in the CallControlTerminalConnection.HELD state. The two conference controlling TerminalConnections are merged into one as a result of this method.

Applications may control which TerminalConnection acts as the conference controller via the CallControlCall.setConferenceController() method. The CallControlCall.getConferenceController() method returns the current conference controller, null if there is none. If no conference controller is set, the implementation chooses a suitable TerminalConnection when the conferencing feature is invoked.

The Telephone Call Argument

All of the participants from the second Call, passed as the argument to this method, are "moved" to the Call on which this method was invoked. That is, new Connections and TerminalConnections are created on this Call which are found on the second Call. Those Connections and TerminalConnections on the second Call are removed from the Call and the Call moves into the Call.INVALID state.

The conference controller TerminalConnections are merged into one on this Call. That is, the existing TerminalConnection controller on this Call is left unchanged, while the TerminalConnection on the second Call is removed from that Call.

Other Shared Participants

There may exist Address and Terminals which are part of both telephone call in addition to the designated conference controller. In these instances, those participants which are shared between both Calls are merged into one. That is, the Connections and TerminalConnections on this Call are left unchanged. The corresponding Connections and TerminalConnections on the second Call are removed from that Call.

Pre-conditions:

1. Let tc1 be the conference controller on this Call
2. Let connection1 = tc1.getConnection()
3. Let tc2 be the conference controller on otherCall
4. (this.getProvider()).getState() == Provider.IN_SERVICE
5. this.getState() == Call.ACTIVE
6. tc1.getTerminal() == tc2.getTerminal()
7. tc1.getCallControlState() == CallControlTerminalConnection.TALKING
8. tc2.getCallControlState() == CallControlTerminalConnection.HELD
9. this != otherCall

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE
3. otherCall.getState() == INVALID
4. Let c[] be the Connections to be merged from otherCall
5. Let tc[] be the TerminalConnections to be merged from otherCall
6. Let new(c) be the set of new Connections created on this Call
7. Let new(tc) be the set of new TerminalConnections created on this Call
8. new(c) element of this.getConnections()
9. new(c).getCallState() == c.getCallState()
10. new(tc) element of (this.getConnections()).getTerminalConnections()
11. new(tc).getCallState() == tc.getCallState()
12. c[i].getCallControlState() == CallControlConnection.DISCONNECTED for all i
13. tc[i].getCallControlState() == CallControlTerminalConnection.DROPPED for all i
14. CallInvalidEv is delivered for otherCall
15. CallCtlConnDisconnectedEv/ConnDisconnectedEv is delivered for all c[i]
16. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for all tc[i]
17. ConnCreatedEv is delivered for all new(c)
18. TermConnCreatedEv is delivered for all new(tc)
19. Appropriate events are delivered for all new(c) and new(tc)

Parameters:

otherCall - The second Call which to merge with this Call object.

Throws:

InvalidArgumentException - The Call object provided is not valid for the conference

InvalidStateException - Either the Provider is not "in service", the Call is not "active", or the conference controllers are not in the proper state.

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, ConnDisconnectedEv, TermConnDroppedEv, CallInvalidEv, CallCtlConnDisconnectedEv, CallCtlTermConnDroppedEv

transfer

public void transfer(Call otherCall)
              throws InvalidStateException,
                     InvalidArgumentException,
                     InvalidPartyException,
                     MethodNotSupportedException,
                     PrivilegeViolationException,
                     ResourceUnavailableException

This method moves all participants from one Call to another, with the exception of a selected common participant. This method takes a Call as an argument, referred to hereafter as the "second" Call. All of the participants, with the exception for the selected common participant, from the second call are moved to the Call on which this method is invoked.

The Transfer Controller

In order for the transfer feature to happen, there must be a participant which acts as the transfer controller. The transfer controller is a TerminalConnection around which the transfer is placed. This transfer controller must be present on each of the two Calls and share a common Terminal. The transfer controller participant is no longer part of any Call once this transfer feature is complete. The transfer controllers on each of the two Calls must be in either of the CallControlTerminalConnection.TALKING or CallControlTerminalConnection.HELD state.

Applications may control which TerminalConnection acts as the transfer controller via the CallControlCall.setTransferController() method. The CallControlCall.getTransferController() method returns the current transfer controller, null if there is none. If no transfer controller is set, the implementation chooses a suitable TerminalConnection when the transfer feature is invoked.

The Telephone Call Argument

All of the participants from the second Call, passed as the argument to this method, are "moved" to the Call on which this method is invoked, with the exception of the transfer controller. That is, new Connections and TerminalConnections are created on this Call which are found on the second Call. Those Connections and TerminalConnections on the second Call are removed from the Call and the Call moves into the Call.INVALID state.

The transfer controller TerminalConnections are dropped from both Calls. They move into the CallControlTerminalConnection.DROPPED state.

Other Shared Participants

There may exist Address and Terminals which are part of both Calls in addition to the designated transfer controller. In these instances, those participants which are shared between both Calls are merged into one. That is, the Connections and TerminalConnections on this Call are left unchanged. The corresponding Connections and TerminalConnections on the second Call are removed from that Call.

Pre-conditions:

1. Let tc1 be the transfer controller on this Call
2. Let tc2 be the transfer controller on otherCall
3. this != otherCall
4. (this.getProvider()).getState() == Provider.IN_SERVICE
5. this.getState() == Call.ACTIVE
6. otherCall.getState() == Call.ACTIVE
7. tc1.getCallControlState() == CallControlTerminalConnection.TALKING or CallControlTerminalConnection.HELD
8. tc2.getCallControlState() == CallControlTerminalConnection.TALKING or CallControlTerminalConnection.HELD

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE
3. otherCall.getState() == Call.INVALID
4. tc1.getCallControlState() == CallControlTerminalConnection.DROPPED
5. tc2.getCallControlState() == CallControlTerminalConnection.DROPPED
6. Let c[] be the Connections to be transferred from otherCall
7. Let tc[] be the TerminalConnections to be transferred from otherCall
8. Let new(c) be the set of new Connections created on this Call
9. Let new(tc) be the set of new TerminalConnections created on this Call
10. new(c) element of this.getConnections()
11. new(c).getCallState() == c.getCallState()
12. new(tc) element of (this.getConnections()).getTerminalConnections()
13. new(tc).getCallState() == tc.getCallState()
14. c[i].getCallControlState() == CallControlConnection.DISCONNECTED for all i
15. tc[i].getCallControlState() == CallControlTerminalConnection.DROPPED for all i
16. CallInvalidEv is delivered for otherCall
17. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for tc1, tc2
18. CallCtlConnDisconnectedEv/ConnDisconnectedEv is delivered for all c[i]
19. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for all tc[i]
20. ConnCreatedEv is delivered for all new(c)
21. TermConnCreatedEv is delivered for all new(tc)
22. Appropriate events are delivered for all new(c) and new(tc)

Parameters:

otherCall - The other Call which to transfer to this Call.

Throws:

InvalidArgumentException - The TerminalConnection controlling the transfer is not valid or does not exist or the other Call is not valid.

InvalidStateException - Either the Provider is not "in service", the Call are not "active", or the transfer controllers are not "talking" or "held".

InvalidPartyException - The other Call given as the argument is not a valid Call to conference with.

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, ConnDisconnectedEv, TermConnDroppedEv, CallInvalidEv, CallCtlConnDisconnectedEv, CallCtlTermConnDroppedEv

transfer

public Connection transfer(java.lang.String address)
                    throws InvalidArgumentException,
                           InvalidStateException,
                           InvalidPartyException,
                           MethodNotSupportedException,
                           PrivilegeViolationException,
                           ResourceUnavailableException

This overloaded version of this method transfers all participants currently on this Call, with the exception of the transfer controller participant, to another telephone address. This is often called a "single-step transfer" because the transfer feature places another telephone call and performs the transfer at one time. The telephone address string given as the argument to this method must be valid and complete.

The Transfer Controller

The transfer controller for this version of this method represents the participant on this Call around which the transfer is taking place and who drops off the Call once the transfer feature has completed. The transfer controller is a TerminalConnection which must be in the CallControlTerminalConnection.TALKING state.

Applications may control which TerminalConnection acts as the transfer controller via the CallControlCall.setTransferController() method. The CallControlCall.getTransferController() method returns the current transfer controller, null if there is none. If no transfer controller is set, the implementation chooses a suitable TerminalConnection when the transfer feature is invoked.

When the transfer feature is invoked, the transfer controller moves into the CallControlTerminalConnection.DROPPED state. If it is the only TerminalConnection associated with its Connection, then its Connection moves into the CallControlConnection.DISCONNECTED state as well.

The New Connection

This method creates and returns a new Connection representing the party to which the Call was transferred. Note that this Connections may be null in the case the Call has been transferred outside of the Provider's domain and can no longer be tracked. This Connection must at least be in the CallControlConnection.IDLE state. Its state may have progressed beyond "idle" before this method returns, and should be reflected by an event. This new Connection will progress as any normal destination Connection on a telephone call. Typical scenarios for this Connection are described by the Call.connect() method.

Pre-conditions:

1. Let tc be the transfer controller on this Call
2. (this.getProvider()).getState() == Provider.IN_SERVICE
3. this.getState() == Call.ACTIVE
4. tc.getCallControlState() == CallControlTerminalConnection.TALKING

Post-conditions:

1. Let newconnection be the Connection created and returned
2. Let connection == tc.getConnection()
3. (this.getProvider()).getState() == Provider.IN_SERVICE
4. this.getState() == Call.ACTIVE
5. tc.getCallControlState() == CallControlTerminalConnection.DROPPED
6. If connection.getTerminalConnections().length == 1, then connection.getCallControlState() == CallControlConnection.DISCONNECTED
7. newconnection is an element of this.getConnections(), if not null.
8. newconnection.getCallControlState() at least CallControlConnection.IDLE, if not null.
9. ConnCreatedEv is delivered for newconnection
10. CallCtlTermConnDroppedEv/TermConnDroppedEv is delivered for tc
11. CallCtlConnDisconnectedEv/ConnDisconnectedEv is delivered for connection if no other TerminalConnections

Parameters:

address - The destination telephone address string to where the Call is being transferred.

Returns:

The new Connection associated with the destination or null.

Throws:

InvalidArgumentException - The TerminalConnection provided as controlling the transfer is not valid or part of this Call.

InvalidStateException - Either the Provider is not "in service", the Call is not "active", or the transfer controller is not "talking".

InvalidPartyException - The destination address 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

setConferenceController

public void setConferenceController(TerminalConnection tc)
                             throws InvalidArgumentException,
                                    InvalidStateException,
                                    MethodNotSupportedException,
                                    ResourceUnavailableException

Sets the TerminalConnection which acts as the conference controller for the Call. The conference controller represents the participant in the Call around which a conference takes place.

Typically, when two Calls are conferenced together, a single participant is part of both Calls. This participant is represented by a TerminalConnection on each Call, each of which shares the same Terminal.

If the designated TerminalConnection is not part of this Call, an exception is thrown. If the TerminalConnection leaves the Call in the future, the implementation resets the conference controller to null.

Pre-conditions:

1. Let connections[] = this.getConnections()
2. (this.getProvider()).getState() == Provider.IN_SERVICE
3. this.getState() == Call.ACTIVE
4. tc element of connections[i].getTerminalConnections() for all i
5. tc.getCallControlState() != CallControlTerminalConnection.DROPPED

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE
3. Let connections[] = this.getConnections()
4. tc element of connections[i].getTerminalConnections() for all i
5. tc.getCallControlState() != CallControlTerminalConnection.DROPPED
6. tc == this.getConferenceController()

Parameters:

tc - The TerminalConnection to use as the conference controller

Throws:

InvalidArgumentException - The TerminalConnection provided is not associated with this Call.

InvalidStateException - Either the Provider is not "in service" or the Call is not "active".

MethodNotSupportedException - This method is not supported by the implementation.

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

getConferenceController

public TerminalConnection getConferenceController()

Returns the TerminalConnection which currently acts as the conference controller. The conference controller represents the participant in the telephone around which a conference takes place.

When a Call is initially created, the conference controller is set to null. This method returns non-null only if the application has previously set the conference controller. If the current conference controller leaves the Call, the conference controller is reset to null.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() != Call.INVALID

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() != Call.INVALID
3. Let tc = this.getConferenceController()
4. Let connections[] = this.getConnections()
5. tc element of connections[i].getTerminalConnections() for all i, if tc is not null
6. tc.getCallControlState() != CallControlTerminalConnection.DROPPED, if tc is not null

Returns:

The current TerminalConnection acting as the conference controller, null if one is not set.

setTransferController

public void setTransferController(TerminalConnection tc)
                           throws InvalidArgumentException,
                                  InvalidStateException,
                                  MethodNotSupportedException,
                                  ResourceUnavailableException

Sets the TerminalConnection which acts as the transfer controller for the Call. The transfer controller represents the participant in the Call around which a transfer takes place.

If the designated TerminalConnection is not part of this Call, an exception is thrown. If the TerminalConnection leaves the Call in the future, the implementation resets the transfer controller to null.

Pre-conditions:

1. Let connections[] = this.getConnections()
2. (this.getProvider()).getState() == Provider.IN_SERVICE
3. this.getState() == Call.ACTIVE
4. tc element of connections[i].getTerminalConnections() for all i
5. tc.getCallControlState() != CallControlTerminalConnection.DROPPED

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE
3. Let connections[] = this.getConnections()
4. tc element of connections[i].getTerminalConnections() for all i
5. tc.getCallControlState() != CallControlTerminalConnection.DROPPED
6. tc == this.getTransferController()

Parameters:

tc - The TerminalConnection to use as the transfer controller

Throws:

InvalidArgumentException - The TerminalConnection provided is not associated with this Call.

InvalidStateException - Either the Provider is not "in service", Call was not "active", or the TerminalConnection argument was "dropped".

MethodNotSupportedException - This method is not supported by the implementation.

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

getTransferController

public TerminalConnection getTransferController()

Returns the TerminalConnection which currently acts as the transfer controller. The transfer controller represents the participant in the Call around which a transfer takes place.

When a Call is initially created, the transfer controller is set to null. This method returns non-null only if the application has previously set the transfer controller. If the current transfer controller leaves the telephone call, the transfer controller is reset to null.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() != Call.INVALID

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() != Call.INVALID
3. Let tc = this.getTransferController()
4. Let connections[] = this.getConnections()
5. tc element of connections[i].getTerminalConnections() for all i, if tc is not null
6. tc.getCallControlState() != CallControlTerminalConnection.DROPPED, if tc is not null

Returns:

The current TerminalConnection acting as the transfer controller, null if one is not set.

setConferenceEnable

public void setConferenceEnable(boolean enable)
                         throws InvalidArgumentException,
                                InvalidStateException,
                                MethodNotSupportedException,
                                PrivilegeViolationException

Controls whether the Call is permitted or able to perform the conferencing feature. The boolean argument provided indicates whether conferencing should be turned on (true) or off (false). This method throws an exception if the boolean argument is true and the implementation does not support the conferencing feature. This method must be invoked when the Call is in the Call.IDLE state.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE
3. enable = this.getConferenceEnable()

Parameters:

enable - True turns conferencing on, false turns conferencing off.

Throws:

InvalidArgumentException - Conferencing cannot be turned on as requested by a true argument.

InvalidStateException - Either the Provider is not "in service" or the Call is not "idle".

MethodNotSupportedException - This method is not supported by the implementation.

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

getConferenceEnable

public boolean getConferenceEnable()

Return true if conferencing is enabled, false otherwise. Applications may use this method initially to obtain the default value set by the implementation and may attempt to change this value using the CallControlCall.setConferenceEnable() method.

Returns:

True if conferencing is enabled, false otherwise.

setTransferEnable

public void setTransferEnable(boolean enable)
                       throws InvalidArgumentException,
                              InvalidStateException,
                              MethodNotSupportedException,
                              PrivilegeViolationException

Controls whether the Call is permitted or able to perform the transferring feature. The boolean argument provided indicates whether transferring should be turned on (true) or off (false). This method throws an exception if the boolean argument is true and the implementation does not support the transferring feature. This method must be invoked when the Call is in the Call.IDLE state.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE
3. enable = this.getConferenceEnable()

Parameters:

enable - True turns transferring on, false turns transferring off.

Throws:

InvalidArgumentException - Transferring cannot be turned on as requested by the true argument.

InvalidStateException - Either the Provider is not "in service" or the Call is not "idle".

MethodNotSupportedException - This method is not supported by the implementation.

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

getTransferEnable

public boolean getTransferEnable()

Return true if transferring is enabled, false otherwise. Applications may use this method initially to obtain the default value set by the implementation and may attempt to change this value using the CallControlCall.setTransferEnable() method.

Returns:

True if transferring is enabled, false otherwise.

consult

public Connection[] consult(TerminalConnection tc,
                            java.lang.String dialedDigits)
                     throws InvalidStateException,
                            InvalidArgumentException,
                            MethodNotSupportedException,
                            ResourceUnavailableException,
                            PrivilegeViolationException,
                            InvalidPartyException

Creates a consultation between this Call and an active Call. A consultation Call is a new, idle Call which is associated with a particular existing Call and often created for a particular purpose. For example, the consultation Call may be used simply to "consult" with another party or to conference or transfer with its associated Call. This method establishes a special relationship between the two Calls which extends down to the telephony platform level. Most often, this feature is directly provided by the underlying telephony platform.

This Call Object

The instance on which this method is invoked is used as the Call on which the consultation takes place. This Call must be in Call.IDLE and is created with the Provider.createCall() method.

The TerminalConnection Argument

The TerminalConnection argument provides two pieces of information. The first piece of information is the other active Call to which this idle Call is associated. The Call associated with the TerminalConnection argument must be in the Call.ACTIVE state.

The second piece of information given by the TerminalConnection argument is the originating endpoint from which to place a telephone call on this idle Call. That is, the Address and Terminal associated with the TerminalConnection argument are used as the originating endpoint for the telephone call. The state of the TerminalConnection must be CallControlTerminalConnection.TALKING and this method first moves it into the CallControlTerminalConnection.HELD in order to place a telephone call on this idle Call.

The Destination Address String

A telephone call is placed to the destination telephone address string given as the second argument to this method. This address string must be valid and complete.

The Consultation Purpose

As mentioned above, the purpose of creating a consultation Call is often to perform a transfer or conference action on these two Calls. If the methods CallControlCall.setConferenceEnable() and CallControlCall.setTransferEnable() are supported as indicated by the CallControlCallCapabilities interface, applications must specify the purpose of the consultation Call by first telling the telephony platform if the intend to perform a transfer and/or conference action.

If the CallControlCall.setConferenceEnable() and the CallControlCall.setTransferEnable() methods are not supported as indicated by this interface's capabilities, applications permit the telephony platform to use the static, default values reported by the CallControlCall.getConferenceEnable() and the CallControlCall.getTransferEnable() methods.

The Telephone Call

A telephone call is placed on this Call and an array of two Connections are returned representing the originating and destination participants of the Call. The Call progresses in the same way as if the Call was placed using the Call.connect() method. The description of that method describes different scenarios under which the state of the call progresses.

Pre-conditions:

1. this.getProvider().getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE
3. tc.getCallControlState() == CallControlTerminalConnection.TALKING
4. (tc.getCall()).getState() == Call.ACTIVE

Post-conditions:

1. Let connections[] be the two Connections created and returned
2. this.getProvider().getState() == Provider.IN_SERVICE
3. this.getState() == Call.ACTIVE
4. tc.getCallControlState() == CallControlTerminalConnection.HELD
5. (tc.getCall()).getState() == Call.ACTIVE
6. Let c[] = this.getConnections() such that c.length == 2
7. c[0].getCallControlState() at least CallControlConnection.IDLE
8. c[1].getCallControlState() at least CallControlConnection.IDLE
9. c == connection
10. CallActiveEv is delivered for this Call
11. ConnCreatedEv are delivered for both connections[i]
12. CallCtlTermConnHeldEv is delivered for tc

Parameters:

tc - The controlling TerminalConnection for the consultation call.

dialedDigits - The destination telephone address string to which a telephone call is being placed.

Returns:

The two new Connections in the Call.

Throws:

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

PrivilegeViolationException - The application does not have the proper authority to place a consultation telephone call.

InvalidArgumentException - The TerminalConnection given is not a valid originating endpoint for a Call.

InvalidPartyException - The destination address string is not valid and/or complete.

InvalidStateException - Either the Provider is not "in service", the Call is not "idle", the other Call is not "active", or the TerminalConnection is not "talking".

MethodNotSupportedException - The implementation does not support this method.

See Also:

CallActiveEv, ConnCreatedEv, CallCtlTermConnHeldEv

consult

public Connection consult(TerminalConnection tc)
                   throws InvalidStateException,
                          InvalidArgumentException,
                          MethodNotSupportedException,
                          ResourceUnavailableException,
                          PrivilegeViolationException

Creates a consultation between this Call and an active Call. A consultation call is a new, idle Call which is associated with a particular existing Call and often created for a particular purpose. For example, the consultation call may be used simply to "consult" with another party or to conference or transfer with its associated Call. This method establishes a special relationship between the two Calls which extends down to the telephony platform level. Most often, this feature is directly provided by the underlying telephony platform.

This overloaded version of this method has a single difference with the other version of the CallControlCall.consult() method. This method does not take a destination telephone address string as an argument.

This method creates and returns a single Connection which is in the CallControlConnection.INITIATED state. Applications may use the CallControlConnection.addToAddress() method to dial the destination address digits.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE
3. tc.getCallControlState() == CallControlTerminalConnection.TALKING
4. (tc.getCall()).getState() == Call.ACTIVE

Post-conditions:

1. Let connection be the connection created and returned
2. (this.getProvider()).getState() == Provider.IN_SERVICE
3. this.getState() == Call.IDLE
4. tc.getCallControlState() == CallControlTerminalConnection.HELD
5. (tc.getCall()).getState() == Call.ACTIVE
6. connection == c
7. Let c = this.getConnections() such that c.length == 1
8. c[0].getCallControlState() == CallControlConnection.INITIATED
9. ConnCreatedEv is delivered for connection
10. CallCtlConnInitiatedEv/ConnConnectedEv is delivered for connection
11. CallActiveEv is delivered for this Call

Parameters:

tc - The controlling TerminalConnection for the consultation call.

Returns:

The Connection in the "initiated" state.

Throws:

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

PrivilegeViolationException - The application does not have the proper authority to place a consultation telephone call.

InvalidArgumentException - The TerminalConnection given is not a valid originating endpoint for a Call.

InvalidStateException - Either the Provider is not "in service", the Call is not "idle", the other Call is not "active", or the TerminalConnection is not "talking".

MethodNotSupportedException - The implementation does not support this method.

See Also:

CallActiveEv, ConnCreatedEv, ConnConnectedEv, CallCtlConnInitiatedEv