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

Interface java.telephony.callcontrol.CallControlCall

public interface CallControlCall
extends Object
extends Call
The CallControlCall interface extends the core Call interface. The CallControlCall interface provides more functionality on the Call object for the purposes of the CallControl package.

Particularly, it provides the addParty() method call to conference in an additional party, the drop() method to drop the entire Call, the conference() method to conference two calls together, the transfer() method to transfer a telephone call, and the consult() method to begin a consultation telephone Call.


Method Index

 o addParty(String)
Adds an additional party to an existing telephone Call.
 o conference(Call)
Merges two Calls together resulting in the union of the parties involved with both calls belong to a single telephone call.
 o consult(TerminalConnection, String)
Begins a consultation Call with the existing Call.
 o consult(TerminalConnection)
This overloaded version of consult() is similar to the other version of consult, except it does not take a destination string address as an argument.
 o drop()
Drops the entire Call.
 o getCalledAddress()
Returns the called Address associated with this Call.
 o getCallingAddress()
Returns the calling Address associated with this call.
 o getCallingTerminal()
Returns the calling Terminal associated with this Call.
 o getConferenceController()
Gets the TerminalConnection which is current acting as the "conference controller." The conference controller is a TerminalConnection on a telephone Call object whose Terminal is also part of another telephone call.
 o getConferenceEnable()
Return true if conferencing is enabled, false otherwise.
 o getLastRedirectedAddress()
Returns the last redirected Address associated with this Call.
 o getTransferController()
Gets the TerminalConnection which is current acting as the "transfer controller." The transfer controller is a TerminalConnection on a telephone Call object whose Terminal is also part of another telephone call.
 o getTransferEnable()
Return true if transfering is enabled, false otherwise.
 o offHook(Address, Terminal)
Takes the originating end of a telephone call off-hook.
 o setConferenceController(TerminalConnection)
Sets the TerminalConnection which is current acting as the "conference controller." The conference controller is a TerminalConnection on a telephone Call object whose Terminal is also part of another telephone call.
 o setConferenceEnable(boolean)
Controls whether this Call object is permitted or able to perform the conferencing feature.
 o setTransferController(TerminalConnection)
Sets the TerminalConnection which is current acting as the "transfer controller." The transfer controller is a TerminalConnection on a telephone Call object whose Terminal is also part of another telephone call.
 o setTransferEnable(boolean)
Controls whether this Call object is permitted or able to perform the transfering feature.
 o transfer(Call)
This flavor of the transfer() method transfer all parties currently associated with the Call to another telephone Call.
 o transfer(String)
This flavor of the transfer() method transfer all parties currently associated with the Call to another telephony number address.

Methods

 o getCallingAddress
  public abstract CallControlAddress getCallingAddress() throws PlatformException
Returns the calling Address associated with this call. The calling Address is defined as the Address which placed the telephone call.

If the calling address is unknown or not yet known, this method returns null.

Returns:
The calling Address.
Throws: PlatformException
Some platform-specific exception occured.
 o getCallingTerminal
  public abstract CallControlTerminal getCallingTerminal() throws PlatformException
Returns the calling Terminal associated with this Call. The calling Terminal is defined as the Terminal which placed the telephone call.

If the calling Terminal is unknown or not yet know, this method returns null.

Returns:
The calling Terminal.
Throws: PlatformException
Some platform-specific exception occured.
 o getCalledAddress
  public abstract CallControlAddress getCalledAddress() throws PlatformException
Returns the called Address associated with this Call. The called Address is defined as the Address to which the call has been originally placed.

If the called address is unknown or not yet known, this method returns null.

Returns:
s The called Address.
Throws: PlatformException
Some platform-specific exception occured.
 o getLastRedirectedAddress
  public abstract CallControlAddress getLastRedirectedAddress() throws PlatformException
Returns the last redirected Address associated with this Call. The last redirected Address is the Address at which the current telephone call was placed immediately before the current Address. This is common if a Call is forwarded to several Addresses before being answered.

If the the last redirected address is unknown or not yet known, this method returns null.

Returns:
s The last redirected Address for this telephone Call.
Throws: PlatformException
Some platform-specific exception occured.
 o addParty
  public abstract CallControlConnection addParty(String newParty) throws InvalidStateException, InvalidPartyException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Adds an additional party to an existing telephone Call. This is sometimes called a "single-step conference" because a party is conferenced into a telephone call directly. The telephony address provided must be complete and valid.

The Call must be ACTIVE before this method is valid. This Call must also have at least two Connections in the CONNECTED state. An addition restriction requires that at most one other Connection may be in either the INPROGRESS state or ALERTING state. The Provider must also be IN_SERVICE. The pre-conditions for this method are given by the following:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. c = call.getConnections() && c.length >= 2
  4. c = call.getConnections() && two connections.getState() == CONNECTED
  5. there exists at most one c = call.getConnections() such that c.getState() equals ALERTING or INPROGRESS.

This method creates a new Connection and associates it with the Call and the Address object associated with the new party. This Connection is in the IDLE state and is the return value for this method. The post-conditions which are true when this method returns are as follows, where 'c' is the returned connection.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. c.getState() == IDLE

In a typical scenario, this new Connection has the same sequence of state transitions as a destination Connection when the method Call.connect() is invoked. Documentation of that method provides detail of the possible state transition scenarios of the new Connection created by this method.

On some platforms, switch limitations impose restrictions on the number of connections of a particular state in a call. For instance, it is common to restrict the number of ALERTING connections to at most one. If any operation is attempted that would violate one of these restrictions. As a result, one precondition for this method is that there cannot be another connection in either the INPROGRESS or ALERTING state. Although some systems may not enforce this requirement, for consistency the Java Telephony API chose this conservative requirement.

Parameters:
newParty - The telephone number address of the party to be added.
Returns:
The new Connection associated with the added party.
Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: InvalidPartyException
The new party to be added to the call is invalid.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o drop
  public abstract void drop() throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Drops the entire Call. This method is equivalent to using the disconnect() method on each Connections which is part of the Call. There are some Connections which the application does not possess the proper authority to drop. In this case, the drop() method performs no action on these. As a result of dropping some of the Connection, the other Connections which the application cannot control may drop automatically as a result. If all Connections succeed in moving to the DISCONNECTED state, the call becomes INVALID. This method returns when it can successfully drop as many Connections are possible. All of the TerminalConnections associated with the dropped Connections will move into the DROPPED state.

The pre-conditions for this method are:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE

The post-conditions for this method are:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. if all connections = call.getConnections() and connections.getState() == DISCONNECTED, then call.getState() == INVALID
  3. for all connections = call.getConnections and connections.getState() == DISCONNECTED, for all termconns = connections.getTerminalConnections(), termconns.getState() == DROPPED.

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 and it can drop none of the Connections.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o offHook
  public abstract CallControlConnection offHook(Address origaddress,
                                                Terminal origterminal) throws InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Takes the originating end of a telephone call off-hook. This method permits application to simply take the originating terminal of a telephone 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 Call object must be in the IDLE state prior to the invocation of this method. This method creates a Connection to the originating Address in the CallControlConnection.INITIATED state and returns this Connection at the successful completion of this method. This method also creates a TerminalConnection associated with the originating Terminal in the CallControlTerminalConnection.TALKING state.

The pre-conditions for this method are:

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

The post-conditions for this method are:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. Let Connnection c = this.offHook(Address, Terminal)
  3. c.getCallControlState() == CallControlConnection.INITIATED
  4. Let TerminalConnection tc[] = c.getTerminalConnections()
  5. tc.length == 1
  6. tc[0].getCallControlState() == CallControlTerminalConnection.TALKING;
  7. tc element of origterminal.getTerminalConnections()
  8. c element of origaddress.getConnections()
  9. c element of this.getConnections()

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
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 and it can drop none of the Connections.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o conference
  public abstract void conference(Call otherCall) throws InvalidStateException, InvalidArgumentException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
Merges two Calls together resulting in the union of the parties involved with both calls belong to a single telephone call. The telephone Call provided as the argument has its Connections move to this Call object, and the Call object argument becomes invalid.

In order for a conference action to be successful, there must exist a Terminal object which is part of both telephone Calls. Furthermore, this Terminal object will have two TerminalConnections associated with it which are each part of one of the Calls. An application may have specified on such TerminalConnections on this call to be the "conference controller". If the application did not make such a selection, the implementation chooses a suitable Terminal and TerminalConnection. We shall call the TerminalConnection on this Call acting as the conference controller (whether selected by the application or not) as "conftermconn" and its Terminal as "confterm". The TerminalConnection associated with confterm and the second Call object, we shall call "scndtermconn". The following are the initial pre-condition predicates for this method:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. conftermconn element of call.getConnections().getTerminalConnections()
  4. conftermconn element of confterm.getTerminalConnections()
  5. scndtermconn element of othercall.getConnections().getTerminalConnections()
  6. scndtermconn element of confterm.getTerminalConnections()

These two TerminalConnections must be in a particular state. Specifically, conftermconn must be in the CallControlTerminalConnection.ACTIVE state and scndtermconn must be in the CallControlTerminalConnection.HELD state. These additional pre-conditions are listed below:

  1. conftermconn.getState() == ACTIVE
  2. scndtermcomm.getState() == HELD

The conference() method "merges" these two telephone Calls together by taking all of the Connections and TerminalConnections on otherCall and creating new Connections and TerminalConnections with the same Address and Terminal objects, respectively, in the same state as in oldCall. The conftermconn and scndtermconn are the exception. The scndtermconn TerminalConnection in otherCall moves to the DROPPED state. Let c equal some Connections in otherCall and tc equal some TerminalConnection in otherCall. Then, for all Connection's c and TerminalConnections tc (with the exception tc = scndtermconn), the following post-conditions indicate the result of the conference method. The construct new(c) and new(tc) mean to create a new Connection and TerminalConnection object with the same Address and TerminalConnection references.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. new(c) element of call.getConnections()
  4. new(c).getState() == c.getState()
  5. new(tc) element of (call.getConnections()).getTerminalConnections()
  6. new(tc).getState() == tc.getState()

Finally, the Connections and TerminalConnections in otherCall move to DISCONNECTED and DROPPED respectively, and otherCall becomes INVALID.

  1. c.getState() == DISCONNECTED
  2. tc.getState() == DROPPED
  3. otherCall.getState() == INVALID

Parameters:
otherCall - The second Call which to merge with this Call object.
Throws: InvalidArgumentException
The Call object provided is not valid for the conference
Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o transfer
  public abstract void transfer(Call otherCall) throws InvalidStateException, InvalidArgumentException, InvalidPartyException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
This flavor of the transfer() method transfer all parties currently associated with the Call to another telephone Call. Here, all parties associated with the Call provided as the argument are moved to this Call object.

There must be a Terminal which is part of both calls on the same Address. This Terminal has a TerminalConnection to each of the telephone calls. If more than one such Terminal exists, the implementation choose are suitable one. If no such Terminal exists, this method throws an exception. Let us call the TerminalConnection associated with this call 'termconn' and the TerminalConnection associated with otherCall, 'scndtermconn'.

These two TerminalConnections (and the Terminal) drop off of the Call once the transfer takes place. The fact that this Terminal drops from the call is a distinguishing feature between this transfer() method and conference(). The TerminalConnections must either be in the TALKING or HELD state (these are CallControlTerminalConnection states). The Provider must be IN_SERVICE. These pre-conditions are listed below:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. otherCall.getState() == ACTIVE
  4. termconn element of (call.getConnections()).getTerminalConnections()
  5. termconn.getState() == TALKING or HELD
  6. scndtermconn element of (otherCall.getConnections()).getTerminalConnections()
  7. scndtermconn.getState() == TALKING or HELD

This method moves the termconn and scndtermconn into the DROPPED state, and if it is the only TerminalConnection on the Connection, the Connection moves to the DISCONNECTED state. The sncdtermconn object also moves into the TerminalConnection state and does not get moved to this Call object. All other Connections and TerminalConnections which are part of otherCall are moved to this Call object in the same state as they were in otherCall. New Connection objects are created, and the old Connection and TerminalConnection objects on otherCall move to DISCONNECTED and DROPPED, respectively. The otherCall object becomes INVALID. The post-conditions of this method are as follows:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn.getState() == DROPPED
  4. (termconn.getConnection()).getTerminalConnections is of length 1, then (termconn.getConnection()).getState() == DISCONNECTED
  5. scndtermconn.getState() == DROPPED
  6. For all connections in otherCall.getConnections(),call.getConnections() has an element in the same state and the same Address reference.
  7. For all terminalconnection in (otherCall.getConnections()).getTerminalConnections(), this call object has the same number of TerminalConnections minus scndtermconn in the same state and associated with the same Connection and Terminal.
  8. For all connections in otherCall.getConnections(), connections.getState() == DISCONNECTED
  9. For all terminalconnections in connections.getTerminalConnections(), terminalconnections.getState() == DROPPED
  10. otherCall.getState() == INVALID

Parameters:
otherCall - The other Call which to transfer to this Call.
Throws: InvalidArgumentException
The TerminalConnection controlling the transfer is not valid or does not exists or the other telephone call is not valid.
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.
Throws: Exception
An implementation-specific exception occurred.

Throws: PlatformException
A platform-specific exception occurred.
 o transfer
  public abstract CallControlConnection transfer(String address) throws InvalidArgumentException, InvalidStateException, InvalidPartyException, MethodNotSupportedException, PrivilegeViolationException, ResourceUnavailableException, PlatformException
This flavor of the transfer() method transfer all parties currently associated with the Call to another telephony number address. Typically, the participants of call will hear the new address alerting. The telephone address provided must be valid and complete.

The transfer() method is associated with some TerminalConnection which is part of the current telephony Call. This TerminalConnection specifies from which Terminal is transfer is being invoked. This Terminal and TerminalConnection drop off from the call once transferred. This special TerminalConnection is called the "transfer controller" and is optionally set by the setTransferController() method. If applications do not select a transfer controller, then the implementations will select a suitable one. For the purposes of this method, this transfer controller TerminalConnection will be denoted as 'termconn'.

The transfer controller must be in the ACTIVE state and be part of this telephone call. The Provider must also be IN_SERVICE. The pre-conditions for this method are:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn element of (call.getConnections()).getTerminalConnections()
  4. termconn.getState() == ACTIVE

This method moves the termconn into the DROPPED state, and if it is the only TerminalConnection on the Connection, the Connection moves to the DISCONNECTED state. The transfer() method then creates a new Connection in the IDLE state to an Address object corresponding to the string telephone number address provided. The transfer() method returns this new Connection. The post-conditions of this method are as follows, given the returned Connection is denoted by 'connection':

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn.getState() == DROPPED
  4. (termconn.getConnection()).getTerminalConnections is of length 1, then (termconn.getConnection()).getState() == DISCONNECTED
  5. if connection != null, connection is an element of call.getConnections()
  6. if connection != null, then connection.getState() == IDLE

An application can expect the new connection to transition through the Connection states similiar to a destination Connection does after a Call.connect() is invoked.

Note that the new Connection created and returned may be null. This Connection will be null in the case that the Call has transferred out of the Provider's domain.

Parameters:
address - The destination address 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 telephone Call.
Throws: InvalidStateException
The state of some object is not valid as designated by the pre-conditions for this method.
Throws: InvalidPartyException
The new party to transfer to is invalid.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: PrivilegeViolationException
The application does not have the proper authority to invoke this method.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o setConferenceController
  public abstract void setConferenceController(TerminalConnection termconn) throws InvalidArgumentException, InvalidStateException, MethodNotSupportedException, ResourceUnavailableException, PlatformException
Sets the TerminalConnection which is current acting as the "conference controller." The conference controller is a TerminalConnection on a telephone Call object whose Terminal is also part of another telephone call. When performing a conference of two telephone Call objects, this TerminalConnection and the Terminal's TerminalConnection which is part of the second call are merged into one in the merged Call object.

The Call must be in the ACTIVE state in order for this method not to throw an exception. The TerminalConnection supplied as the conference controller must be in the Call and must not be in the DROPPED state. The Provider must also be IN_SERVICE. These pre-conditions are given below.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn union (call.getConnections()).getTerminalConnections() == termconn
  4. termconn.getState() != DROPPED

If these pre-conditions are met, this method sets the given TerminalConnection as the conference controller, where the following post-conditions are met:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn union (call.getConnections()).getTerminalConnections() == termconn
  4. termconn.getState() != DROPPED
  5. termconn == call.getConferenceController()

Parameters:
termconn - The TerminalConnection to use as the conference controller
Throws: InvalidArgumentException
The TerminalConnection object provided is not associated with this Call object.
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: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o getConferenceController
  public abstract CallControlTerminalConnection getConferenceController() throws PlatformException
Gets the TerminalConnection which is current acting as the "conference controller." The conference controller is a TerminalConnection on a telephone Call object whose Terminal is also part of another telephone call. When performing a conference of two telephone Call objects, this TerminalConnection and the Terminal's TerminalConnection which is part of the second call are merged into one in the merged Call object.

When a Call is initially created, the conference controller is set to null. This method returns non-null only if the application has previously successfully invoked the setConferenceController() method. If a TerminalConnection, which is currently the conference controller, moves into the DROPPED state in the Call, the conference controller is then set to null once again.

This method requires that the Provider is IN_SERVICE and the call is either IDLE or ACTIVE. The pre-conditions are listed below.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == IDLE or call.getState() == ACTIVE

The post conditions for this method ensure that the returned TerminalConnection, if not null, is in the call and not in the DROPPED state as given below, where 'termconn' is the TerminalConnection returned from this method:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == IDLE or call.getState() == ACTIVE
  3. if termconn != null, then termconn is an element of (call.getConnections()).getTerminalConnections()
  4. if termconn != null, then termconn.getState() != DROPPED

Returns:
The current TerminalConnection acting as the conference controller, null if one is not set.
Throws: PlatformException
A platform-specific exception occurred.
 o setTransferController
  public abstract void setTransferController(TerminalConnection termconn) throws InvalidArgumentException, InvalidStateException, MethodNotSupportedException, ResourceUnavailableException, PlatformException
Sets the TerminalConnection which is current acting as the "transfer controller." The transfer controller is a TerminalConnection on a telephone Call object whose Terminal is also part of another telephone call. When performing a transfer of telephone Call objects, this TerminalConnection and the Terminal's TerminalConnection which is part of the second call are dropped.

The Call must be in the ACTIVE state in order for this method not to throw an exception. The TerminalConnection supplied as the terminal controller must be in the Call and must not be in the DROPPED state. The Provider must also be IN_SERVICE. These pre-conditions are given below.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn union (call.getConnections()).getTerminalConnections() == termconn
  4. termconn.getState() != DROPPED

If these pre-conditions are met, this method sets the given TerminalConnection as the transfer controller, where the following post-conditions are met:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn union (call.getConnections()).getTerminalConnections() == termconn
  4. termconn.getState() != DROPPED
  5. termconn == call.getTransferController()

Parameters:
termconn - The TerminalConnection to use as the transfer controller
Throws: InvalidArgumentException
The TerminalConnection object provided is not associated with this Call object.
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: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is not available.
Throws: PlatformException
A platform-specific exception occurred.
 o getTransferController
  public abstract CallControlTerminalConnection getTransferController() throws PlatformException
Gets the TerminalConnection which is current acting as the "transfer controller." The transfer controller is a TerminalConnection on a telephone Call object whose Terminal is also part of another telephone call. When performing a transfer of two telephone Call objects, this TerminalConnection and the Terminal's TerminalConnection which is part of the second call are dropped in the merged call.

When a Call is initially created, the transfer controller is set to null. This method returns non-null only if the application has previously successfully invoked the setTransferController() method. If a TerminalConnection, which is currently the transfer controller, moves into the DROPPED state in the Call, the transfer controller is then set to null once again.

This method requires that the Provider is IN_SERVICE and the call is either IDLE or ACTIVE. The pre-conditions are listed below.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == IDLE or call.getState() == ACTIVE

The post conditions for this method ensure that the returned TerminalConnection, if not null, is in the call and not in the DROPPED state as given below, where 'termconn' is the TerminalConnection returned from this method:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == IDLE or call.getState() == ACTIVE
  3. if termconn != null, then termconn is an element of (call.getConnections()).getTerminalConnections()
  4. if termconn != null, then termconn.getState() != DROPPED

Returns:
The current TerminalConnection acting as the transfer controller, null if one is not set.
Throws: PlatformException
A platform-specific exception occurred.
 o setConferenceEnable
  public abstract void setConferenceEnable(boolean enable) throws InvalidArgumentException, InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, PlatformException
Controls whether this Call object is permitted or able to perform the conferencing feature. If the 'enable' argument is true, this method attempts to turn on the conferencing ability. If 'false' this method turns disallows the conferencing feature. If the implementation is unable to support conferencing, a setConferenceEnable(true) will throw an exception.

This method must be called when the Call object is first create and in the IDLE state. The provider must also be in service. The pre- conditions are as follows:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == IDLE

The post-conditions are as follows, given an exception is not thrown and the variable 'enable' represents the value of the parameter passed to this method.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == IDLE
  3. enable = call.getConferenceEnable();

Parameters:
enable - True turns conferencing on, false turns conferencing off.
Throws: InvalidArgumentException
The Connection object provided is not associated with this Address object.
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: PlatformException
A platform-specific exception occurred.
 o getConferenceEnable
  public abstract boolean getConferenceEnable() throws PlatformException
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.
Throws: PlatformException
A platform-specific exception occurred.
 o setTransferEnable
  public abstract void setTransferEnable(boolean enable) throws InvalidArgumentException, InvalidStateException, MethodNotSupportedException, PrivilegeViolationException, PlatformException
Controls whether this Call object is permitted or able to perform the transfering feature. If the 'enable' argument is true, this method attempts to turn on the transfering ability. If 'false' this method turns disallows the transfering feature. If the implementation is unable to support transfering, a setTransferEnable(true) will throw an exception.

This method must be called when the Call object is first create and in the IDLE state. The provider must also be in service. The pre- conditions are as follows:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == IDLE

The post-conditions are as follows, given an exception is not thrown and the variable 'enable' represents the value of the parameter passed to this method.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == IDLE
  3. enable = call.getTransferEnable();

Parameters:
enable - True turns transfering on, false turns transfering off.
Throws: InvalidArgumentException
The Connection object provided is not associated with this Address object.
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: PlatformException
A platform-specific exception occurred.
 o getTransferEnable
  public abstract boolean getTransferEnable() throws PlatformException
Return true if transfering 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 transfering is enabled, false otherwise.
Throws: PlatformException
A platform-specific exception occurred.
 o consult
  public abstract CallControlCall consult(TerminalConnection termconn,
                                          String address) throws InvalidStateException, InvalidArgumentException, MethodNotSupportedException, ResourceUnavailableException, PrivilegeViolationException, PlatformException
Begins a consultation Call with the existing Call. A consultation Call is a new telephone Call placed to a telephony number address and is associated with the current telephony Call. The purpose of creating a consultation call is to either simply consult with another party or eventually to either conference in or transfer to with the existing party. The creation of the new Call behaves in a similar manner as Call.connect(), however the consult() method establishes a special association between the new Call and the current telephone Call. The consult() method exists because it is often a switch feature and establishes the special association between the current telephone Call. The telephone number address provided must be valid and complete.

As mentioned above, the purpose of creating a consulation Call is often to perform a transfer() or conference() on these two Calls. Applications must specify their purpose by first telling the switch whether they intend to perform a conference() or transfer() or both using the setConferenceEnable() and setTransferEnable() methods on this object.

The originator of this new consultation call is given by a TerminalConnection which must be part of the current Call object and must be in the active state. The destination address for this new call is given by the second argument. Therefore, the new call placed is similar to the Call.connect() method in that the originating Terminal is termconn.getTerminal() and the origination Address is (termconn.getConnection()).getAddress().

This method places termconn in the HELD state and create a new Call object. This Call object has two connection, one each for the originating side and the destination side. Both of these Connections are in the IDLE state. This new Call object is returned by the consult() method. The Provider must also be IN_SERVICE. The pre-conditions of this method are given below:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn is element of call.getConnections().getTerminalConnections()
  4. termconn.getState() == ACTIVE

The post-conditions for this method are as follows, where the Call object returned is denoted by 'newcall'.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn.getState() == HELD
  4. newcall.getState() == ACTIVE
  5. Let c = newcall.getConnections() such that c.length == 2
  6. c[0].getState == IDLE
  7. c[1].getState == IDLE

An application can expect that this new Call object will exhibit the same Connection and TerminalConnection state transition scenarios as Calls placed using Call.connect() and as described in the documentation for that method.

Parameters:
termconn - The controlling TerminalConnection for the consultation call.
address - The destination telephone number address.
Returns:
The new consultation Call object.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is unavailable.
Throws: PrivilegeViolationException
The application does not have the proper authority to place a consultation telephone call.
Throws: InvalidArgumentException
An argument provided is not valid either by not providing enough information for consult() or is inconsistent with another argument.
Throws: InvalidStateException
Some object required by this method is not is a valid state as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
The implementation does not support this method.
Throws: PlatformException
A platform-specific exception occurred.
 o consult
  public abstract CallControlCall consult(TerminalConnection termconn) throws InvalidStateException, InvalidArgumentException, MethodNotSupportedException, ResourceUnavailableException, PrivilegeViolationException, PlatformException
This overloaded version of consult() is similar to the other version of consult, except it does not take a destination string address as an argument. Instead, it creates a Call object with one Connection in the CallControlConnection.INITIATED state. Applications may use the CallControlConnection.addToAddress() method to dial the destination digits.

This method places termconn in the HELD state and create a new Call object. This new Call object is returned by the consult() method. The Provider must also be IN_SERVICE. The pre-conditions of this method are given below:

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn is element of call.getConnections().getTerminalConnections()
  4. termconn.getState() == ACTIVE

The post-conditions for this method are as follows, where the Call object returned is denoted by 'newcall'.

  1. (call.getProvider()).getState() == IN_SERVICE
  2. call.getState() == ACTIVE
  3. termconn.getState() == HELD
  4. newcall.getState() == ACTIVE
  5. Let c = newcall.getConnections() such that c.length == 1
  6. c[0].getState == INITIATED

Parameters:
termconn - The controlling TerminalConnection for the consultation call.
Returns:
The new consultation Call object.
Throws: ResourceUnavailableException
An internal resource neccessary for the successful invocation of this method is unavailable.
Throws: PrivilegeViolationException
The application does not have the proper authority to place a consultation telephone call.
Throws: InvalidArgumentException
An argument provided is not valid either by not providing enough information for consult() or is inconsistent with another argument.
Throws: InvalidStateException
Some object required by this method is not is a valid state as designated by the pre-conditions for this method.
Throws: MethodNotSupportedException
The implementation does not support this method.
Throws: PlatformException
A platform-specific exception occurred.

All Packages  Class Hierarchy  This Package  Previous  Next  Index