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.util.DataObject

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:

java.beans.PropertyChangeListener, java.util.EventListener, CallPeerListener, DTMFListener

Direct Known Subclasses:

AbstractCallJabberGTalkImpl, CallSipImpl

public abstract class MediaAwareCall<T extends MediaAwareCallPeer<?,?,V>,U extends OperationSetBasicTelephony<V>,V extends ProtocolProviderService>
extends AbstractCall<T,V>
implements CallPeerListener, java.beans.PropertyChangeListener, DTMFListener

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

Fields

Modifier and Type	Field and Description
static java.lang.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 org.jitsi.service.neomedia.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.Call

CONFERENCE, CONFERENCE_FOCUS, useTranslator

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MediaAwareCall(U parentOpSet) Crates a Call instance belonging to parentOpSet.

Method Summary

Modifier and Type	Method and Description
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	addVideoPropertyChangeListener(java.beans.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.
protected void	conferenceFocusChanged(boolean oldValue, boolean newValue) Notifies this instance that the value of its property Call.CONFERENCE_FOCUS has changed from a specific old value to a specific new value.
protected CallConference	createConference() Creates a new CallConference instance which is to represent the telephony conference-related state of this Call.
org.jitsi.service.neomedia.recording.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).
protected void	firePropertyChange(java.lang.String property, java.lang.Object oldValue, java.lang.Object newValue) Fires a new PropertyChangeEvent to the PropertyChangeListeners registered with this Call in order to notify about a change in the value of a specific property which had its old value modified to a specific new value.
MediaAwareCallConference	getConference() Gets the telephony conference-related state of this Call.
org.jitsi.service.neomedia.device.MediaDevice	getDefaultDevice(org.jitsi.service.neomedia.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.
org.jitsi.service.neomedia.MediaUseCase	getMediaUseCase() Get the media use case.
U	getParentOperationSet() Returns a reference to the OperationSetBasicTelephony implementation instance that created this call.
org.jitsi.service.neomedia.RTPTranslator	getRTPTranslator(org.jitsi.service.neomedia.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.
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(org.jitsi.service.neomedia.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(java.beans.PropertyChangeEvent ev) 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	removeVideoPropertyChangeListener(java.beans.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(org.jitsi.service.neomedia.device.MediaDevice audioDevice) Sets the MediaDevice to be used by this Call for audio capture and/or playback.
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	setConference(CallConference conference) Sets the telephony conference-related state of this Call.
void	setLocalVideoAllowed(boolean allowed, org.jitsi.service.neomedia.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(org.jitsi.service.neomedia.device.MediaDevice videoDevice, org.jitsi.service.neomedia.MediaUseCase useCase) Sets the MediaDevice to be used by this Call for video capture and/or playback and the use case of the video streaming in this MediaAwareCall.
void	toneReceived(DTMFReceivedEvent evt) Called when a new incoming DTMFTone has been received.

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

addPropertyChangeListener, doAddCallPeer, doRemoveCallPeer, getCallPeerCount, getCallPeerList, getCallPeers, getProtocolProvider, removePropertyChangeListener

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

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

Methods inherited from class net.java.sip.communicator.util.DataObject

getData, setData

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_DEVICE

public static final java.lang.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 org.jitsi.service.neomedia.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 org.jitsi.service.neomedia.RTPTranslator getRTPTranslator(org.jitsi.service.neomedia.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.

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

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

getDefaultDevice

public org.jitsi.service.neomedia.device.MediaDevice getDefaultDevice(org.jitsi.service.neomedia.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,
                                 org.jitsi.service.neomedia.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 org.jitsi.service.neomedia.MediaUseCase getMediaUseCase()

Get the media use case.

Returns:

media use case

isLocalVideoAllowed

public boolean isLocalVideoAllowed(org.jitsi.service.neomedia.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.

addVideoPropertyChangeListener

public void addVideoPropertyChangeListener(java.beans.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.

removeVideoPropertyChangeListener

public void removeVideoPropertyChangeListener(java.beans.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 org.jitsi.service.neomedia.recording.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

setAudioDevice

public void setAudioDevice(org.jitsi.service.neomedia.device.MediaDevice audioDevice)

Sets the MediaDevice to be used by this Call for audio capture and/or playback.

Parameters:

audioDevice - the MediaDevice to be used by this Call for audio capture and/or playback

setVideoDevice

public void setVideoDevice(org.jitsi.service.neomedia.device.MediaDevice videoDevice,
                           org.jitsi.service.neomedia.MediaUseCase useCase)

Sets the MediaDevice to be used by this Call for video capture and/or playback and the use case of the video streaming in this MediaAwareCall.

Parameters:

videoDevice - the MediaDevice to be used by this Call for video capture and/or playback

useCase - the use case of the video streaming to be set on this MediaAwareCall such as webcam capture or desktop sharing/streaming

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(java.beans.PropertyChangeEvent ev)

Notifies this instance about a change of the value of a specific property from a specific old value to a specific new value.

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

Parameters:

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

conferenceFocusChanged

protected void conferenceFocusChanged(boolean oldValue,
                                      boolean newValue)

Notifies this instance that the value of its property Call.CONFERENCE_FOCUS has changed from a specific old value to a specific new value. Fires a PropertyChangeEvent to the registered PropertyChangeListeners. Protocol implementations which extend MediaAwareCall will likely want to override in order to add notifying the associated CallPeers about the change of the property value (e.g. SIP will want to include the "isfocus" parameter in the Contact header while the local peer is acting as a conference focus.)

Parameters:

oldValue - the value of the property CONFERENCE_FOCUS before the change

newValue - the value of the property CONFERENCE_FOCUS after the change

createConference

protected CallConference createConference()

Creates a new CallConference instance which is to represent the telephony conference-related state of this Call. Allows extenders to override and customize the runtime type of the CallConference to used by this Call. Creates a new MediaAwareCallConference to represent the media-specific information associated with the telephony conference-related state of this MediaAwareCall.

Overrides:

createConference in class Call

Returns:

a new CallConference instance which is to represent the telephony conference-related state of this Call

getConference

public MediaAwareCallConference getConference()

Gets the telephony conference-related state of this Call. Since a non-conference Call may be converted into a conference Call at any time, every Call instance maintains a CallConference instance regardless of whether the Call in question is participating in a telephony conference. Makes sure that the telephony conference-related state of this MediaAwareCall is represented by a MediaAwareCallConference instance.

Overrides:

getConference in class Call

Returns:

a CallConference instance which represents the telephony conference-related state of this Call.

firePropertyChange

protected void firePropertyChange(java.lang.String property,
                                  java.lang.Object oldValue,
                                  java.lang.Object newValue)

Fires a new PropertyChangeEvent to the PropertyChangeListeners registered with this Call in order to notify about a change in the value of a specific property which had its old value modified to a specific new value. Delegates to AbstractCall.propertyChangeSupport. Listens to the changes in the values of the properties of this Call.

Overrides:

firePropertyChange in class AbstractCall<T extends MediaAwareCallPeer<?,?,V>,V extends ProtocolProviderService>

Parameters:

property - the name of the property of this Call which had its value changed

oldValue - the value of the property with the specified name before the change

newValue - the value of the property with the specified name after the change

setConference

public void setConference(CallConference conference)

Sets the telephony conference-related state of this Call. If the invocation modifies this instance, it adds this Call to the newly set CallConference and fires a PropertyChangeEvent for the CONFERENCE property to its listeners. Makes sure that the telephony conference-related state of this MediaAwareCall is represented by a MediaAwareCallConference instance.

Overrides:

setConference in class Call

Parameters:

conference - the CallConference instance to represent the telephony conference-related state of this Call

toneReceived

public void toneReceived(DTMFReceivedEvent evt)

Called when a new incoming DTMFTone has been received. Implements DTMFListener.toneReceived(net.java.sip.communicator.service.protocol.event.DTMFReceivedEvent)

Specified by:

toneReceived in interface DTMFListener

Parameters:

evt - the DTMFReceivedEvent containing the newly received tone.