OpenScape
V3.2, Revision 044 20100322

com.siemens.symphonia.bcom.bcommon.external
Interface VoiceConnection

All Superinterfaces:
ComConnection
All Known Subinterfaces:
VoiceConnectionInternal
All Known Implementing Classes:
AbstractVoiceConnection, VoiceConnectionImpl, VoiceConnectionImpl

public interface VoiceConnection
extends ComConnection

Connection of media type voice.

Specific characteristic of a ComConnection object which describes a connection of media type voice. Objects of this class are instantiated on demand by Basic Communication Service. Creation of such an object is notified either direct by the onNewConnection(ComConnection, ComEndpoint) event or indirect by the onNewCommunication(Communication, ComEndpoint) event as part of the graph constructed.
Release of such an object is also be done by Basic Communication and notified by an onTerminated(ComConnection, ComEndpoint) event.


Method Summary
 void alternate()
          Alternates between two connections.
 void alternate(ComConnection heldConnection)
          Deprecated. *** use alternate() instead ***
 void answer()
          Answers an incoming call.
 boolean canAlternate()
          Determine whether alternating of the connections is possible.
 boolean canAnswer()
          Determine whether answering an incoming call is possible.
 boolean canDeflect()
          Determine whether forwarting of this connection is possible.
 boolean canDeflectONS()
          Determine whether device handover in state ALERTING is possible.
 boolean canDrop()
          Determine whether terminating of this connection is possible.
 boolean canHold()
          Determine whether holding of this connection is possible.
 boolean canRetrieve()
          Determine whether retrieveing of this connection is possible.
 boolean canTransfer()
          Determine whether transferring of this connection is possible.
 boolean canTransferONS()
          Determine whether device handover in state CONNECTED is possible.
 void deflectONS()
          Hands device over in state ALERTING.
 java.lang.String getDisplayName()
          Determine the display name used by the communication system.
 java.lang.String getDisplayNumber()
          Determine the display number used by the communication system.
 FailedReason getFailedReason()
          Get reason for failed request.
 void hold()
          Holds a connection.
 boolean isDisplayRestricted()
          Indicates whether the owner of the connection has requested privacy.
 void retrieve()
          Retrieves a connection.
 ComConnection transfer(ComEndpoint transferToAddr)
          Transfers a connection to another target.
 ComConnection transfer(java.lang.String targetUri)
          Transfers a connection to another target.
 void transferONS()
          Hands device over in state CONNECTED.
 
Methods inherited from interface com.siemens.symphonia.bcom.bcommon.external.ComConnection
deflect, deflect, drop, getComEndpoint, getCommunication, getInitiationCause, getObjectId, getState, getTerminationCause, isMyConnection
 

Method Detail

answer

void answer()
Answers an incoming call.

An alerting call is answered. I.e. the state of the connection changes from ALERTING to CONNECTED and a communication to the caller is possible.

Note:
This method invokes a synchronous service request which implicates:

Throws:
ComException - on immediate detected problems.

hold

void hold()
Holds a connection.

The state of the connection is changed from CONNECTED to HELD. The other participant(s) of the communication can't hear the participant of this connection anymore.

Notes:
Typically there is played music on hold for the other participant(s). In case of an VCC controlled conference this is suppressed not to disturb the other participants of the conference.

This method invokes a synchronous service request which implicates:

Throws:
ComException - on immediate detected problems.

retrieve

void retrieve()
Retrieves a connection.

The state of the connection is changed from HELD to CONNECTED. The participant of this connection can talk again to the other participant(s).

Note:
This method invokes a synchronous service request which implicates:

Throws:
ComException - on immediate detected problems.

alternate

void alternate()
Alternates between two connections.

After setting up two connections in two different communications e.g. by using consult(ComConnection, ComEndpoint) it is possible to toggle between the two connection. The connection in state CONNECTED changes to HELD and the other connection from state HELD to CONNECTED. Therefore it is possible to talk to the two participants alternately.

This method must always be invoked on the VoiceConnection object which is in state CONNECTED.

Note:
This method invokes a synchronous service request which implicates:

Throws:
ComException - on immediate detected problems.

alternate

void alternate(ComConnection heldConnection)
Deprecated. *** use alternate() instead ***

Alternates between two connections.

After setting up two connections in two different communications e.g. by using consult(ComConnection, ComEndpoint) it is possible to toggle between the two connection. The connection in state CONNECTED changes to HELD and the other connection from state HELD to CONNECTED. Therefore it is possible to talk to the two participants alternately.

This method must always be invoked on the VoiceConnection object which is in state CONNECTED. The other connection is given as parameter.

Note:
This method invokes a synchronous service request which implicates:

Parameters:
heldConnection - the VoiceConnection object which is in state HELD.
Throws:
ComException - on immediate detected problems.

deflectONS

void deflectONS()
Hands device over in state ALERTING.

Allows to hand a connection in state ALERTING over from the currently used device to another device. You can then take the call on the new device. The caller doesn't get aware of this operation.
It is possible to do this multiple times, i.e. hand the connection again over to another device. And it is also possible to bring the connection back to the original device by this method.

The new device to be handed over to is selected in the following precedence:

  1. Override of preferred device is set on this communication by means of the method setPreferredDevice(ComEndpoint).
  2. Preferred device currently defined in User Service.
  3. ONS device of user.
In a device view always setPreferredDevice(ComEndpoint) must be used.

This connection will terminate and a new connection is created. The new connection will come into existence through a onNewConnection(ComConnection, ComEndpoint) event. The new connection becomes the own connection in the given user or device view (i.e. the method isMyConnection() will return true). The new connection will also receive an onAlerting(ComConnection, ComEndpoint) event.

Notes:
General:

This method invokes a synchronous service request which implicates:


transfer

ComConnection transfer(ComEndpoint transferToAddr)
Transfers a connection to another target.

While beeing in communication with another party it is possible to transfer this party to another target. The own connection is terminated as result of a successful transfer.

As long as the transfer is ongoing (i.e. the target has not yet answerred the call) the own connection is kept in the state TRANSFER_PENDING. If the target doesn't answer the call at all and the communication system is setup to "recall" the communication the call will be presented again on this connection. I.e. the state will change from TRANSFER_PENDING to ALERTING. This way a recall of a transferred connection can be detected.
Otherwise (i.e. the target answers the call) this connection gets terminated.

Note:
This method invokes a synchronous service request which implicates:

Parameters:
transferToAddr - endpoint of new destination.
Returns:
newly created ComConnection object.
Throws:
ComException - on immediate detected problems.

transfer

ComConnection transfer(java.lang.String targetUri)
Transfers a connection to another target.

Has the same semantics as transfer(ComEndpoint) but allows to specify the communication target as URI. The following URI formats are supported:

Parameters:
targetUri - URI new connection should be established to.
Returns:
newly created ComConnection object.
Throws:
ComException - on immediate detected problems.

transferONS

void transferONS()
Hands device over in state CONNECTED.

Has the same semantics as deflectONS(). The difference is it can be used in the state CONNECTED. I.e. an established call can be handed over to another device without interrupting the communication.

See deflectONS() for further details.


canAnswer

boolean canAnswer()
Determine whether answering an incoming call is possible.

Allows to check whether an invocation of the method answer() is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

canDrop

boolean canDrop()
Determine whether terminating of this connection is possible.

Allows to check whether an invocation of the method drop() is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

canDeflect

boolean canDeflect()
Determine whether forwarting of this connection is possible.

Allows to check whether an invocation of the method deflect(ComEndpoint) or deflect(String) is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

canDeflectONS

boolean canDeflectONS()
Determine whether device handover in state ALERTING is possible.

Allows to check whether an invocation of the method deflectONS() is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

canTransfer

boolean canTransfer()
Determine whether transferring of this connection is possible.

Allows to check whether an invocation of the method transfer(ComEndpoint) or transfer(String) is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

canTransferONS

boolean canTransferONS()
Determine whether device handover in state CONNECTED is possible.

Allows to check whether an invocation of the method transferONS() is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

canHold

boolean canHold()
Determine whether holding of this connection is possible.

Allows to check whether an invocation of the method hold() is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

canRetrieve

boolean canRetrieve()
Determine whether retrieveing of this connection is possible.

Allows to check whether an invocation of the method retrieve() is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

canAlternate

boolean canAlternate()
Determine whether alternating of the connections is possible.

Allows to check whether an invocation of the method alternate(ComConnection) is possible in the current state of the communication. This might change with every state change of the communication.

Returns:
true iff invocation is possible.

isDisplayRestricted

boolean isDisplayRestricted()
Indicates whether the owner of the connection has requested privacy.

Privacy means that the number, name or anything else identifieing the user/device may not be shown. In general any GUI application must show then localized "private" and do not perform directory name lookup, the private number must not permeate to the user.

In addition we have the dial out scenario where a user is dialing a number xyz which has display restriction. Of course since the user dialed xyz he wants to see xyz in the GUI even if the infrastructure signals that xyz is a number with display restrictions. So we need to display xyz in the GUI of this user, but not in the GUI of another user.

When the call is moved to another device we need of course to honor the display restriction above.

Beyond displaying on the GUI the ComEndpoint can be used at any time to lookup the directory entry or any other purpose. I.e. it is up to the client to implement this display restriction.

Returns:
true iff display of number and name is restricted.

getDisplayName

java.lang.String getDisplayName()
Determine the display name used by the communication system.

The name displayed on the phone device of the communication partners to this connection is determined by this method. This depends on the configuration of the communication system and may be not configured at all.

OpenScape clients should not rely on this information because it is not part of OpenScape configuration. It should be considered informational only.

Returns:
display name or null if not configured.

getDisplayNumber

java.lang.String getDisplayNumber()
Determine the display number used by the communication system.

The phone number displayed on the phone device of the communication partners to this connection is determined by this method. This depends on the configuration of the communication system and may be not configured at all.

OpenScape clients should not rely on this information because it is not part of OpenScape configuration. It should be considered informational only.

For the GUI this is the preferred representation of a number to display because it is consistent with the display on the phone devices itself. Only if this information is not available ComEndpoint should be taken for number display.

Returns:
display number or null if not configured.

getFailedReason

FailedReason getFailedReason()
Get reason for failed request.

Each request sent to a communication system might fail. This is indicated by an onFailed(ComConnection, ComEndpoint) event. The reason for this failure can be determined by this method.

Note:
A failed reason is only available while processing an onFailed(ComConnection, ComEndpoint) event. Therefore only while this processing a valid reason is returned.

Returns:
information about why the started action failed.

OpenScape
V3.2, Revision 044 20100322

Copyright (c) 2014 Unify, Germany
All rights reserved.

This software is the confidential and proprietary information of Unify, Germany