net.java.sip.communicator.service.protocol.media
Class MediaAwareCall<T extends MediaAwareCallPeer<?,?,V>,U extends OperationSetBasicTelephony<V>,V extends ProtocolProviderService>

java.lang.Object
  net.java.sip.communicator.service.protocol.Call
      net.java.sip.communicator.service.protocol.AbstractCall<T,V>
          net.java.sip.communicator.service.protocol.media.MediaAwareCall<T,U,V>

Type Parameters:

T - the peer extension class like for example CallPeerSipImpl or CallPeerJabberImpl

U - the provider extension class like for example OperationSetBasicTelephonySipImpl or OperationSetBasicTelephonySipImpl

V - the provider extension class like for example ProtocolProviderServiceSipImpl or ProtocolProviderServiceJabberImpl

All Implemented Interfaces:

PropertyChangeListener, EventListener, CallChangeListener, CallGroupListener, CallPeerListener

Direct Known Subclasses:

CallGTalkImpl, CallJabberImpl, CallSipImpl

public abstract class MediaAwareCall<T extends MediaAwareCallPeer<?,?,V>,U extends OperationSetBasicTelephony<V>,V extends ProtocolProviderService>
extends AbstractCall<T,V>
implements CallPeerListener, CallChangeListener, PropertyChangeListener

A utility class implementing media control code shared between current telephony implementations. This class is only meant for use by protocol implementations and should/could not be accessed by bundles that are simply using the telephony functionalities.

Author:

Emil Ivov, Lyubomir Marinov

Field Summary

static String	DEFAULT_DEVICE The name of the property of MediaAwareCall the value of which corresponds to the value returned by getDefaultDevice(MediaType).
protected boolean	localVideoAllowed Our video streaming policy.
protected MediaUseCase	mediaUseCase Device used in call will be chosen according to MediaUseCase.
protected U	parentOpSet The OperationSetBasicTelephony implementation which created us.

Fields inherited from class net.java.sip.communicator.service.protocol.AbstractCall

callGroup

Constructor Summary

protected

MediaAwareCall(U parentOpSet) Crates a Call instance belonging to parentOpSet.

Method Summary

protected void	addCallPeer(T callPeer) Adds callPeer to the list of peers in this call.
void	addLocalUserSoundLevelListener(SoundLevelListener l) Adds a specific SoundLevelListener to the list of listeners interested in and notified about changes in local sound level related information.
void	addPropertyChangeListener(PropertyChangeListener listener) Adds a PropertyChangeListener to be notified about changes in the values of the properties of this instance.
void	addVideoPropertyChangeListener(PropertyChangeListener listener) Registers a listener with all CallPeer currently participating with the call so that it would be notified of changes in video related properties (e.g.
void	callAdded(CallGroupEvent evt) Notifies this instance that a specific Call has been added to a CallGroup.
void	callPeerAdded(CallPeerEvent evt) Indicates that a new call peer has joined the source call.
void	callPeerRemoved(CallPeerEvent evt) Indicates that a call peer has left the source call.
void	callRemoved(CallGroupEvent evt) Notified when a call is removed from a CallGroup.
void	callStateChanged(CallChangeEvent evt) Indicates that a change has occurred in the state of the source call.
Recorder	createRecorder() Creates a new Recorder which is to record this Call (into a file which is to be specified when starting the returned Recorder).
MediaDevice	getDefaultDevice(MediaType mediaType) Gets a MediaDevice which is capable of capture and/or playback of media of the specified MediaType, is the default choice of the user for a MediaDevice with the specified MediaType and is appropriate for the current state of this Call.
MediaUseCase	getMediaUseCase() Get the media use case.
U	getParentOperationSet() Returns a reference to the OperationSetBasicTelephony implementation instance that created this call.
RTPTranslator	getRTPTranslator(MediaType mediaType) Gets the RTPTranslator which forwards RTP and RTCP traffic between the CallPeers of this Call when the local peer represented by this Call is acting as a conference focus i.e.
boolean	isConferenceFocus() Gets the indicator which determines whether the local peer represented by this Call is acting as a conference focus and thus may need to send the corresponding parameters in its outgoing signaling.
boolean	isLocalVideoAllowed(MediaUseCase useCase) Determines whether the streaming of local video in this Call is currently allowed.
boolean	isLocalVideoStreaming() Determines whether we are currently streaming video toward at least one of the peers in this call.
boolean	isMute() Determines whether this call is mute.
void	peerAddressChanged(CallPeerChangeEvent evt) Dummy implementation of a method (inherited from CallPeerListener) that we don't need.
void	peerDisplayNameChanged(CallPeerChangeEvent evt) Dummy implementation of a method (inherited from CallPeerListener) that we don't need.
void	peerImageChanged(CallPeerChangeEvent evt) Dummy implementation of a method (inherited from CallPeerListener) that we don't need.
void	peerStateChanged(CallPeerChangeEvent evt) Verifies whether the call peer has entered a state.
void	peerTransportAddressChanged(CallPeerChangeEvent evt) Dummy implementation of a method (inherited from CallPeerListener) that we don't need.
void	propertyChange(PropertyChangeEvent event) Notifies this instance about a change of the value of a specific property from a specific old value to a specific new value.
void	removeLocalUserSoundLevelListener(SoundLevelListener l) Removes a specific SoundLevelListener from the list of listeners interested in and notified about changes in local sound level related information.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes a PropertyChangeListener to no longer be notified about changes in the values of the properties of this instance.
void	removeVideoPropertyChangeListener(PropertyChangeListener listener) Removes listener from all CallPeers currently participating with the call so that it won't receive further notifications on changes in video related properties (e.g.
void	setAudioDevice(MediaDevice dev) Set the MediaDevice used for the audio.
protected void	setCallState(CallState newState, CallPeerChangeEvent cause) Sets the state of this Call and fires a new CallChangeEvent notifying the registered CallChangeListeners about the change of the state.
void	setConferenceFocus(boolean conferenceFocus) Sets the indicator which determines whether the local peer represented by this Call is acting as a conference focus (and thus may, for example, need to send the corresponding parameters in its outgoing signaling).
void	setLocalVideoAllowed(boolean allowed, MediaUseCase useCase) Modifies the local media setup of all peers in the call to reflect the requested setting for the streaming of the local video and then passes the setting to the participating MediaAwareCallPeer instances.
void	setMute(boolean mute) Sets the mute property for this call.
void	setVideoDevice(MediaDevice dev) Set the MediaDevice used for the video.

Methods inherited from class net.java.sip.communicator.service.protocol.AbstractCall

getCallGroup, getCallPeerCount, getCallPeers, getCallPeersVector, getCrossProtocolCallPeerCount, getCrossProtocolCallPeers, getCrossProtocolCallPeersVector, getProtocolProvider, setCallGroup

Methods inherited from class net.java.sip.communicator.service.protocol.Call

addCallChangeListener, equals, fireCallChangeEvent, fireCallChangeEvent, fireCallPeerEvent, getCallID, getCallState, hashCode, isDefaultEncrypted, isSipZrtpAttribute, removeCallChangeListener, setCallState, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_DEVICE

public static final String DEFAULT_DEVICE

The name of the property of MediaAwareCall the value of which corresponds to the value returned by getDefaultDevice(MediaType). The oldValue and the newValue of the fired PropertyChangeEvent are not to be relied on and instead a call to getDefaultDevice is to be performed to retrieve the new value.

See Also:

Constant Field Values

localVideoAllowed

protected boolean localVideoAllowed

Our video streaming policy.

parentOpSet

protected final U extends OperationSetBasicTelephony<V> parentOpSet

The OperationSetBasicTelephony implementation which created us.

mediaUseCase

protected MediaUseCase mediaUseCase

Device used in call will be chosen according to MediaUseCase.

Constructor Detail

MediaAwareCall

protected MediaAwareCall(U parentOpSet)

Crates a Call instance belonging to parentOpSet.

Parameters:

parentOpSet - a reference to the operation set that's creating us and that we would be able to use for even dispatching.

Method Detail

addCallPeer

protected void addCallPeer(T callPeer)

Adds callPeer to the list of peers in this call. If the call peer is already included in the call, the method has no effect.

Parameters:

callPeer - the new CallPeer

peerImageChanged

public void peerImageChanged(CallPeerChangeEvent evt)

Dummy implementation of a method (inherited from CallPeerListener) that we don't need.

Specified by:

peerImageChanged in interface CallPeerListener

Parameters:

evt - unused.

peerAddressChanged

public void peerAddressChanged(CallPeerChangeEvent evt)

Dummy implementation of a method (inherited from CallPeerListener) that we don't need.

Specified by:

peerAddressChanged in interface CallPeerListener

Parameters:

evt - unused.

peerTransportAddressChanged

public void peerTransportAddressChanged(CallPeerChangeEvent evt)

Dummy implementation of a method (inherited from CallPeerListener) that we don't need.

Specified by:

peerTransportAddressChanged in interface CallPeerListener

Parameters:

evt - unused.

peerDisplayNameChanged

public void peerDisplayNameChanged(CallPeerChangeEvent evt)

Dummy implementation of a method (inherited from CallPeerListener) that we don't need.

Specified by:

peerDisplayNameChanged in interface CallPeerListener

Parameters:

evt - unused.

peerStateChanged

public void peerStateChanged(CallPeerChangeEvent evt)

Verifies whether the call peer has entered a state.

Specified by:

peerStateChanged in interface CallPeerListener

Parameters:

evt - The CallPeerChangeEvent instance containing the source event as well as its previous and its new status.

getParentOperationSet

public U getParentOperationSet()

Returns a reference to the OperationSetBasicTelephony implementation instance that created this call.

Returns:

a reference to the OperationSetBasicTelephony instance that created this call.

getRTPTranslator

public RTPTranslator getRTPTranslator(MediaType mediaType)

Gets the RTPTranslator which forwards RTP and RTCP traffic between the CallPeers of this Call when the local peer represented by this Call is acting as a conference focus i.e. conferenceFocus is true.

Parameters:

mediaType - the MediaType of the MediaStream which RTP and RTCP traffic is to be forwarded between

Returns:

the RTPTranslator which forwards RTP and RTCP traffic between the CallPeers of this Call when the local peer represented by this Call is acting as a conference focus i.e. conferenceFocus is true

isConferenceFocus

public boolean isConferenceFocus()

Gets the indicator which determines whether the local peer represented by this Call is acting as a conference focus and thus may need to send the corresponding parameters in its outgoing signaling.

Specified by:

isConferenceFocus in class Call

Returns:

true if the local peer represented by this Call is acting as a conference focus; otherwise, false

setConferenceFocus

public void setConferenceFocus(boolean conferenceFocus)

Sets the indicator which determines whether the local peer represented by this Call is acting as a conference focus (and thus may, for example, need to send the corresponding parameters in its outgoing signaling).

Parameters:

conferenceFocus - true if the local peer represented by this Call is to act as a conference focus; otherwise, false

getDefaultDevice

public MediaDevice getDefaultDevice(MediaType mediaType)

Gets a MediaDevice which is capable of capture and/or playback of media of the specified MediaType, is the default choice of the user for a MediaDevice with the specified MediaType and is appropriate for the current state of this Call.

For example, when the local peer represented by this Call instance is acting as a conference focus, the audio device must be a mixer.

Parameters:

mediaType - the MediaType in which the retrieved MediaDevice is to capture and/or play back media

Returns:

a MediaDevice which is capable of capture and/or playback of media of the specified mediaType, is the default choice of the user for a MediaDevice with the specified mediaType and is appropriate for the current state of this Call

addLocalUserSoundLevelListener

public void addLocalUserSoundLevelListener(SoundLevelListener l)

Adds a specific SoundLevelListener to the list of listeners interested in and notified about changes in local sound level related information. When the first listener is being registered the method also registers its single listener with the call peer media handlers so that it would receive level change events and delegate them to the listeners that have registered with us.

Specified by:

addLocalUserSoundLevelListener in class Call

Parameters:

l - the SoundLevelListener to add

removeLocalUserSoundLevelListener

public void removeLocalUserSoundLevelListener(SoundLevelListener l)

Removes a specific SoundLevelListener from the list of listeners interested in and notified about changes in local sound level related information. If l is the last listener that we had here we are also going to unregister our own level event delegate in order to stop level calculations.

Specified by:

removeLocalUserSoundLevelListener in class Call

Parameters:

l - the SoundLevelListener to remove

isMute

public boolean isMute()

Determines whether this call is mute.

Returns:

true if an audio streams being sent to the call peers are currently muted; false, otherwise

setMute

public void setMute(boolean mute)

Sets the mute property for this call.

Parameters:

mute - the new value of the mute property for this call

setLocalVideoAllowed

public void setLocalVideoAllowed(boolean allowed,
                                 MediaUseCase useCase)
                          throws OperationFailedException

Modifies the local media setup of all peers in the call to reflect the requested setting for the streaming of the local video and then passes the setting to the participating MediaAwareCallPeer instances.

Parameters:

allowed - true if local video transmission is allowed and false otherwise.

useCase - the use case of the video (i.e video call or desktop streaming/sharing session)

Throws:

OperationFailedException - if video initialization fails.

getMediaUseCase

public MediaUseCase getMediaUseCase()

Get the media use case.

Returns:

media use case

isLocalVideoAllowed

public boolean isLocalVideoAllowed(MediaUseCase useCase)

Determines whether the streaming of local video in this Call is currently allowed. The setting does not reflect the availability of actual video capture devices, it just expresses the local policy (or desire of the user) to have the local video streamed in the case the system is actually able to do so.

Parameters:

useCase - the use case of the video (i.e video call or desktop streaming/sharing session)

Returns:

true if the streaming of local video for this Call is allowed; otherwise, false

isLocalVideoStreaming

public boolean isLocalVideoStreaming()

Determines whether we are currently streaming video toward at least one of the peers in this call.

Returns:

true if we are currently streaming video toward at least one of the peers in this call and false otherwise.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Adds a PropertyChangeListener to be notified about changes in the values of the properties of this instance.

Parameters:

listener - the PropertyChangeListener to be notified about changes in the values of the properties of this instance

addVideoPropertyChangeListener

public void addVideoPropertyChangeListener(PropertyChangeListener listener)

Registers a listener with all CallPeer currently participating with the call so that it would be notified of changes in video related properties (e.g. LOCAL_VIDEO_STREAMING).

Parameters:

listener - the PropertyChangeListener to be notified when the properties associated with member CallPeers change their values.

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Removes a PropertyChangeListener to no longer be notified about changes in the values of the properties of this instance.

Parameters:

listener - the PropertyChangeListener to no longer be notified about changes in the values of the properties of this instance

removeVideoPropertyChangeListener

public void removeVideoPropertyChangeListener(PropertyChangeListener listener)

Removes listener from all CallPeers currently participating with the call so that it won't receive further notifications on changes in video related properties (e.g. LOCAL_VIDEO_STREAMING).

Parameters:

listener - the PropertyChangeListener to unregister from member CallPeers change their values.

createRecorder

public Recorder createRecorder()
                        throws OperationFailedException

Creates a new Recorder which is to record this Call (into a file which is to be specified when starting the returned Recorder).

Returns:

a new Recorder which is to record this Call (into a file which is to be specified when starting the returned Recorder)

Throws:

OperationFailedException - if anything goes wrong while creating the new Recorder for this Call

setVideoDevice

public void setVideoDevice(MediaDevice dev)

Set the MediaDevice used for the video.

Parameters:

dev - video MediaDevice

setAudioDevice

public void setAudioDevice(MediaDevice dev)

Set the MediaDevice used for the audio.

Parameters:

dev - audio MediaDevice

callPeerAdded

public void callPeerAdded(CallPeerEvent evt)

Indicates that a new call peer has joined the source call.

Specified by:

callPeerAdded in interface CallChangeListener

Parameters:

evt - the CallPeerEvent containing the source call and call peer.

callPeerRemoved

public void callPeerRemoved(CallPeerEvent evt)

Indicates that a call peer has left the source call.

Specified by:

callPeerRemoved in interface CallChangeListener

Parameters:

evt - the CallPeerEvent containing the source call and call peer.

callStateChanged

public void callStateChanged(CallChangeEvent evt)

Indicates that a change has occurred in the state of the source call.

Specified by:

callStateChanged in interface CallChangeListener

Parameters:

evt - the CallChangeEvent instance containing the source calls and its old and new state.

callAdded

public void callAdded(CallGroupEvent evt)

Notifies this instance that a specific Call has been added to a CallGroup.

Specified by:

callAdded in interface CallGroupListener

Parameters:

evt - a CallGroupEvent which specifies the Call which has been added to a CallGroup

See Also:

CallGroupListener.callAdded(CallGroupEvent)

callRemoved

public void callRemoved(CallGroupEvent evt)

Notified when a call is removed from a CallGroup.

Specified by:

callRemoved in interface CallGroupListener

Parameters:

evt - event

setCallState

protected void setCallState(CallState newState,
                            CallPeerChangeEvent cause)

Sets the state of this Call and fires a new CallChangeEvent notifying the registered CallChangeListeners about the change of the state.

Overrides:

setCallState in class Call

Parameters:

newState - the CallState into which this Call is to enter

cause - the CallPeerChangeEvent which is the cause for the request to have this Call enter the specified CallState

See Also:

Call.setCallState(CallState, CallPeerChangeEvent)

propertyChange

public void propertyChange(PropertyChangeEvent event)

Notifies this instance about a change of the value of a specific property from a specific old value to a specific new value. At the time of this writing, MediaAwareCall listeners to the property value changes of MediaService in order to track the changes of the default MediaDevice.

Specified by:

propertyChange in interface PropertyChangeListener

Parameters:

event - a PropertyChangeEvent which specifies the name of the property which has its value changed and the old and new values