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.
-
addParty(String)
- Adds an additional party to an existing telephone Call.
-
conference(Call)
- Merges two Calls together resulting in the union of the parties involved
with both calls belong to a single telephone call.
-
consult(TerminalConnection, String)
- Begins a consultation Call with the existing Call.
-
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.
-
drop()
- Drops the entire Call.
-
getCalledAddress()
- Returns the called Address associated with this Call.
-
getCallingAddress()
- Returns the calling Address associated with this call.
-
getCallingTerminal()
- Returns the calling Terminal associated with this Call.
-
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.
-
getConferenceEnable()
- Return true if conferencing is enabled, false otherwise.
-
getLastRedirectedAddress()
- Returns the last redirected Address associated with this Call.
-
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.
-
getTransferEnable()
- Return true if transfering is enabled, false otherwise.
-
offHook(Address, Terminal)
- Takes the originating end of a telephone call off-hook.
-
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.
-
setConferenceEnable(boolean)
- Controls whether this Call object is permitted or able to perform
the conferencing feature.
-
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.
-
setTransferEnable(boolean)
- Controls whether this Call object is permitted or able to perform
the transfering feature.
-
transfer(Call)
- This flavor of the transfer() method transfer all parties currently
associated with the Call to another telephone Call.
-
transfer(String)
- This flavor of the transfer() method transfer all parties currently
associated with the Call to another telephony number address.
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.
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.
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.
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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- c = call.getConnections() && c.length >= 2
- c = call.getConnections() && two connections.getState() == CONNECTED
- 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.
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- 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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
The post-conditions for this method are:
- (call.getProvider()).getState() == IN_SERVICE
- if all connections = call.getConnections() and
connections.getState() == DISCONNECTED, then call.getState() == INVALID
- 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.
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:
- (this.getProvider()).getState() == Provider.IN_SERVICE
- this.getState() == Call.IDLE
The post-conditions for this method are:
- (this.getProvider()).getState() == Provider.IN_SERVICE
- Let Connnection c = this.offHook(Address, Terminal)
- c.getCallControlState() == CallControlConnection.INITIATED
- Let TerminalConnection tc[] = c.getTerminalConnections()
- tc.length == 1
- tc[0].getCallControlState() == CallControlTerminalConnection.TALKING;
- tc element of origterminal.getTerminalConnections()
- c element of origaddress.getConnections()
- 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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- conftermconn element of call.getConnections().getTerminalConnections()
- conftermconn element of confterm.getTerminalConnections()
- scndtermconn element of
othercall.getConnections().getTerminalConnections()
- 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:
- conftermconn.getState() == ACTIVE
- 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.
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- new(c) element of call.getConnections()
- new(c).getState() == c.getState()
- new(tc) element of (call.getConnections()).getTerminalConnections()
- new(tc).getState() == tc.getState()
Finally, the Connections and TerminalConnections in otherCall move to
DISCONNECTED and DROPPED respectively, and otherCall becomes INVALID.
- c.getState() == DISCONNECTED
- tc.getState() == DROPPED
- 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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- otherCall.getState() == ACTIVE
- termconn element of (call.getConnections()).getTerminalConnections()
- termconn.getState() == TALKING or HELD
- scndtermconn element of
(otherCall.getConnections()).getTerminalConnections()
- 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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn.getState() == DROPPED
- (termconn.getConnection()).getTerminalConnections is of length 1, then
(termconn.getConnection()).getState() == DISCONNECTED
- scndtermconn.getState() == DROPPED
- For all connections in otherCall.getConnections(),call.getConnections()
has an element in the same state and the same Address reference.
- 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.
- For all connections in otherCall.getConnections(),
connections.getState() == DISCONNECTED
- For all terminalconnections in connections.getTerminalConnections(),
terminalconnections.getState() == DROPPED
- 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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn element of (call.getConnections()).getTerminalConnections()
- 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':
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn.getState() == DROPPED
- (termconn.getConnection()).getTerminalConnections is of length 1, then
(termconn.getConnection()).getState() == DISCONNECTED
- if connection != null, connection is an element of call.getConnections()
- 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.
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.
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn union (call.getConnections()).getTerminalConnections() ==
termconn
- 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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn union (call.getConnections()).getTerminalConnections() ==
termconn
- termconn.getState() != DROPPED
- 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.
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.
- (call.getProvider()).getState() == IN_SERVICE
- 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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == IDLE or call.getState() == ACTIVE
- if termconn != null, then termconn is an element of
(call.getConnections()).getTerminalConnections()
- 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.
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.
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn union (call.getConnections()).getTerminalConnections() ==
termconn
- 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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn union (call.getConnections()).getTerminalConnections() ==
termconn
- termconn.getState() != DROPPED
- 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.
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.
- (call.getProvider()).getState() == IN_SERVICE
- 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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == IDLE or call.getState() == ACTIVE
- if termconn != null, then termconn is an element of
(call.getConnections()).getTerminalConnections()
- 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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- 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.
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == IDLE
- 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.
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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- 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.
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == IDLE
- 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.
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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn is element of call.getConnections().getTerminalConnections()
- termconn.getState() == ACTIVE
The post-conditions for this method are as follows, where the Call object
returned is denoted by 'newcall'.
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn.getState() == HELD
- newcall.getState() == ACTIVE
- Let c = newcall.getConnections() such that c.length == 2
- c[0].getState == IDLE
- 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.
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:
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn is element of call.getConnections().getTerminalConnections()
- termconn.getState() == ACTIVE
The post-conditions for this method are as follows, where the Call object
returned is denoted by 'newcall'.
- (call.getProvider()).getState() == IN_SERVICE
- call.getState() == ACTIVE
- termconn.getState() == HELD
- newcall.getState() == ACTIVE
- Let c = newcall.getConnections() such that c.length == 1
- 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