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

java.lang.Object
  net.java.sip.communicator.util.PropertyChangeNotifier
      net.java.sip.communicator.service.protocol.AbstractCallPeer<T,V>
          net.java.sip.communicator.service.protocol.media.MediaAwareCallPeer<T,U,V>

Type Parameters:

T - the peer extension class like for example CallSipImpl or CallJabberImpl

U - the media handler extension class like for example CallPeerMediaHandlerSipImpl or CallPeerMediaHandlerJabberImpl

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

All Implemented Interfaces:

EventListener, CsrcAudioLevelListener, SimpleAudioLevelListener, SrtpListener, CallPeer, CallPeerConferenceListener

Direct Known Subclasses:

CallPeerGTalkImpl, CallPeerJabberImpl, CallPeerSipImpl

public abstract class MediaAwareCallPeer<T extends MediaAwareCall<?,?,V>,U extends CallPeerMediaHandler<?>,V extends ProtocolProviderService>
extends AbstractCallPeer<T,V>
implements SrtpListener, CallPeerConferenceListener, CsrcAudioLevelListener, SimpleAudioLevelListener

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

Field Summary

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

callPeerConferenceListeners, callPeerListeners, callPeerSecurityListeners, NO_CONFERENCE_MEMBERS

Fields inherited from interface net.java.sip.communicator.service.neomedia.event.SimpleAudioLevelListener

MAX_LEVEL, MIN_LEVEL

Fields inherited from interface net.java.sip.communicator.service.protocol.CallPeer

CALL_DURATION_START_TIME_UNKNOWN, MUTE_PROPERTY_NAME

Constructor Summary

MediaAwareCallPeer(T owningCall)
Creates a new call peer with address peerAddress.

Method Summary

void	addConferenceMembersSoundLevelListener(ConferenceMembersSoundLevelListener listener) Adds a specific ConferenceMembersSoundLevelListener to the list of listeners interested in and notified about changes in conference members sound level.
void	addStreamSoundLevelListener(SoundLevelListener listener) Adds a specific SoundLevelListener to the list of listeners interested in and notified about changes in the sound level of the audio sent by the remote party.
void	addVideoPropertyChangeListener(PropertyChangeListener listener) Adds a specific PropertyChangeListener to the list of listeners which get notified when the properties (e.g.
void	audioLevelChanged(int newLevel) Notified by its very majesty the media service about changes in the audio level of the stream coming from this peer, this method generates the corresponding events and delivers them to the listeners that have registered here.
void	audioLevelsReceived(long[] audioLevels) Implements CsrcAudioLevelListener.audioLevelsReceived(long[]) so that we could deliver to ConferenceMembersSoundLevelListeners the events corresponding to the audio level changes that are being reported here.
void	callPeerAdded(CallPeerEvent evt) Does nothing.
void	callPeerRemoved(CallPeerEvent evt) Does nothing.
void	conferenceFocusChanged(CallPeerConferenceEvent evt) Dummy implementation of #conferenceFocusChanged(CallPeerConferenceEvent).
void	conferenceMemberAdded(CallPeerConferenceEvent conferenceEvent) Called when this peer becomes a mixer.
void	conferenceMemberRemoved(CallPeerConferenceEvent conferenceEvent) Called when this peer stops being a mixer.
T	getCall() Returns a reference to the call that this peer belongs to.
byte[]	getImage() The method returns an image representation of the call peer if one is available.
U	getMediaHandler() Returns a reference to the CallPeerMediaHandler used by this peer.
String	getPeerID() Returns a unique identifier representing this peer.
V	getProtocolProvider() Returns the protocol provider that this peer belongs to.
boolean	isLocalVideoStreaming() Determines whether we are currently streaming video toward whoever this CallPeerSipImpl represents.
boolean	isMute() Determines whether the audio stream (if any) being sent to this peer is mute.
void	logAndFail(String message, Throwable throwable) Logs message and cause and sets this peer's state to CallPeerState.FAILED
void	reevalLocalHoldStatus() Updates the state of this CallPeer to match the locally-on-hold status of our media handler.
void	reevalRemoteHoldStatus() Updates the state of this CallPeer to match the remotely-on-hold status of our media handler.
void	removeConferenceMembersSoundLevelListener(ConferenceMembersSoundLevelListener listener) Removes a specific ConferenceMembersSoundLevelListener of the list of listeners interested in and notified about changes in conference members sound level.
void	removeStreamSoundLevelListener(SoundLevelListener listener) Removes a specific SoundLevelListener of the list of listeners interested in and notified about changes in stream sound level related information.
void	removeVideoPropertyChangeListener(PropertyChangeListener listener) Removes a specific PropertyChangeListener from the list of listeners which get notified when the properties (e.g.
void	securityMessageReceived(String messageType, String i18nMessage, int severity) Sets the security message associated with a failure/warning or information coming from the encryption protocol.
void	securityTurnedOff(int sessionType) Sets the security status to OFF for this call peer.
void	securityTurnedOn(int sessionType, String cipher, SrtpControl sender) Sets the security status to ON for this call peer.
void	setCall(T call) Sets the call containing this peer.
void	setImage(byte[] image) Sets the byte array containing an image representation (photo or picture) of the call peer.
void	setLocalVideoAllowed(boolean allowed) Modifies the local media setup to reflect the requested setting for the streaming of the local video and then re-invites the peer represented by this class using a corresponding SDP description..
protected void	setMediaHandler(U mediaHandler) Sets a reference to the CallPeerMediaHandler used by this peer.
void	setMute(boolean newMuteValue) Sets the mute property for this call peer.
void	setPeerID(String peerID) Sets the String that serves as a unique identifier of this CallPeer.
void	setState(CallPeerState newState, String reason, int reasonCode) Overrides the parent set state method in order to make sure that we close our media handler whenever we enter a disconnected state.

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

addCallPeerConferenceListener, addCallPeerListener, addCallPeerSecurityListener, addConferenceMember, findConferenceMember, fireCallPeerChangeEvent, fireCallPeerChangeEvent, fireCallPeerChangeEvent, fireCallPeerConferenceEvent, fireCallPeerSecurityMessageEvent, fireCallPeerSecurityOffEvent, fireCallPeerSecurityOnEvent, getCallDurationStartTime, getCallInfoURL, getConferenceMemberCount, getConferenceMembers, getCurrentSecuritySettings, getState, isConferenceFocus, removeCallPeerConferenceListener, removeCallPeerListener, removeCallPeerSecurityListener, removeConferenceMember, setConferenceFocus, setState, setState, toString

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

addPropertyChangeListener, firePropertyChange, getPropertyChangeSource, removePropertyChangeListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.java.sip.communicator.service.protocol.CallPeer

addPropertyChangeListener, getAddress, getContact, getDisplayName, getURI, removePropertyChangeListener

Constructor Detail

MediaAwareCallPeer

public MediaAwareCallPeer(T owningCall)

Creates a new call peer with address peerAddress.

Parameters:

owningCall - the call that contains this call peer.

Method Detail

getImage

public byte[] getImage()

The method returns an image representation of the call peer if one is available.

Specified by:

getImage in interface CallPeer

Returns:

byte[] a byte array containing the image or null if no image is available.

setImage

public void setImage(byte[] image)

Sets the byte array containing an image representation (photo or picture) of the call peer.

Parameters:

image - a byte array containing the image

getPeerID

public String getPeerID()

Returns a unique identifier representing this peer.

Specified by:

getPeerID in interface CallPeer

Returns:

an identifier representing this call peer.

setPeerID

public void setPeerID(String peerID)

Sets the String that serves as a unique identifier of this CallPeer.

Parameters:

peerID - the ID of this call peer.

getCall

public T getCall()

Returns a reference to the call that this peer belongs to. Calls are created by underlying telephony protocol implementations.

Specified by:

getCall in interface CallPeer

Specified by:

getCall in class AbstractCallPeer<T extends MediaAwareCall<?,?,V>,V extends ProtocolProviderService>

Returns:

a reference to the call containing this peer.

setCall

public void setCall(T call)

Sets the call containing this peer.

Parameters:

call - the call that this call peer is participating in.

getProtocolProvider

public V getProtocolProvider()

Returns the protocol provider that this peer belongs to.

Specified by:

getProtocolProvider in interface CallPeer

Specified by:

getProtocolProvider in class AbstractCallPeer<T extends MediaAwareCall<?,?,V>,V extends ProtocolProviderService>

Returns:

a reference to the ProtocolProviderService that this peer belongs to.

isMute

public boolean isMute()

Determines whether the audio stream (if any) being sent to this peer is mute.

Specified by:

isMute in interface CallPeer

Overrides:

isMute in class AbstractCallPeer<T extends MediaAwareCall<?,?,V>,V extends ProtocolProviderService>

Returns:

true if an audio stream is being sent to this peer and it is currently mute; false, otherwise

reevalRemoteHoldStatus

public void reevalRemoteHoldStatus()

Updates the state of this CallPeer to match the remotely-on-hold status of our media handler.

reevalLocalHoldStatus

public void reevalLocalHoldStatus()

Updates the state of this CallPeer to match the locally-on-hold status of our media handler.

setMute

public void setMute(boolean newMuteValue)

Sets the mute property for this call peer.

Overrides:

setMute in class AbstractCallPeer<T extends MediaAwareCall<?,?,V>,V extends ProtocolProviderService>

Parameters:

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

logAndFail

public void logAndFail(String message,
                       Throwable throwable)

Logs message and cause and sets this peer's state to CallPeerState.FAILED

Parameters:

message - a message to log and display to the user.

throwable - the exception that cause the error we are logging

setLocalVideoAllowed

public void setLocalVideoAllowed(boolean allowed)
                          throws OperationFailedException

Modifies the local media setup to reflect the requested setting for the streaming of the local video and then re-invites the peer represented by this class using a corresponding SDP description..

Parameters:

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

Throws:

OperationFailedException - if video initialization fails.

isLocalVideoStreaming

public boolean isLocalVideoStreaming()

Determines whether we are currently streaming video toward whoever this CallPeerSipImpl represents.

Returns:

true if we are currently streaming video toward this CallPeer and false otherwise.

addVideoPropertyChangeListener

public void addVideoPropertyChangeListener(PropertyChangeListener listener)

Adds a specific PropertyChangeListener to the list of listeners which get notified when the properties (e.g. LOCAL_VIDEO_STREAMING) associated with this CallPeer change their values.

Parameters:

listener - the PropertyChangeListener to be notified when the properties associated with the specified Call change their values

removeVideoPropertyChangeListener

public void removeVideoPropertyChangeListener(PropertyChangeListener listener)

Removes a specific PropertyChangeListener from the list of listeners which get notified when the properties (e.g. LOCAL_VIDEO_STREAMING) associated with this CallPeer change their values.

Parameters:

listener - the PropertyChangeListener to no longer be notified when the properties associated with the specified Call change their values

setState

public void setState(CallPeerState newState,
                     String reason,
                     int reasonCode)

Overrides the parent set state method in order to make sure that we close our media handler whenever we enter a disconnected state.

Overrides:

setState in class AbstractCallPeer<T extends MediaAwareCall<?,?,V>,V extends ProtocolProviderService>

Parameters:

newState - the CallPeerState that we are about to enter and that we pass to our predecessor.

reason - a reason phrase explaining the state (e.g. if newState indicates a failure) and that we pass to our predecessor.

reasonCode - the code for the reason of the state change.

addStreamSoundLevelListener

public void addStreamSoundLevelListener(SoundLevelListener listener)

Adds a specific SoundLevelListener to the list of listeners interested in and notified about changes in the sound level of the audio sent by the remote party. When the first listener is being registered the method also registers its single listener with the media handler so that it would receive level change events and delegate them to the listeners that have registered with us.

Specified by:

addStreamSoundLevelListener in interface CallPeer

Parameters:

listener - the SoundLevelListener to add

removeStreamSoundLevelListener

public void removeStreamSoundLevelListener(SoundLevelListener listener)

Removes a specific SoundLevelListener of the list of listeners interested in and notified about changes in stream sound level related information.

Specified by:

removeStreamSoundLevelListener in interface CallPeer

Parameters:

listener - the SoundLevelListener to remove

addConferenceMembersSoundLevelListener

public void addConferenceMembersSoundLevelListener(ConferenceMembersSoundLevelListener listener)

Adds a specific ConferenceMembersSoundLevelListener to the list of listeners interested in and notified about changes in conference members sound level.

Specified by:

addConferenceMembersSoundLevelListener in interface CallPeer

Parameters:

listener - the ConferenceMembersSoundLevelListener to add

removeConferenceMembersSoundLevelListener

public void removeConferenceMembersSoundLevelListener(ConferenceMembersSoundLevelListener listener)

Removes a specific ConferenceMembersSoundLevelListener of the list of listeners interested in and notified about changes in conference members sound level.

Specified by:

removeConferenceMembersSoundLevelListener in interface CallPeer

Parameters:

listener - the ConferenceMembersSoundLevelListener to remove

audioLevelsReceived

public void audioLevelsReceived(long[] audioLevels)

Implements CsrcAudioLevelListener.audioLevelsReceived(long[]) so that we could deliver to ConferenceMembersSoundLevelListeners the events corresponding to the audio level changes that are being reported here.

Specified by:

audioLevelsReceived in interface CsrcAudioLevelListener

Parameters:

audioLevels - the levels that we need to dispatch to all registered ConferenceMemberSoundLevelListeners.

callPeerAdded

public void callPeerAdded(CallPeerEvent evt)

Does nothing.

Parameters:

evt - the event.

callPeerRemoved

public void callPeerRemoved(CallPeerEvent evt)

Does nothing.

Parameters:

evt - the event.

securityTurnedOn

public void securityTurnedOn(int sessionType,
                             String cipher,
                             SrtpControl sender)

Sets the security status to ON for this call peer.

Specified by:

securityTurnedOn in interface SrtpListener

Parameters:

sessionType - the type of the call session - audio or video.

cipher - the cipher

sender - the security controller that caused the event

securityTurnedOff

public void securityTurnedOff(int sessionType)

Sets the security status to OFF for this call peer.

Specified by:

securityTurnedOff in interface SrtpListener

Parameters:

sessionType - the type of the call session - audio or video.

securityMessageReceived

public void securityMessageReceived(String messageType,
                                    String i18nMessage,
                                    int severity)

Sets the security message associated with a failure/warning or information coming from the encryption protocol.

Specified by:

securityMessageReceived in interface SrtpListener

Parameters:

messageType - the type of the message.

i18nMessage - the message

severity - severity level

conferenceFocusChanged

public void conferenceFocusChanged(CallPeerConferenceEvent evt)

Dummy implementation of #conferenceFocusChanged(CallPeerConferenceEvent).

Specified by:

conferenceFocusChanged in interface CallPeerConferenceListener

Parameters:

evt - ignored

conferenceMemberAdded

public void conferenceMemberAdded(CallPeerConferenceEvent conferenceEvent)

Called when this peer becomes a mixer. The method add removes this class as the stream audio level listener for the media coming from this peer because the levels it delivers no longer represent the level of a particular member. The method also adds this class as a member (CSRC) audio level listener.

Specified by:

conferenceMemberAdded in interface CallPeerConferenceListener

Parameters:

conferenceEvent - the event containing information (that we don't really use) on the newly add member.

conferenceMemberRemoved

public void conferenceMemberRemoved(CallPeerConferenceEvent conferenceEvent)

Called when this peer stops being a mixer. The method add removes this class as the stream audio level listener for the media coming from this peer because the levels it delivers no longer represent the level of a particular member. The method also adds this class as a member (CSRC) audio level listener.

Specified by:

conferenceMemberRemoved in interface CallPeerConferenceListener

Parameters:

conferenceEvent - the event containing information (that we don't really use) on the freshly removed member.

audioLevelChanged

public void audioLevelChanged(int newLevel)

Notified by its very majesty the media service about changes in the audio level of the stream coming from this peer, this method generates the corresponding events and delivers them to the listeners that have registered here.

Specified by:

audioLevelChanged in interface SimpleAudioLevelListener

Parameters:

newLevel - the new audio level of the local user.

getMediaHandler

public U getMediaHandler()

Returns a reference to the CallPeerMediaHandler used by this peer. The media handler class handles all media management for a single CallPeer. This includes initializing and configuring streams, generating SDP, handling ICE, etc. One instance of CallPeer always corresponds to exactly one instance of CallPeerMediaHandler and both classes are only separated for reasons of readability.

Returns:

a reference to the CallPeerMediaHandler instance that this peer uses for media related tips and tricks.

setMediaHandler

protected void setMediaHandler(U mediaHandler)

Sets a reference to the CallPeerMediaHandler used by this peer. The media handler class handles all media management for a single CallPeer. This includes initializing and configuring streams, generating SDP, handling ICE, etc. One instance of CallPeer always corresponds to exactly one instance of CallPeerMediaHandler and both classes are only separated for reasons of readability.

Parameters:

mediaHandler - a reference to the CallPeerMediaHandler instance that this peer uses for media related tips and tricks.