net.java.sip.communicator.service.media
Interface CallSession

All Known Implementing Classes:

CallSessionImpl

public interface CallSession

A CallSession contains parameters associated with a particular Call such as ports used for transmitting and sending media (audio video), a reference to the call itself and others. Call session instances are created through the openCallSession(Call) method of the MediaService.

One CallSession pertains to a single Call instance and a single Call may only be associated one CallSession instance.

A call session also allows signaling protocols to generate SDP offers and construct sdp answers.

Author:

Emil Ivov, Lubomir Marinov, Emanuel Onica

Field Summary

static String	LOCAL_VIDEO_STREAMING The property which indicates whether a CallSession is currently streaming the local video (to a remote destination).
static byte	ON_HOLD_REMOTELY The media flag which signals that the other side of the call has put this on hold.
static byte	RECEIVE_AUDIO The media flag which signals that audio streams being received are to be handled (e.g.
static byte	RECEIVE_VIDEO The media flag which signals that video streams being received are to be handled (e.g.

Method Summary

void	addPropertyChangeListener(PropertyChangeListener listener) Adds a specific PropertyChangeListener to the list of listeners which get notified when the properties (e.g.
void	addVideoListener(VideoListener listener) Adds a specific VideoListener to this CallSession in order to receive notifications when visual/video Components are being added and removed.
Component	createLocalVisualComponent(VideoListener listener) Creates a visual Component which represents the local video streamed by this CallSession (to remote destinations).
String	createSdpDescriptionForHold(String peerSdpDescription, boolean onHold) The method is meant for use by protocol service implementations when willing to send an in-dialog invitation to a remote callee to put her on/off hold or to send an answer to an offer to be put on/off hold.
String	createSdpOffer() The method is meant for use by protocol service implementations when willing to send an invitation to a remote callee.
String	createSdpOffer(InetAddress intendedDestination) The method is meant for use by protocol service implementations when willing to send an invitation to a remote callee.
String	createSdpOffer(String peerSdpDescription) Creates a SDP description including the current state of the local media setup and in accord with a specific SDP description of a call peer (who is to be offered the created SDP description, for example, as part of a re-INVITE).
void	disposeLocalVisualComponent(Component component) Disposes of a specific visual Component representing local video which has been created by this instance with createLocalVisualComponent(VideoListener).
int	getAudioPort() Returns the port that we are using for receiving audio data in this CallSession.
Call	getCall() Gets the call associated with this session
URL	getCallInfoURL() Returns a URL pointing to a location with call control information for this call or null if no such URL is available.
int	getSdpOfferMediaFlags(String sdpOffer) Determines whether a specific SDP description String offers this party to be put on hold and which media types are offered to be received.
boolean	getSecureCommunicationStatus() Gets the default secure/unsecure communication status for the supported call sessions.
SessionCreatorCallback	getSessionCreatorCallback() Returns the SessionCreatorCallback which listens for security events.
int	getVideoPort() Returns the port that we are using for receiving video data in this CallSession.
Component[]	getVisualComponents() Gets the visual/video Components available in this CallSession.
boolean	isLocalVideoAllowed() Gets the indicator which determines whether the streaming of local video in this CallSession is allowed.
boolean	isLocalVideoStreaming() Gets the indicator which determines whether this CallSession is currently streaming the local video (to a remote destination).
boolean	isMute() Determines whether the audio of this session is (set to) mute.
void	processSdpAnswer(CallPeer responder, String sdpAnswer) The method is meant for use by protocol service implementations upon reception of an SDP answer in response to an offer sent by us earlier.
String	processSdpOffer(CallPeer offerer, String sdpOffer) The method is meant for use by protocol service implementations when willing to respond to an invitation received from a remote caller.
void	putOnHold(boolean on, boolean here) Puts the media of this CallSession on/off hold depending on the origin of the request.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes a specific PropertyChangeListener from the list of listeners which get notified when the properties (e.g.
void	removeVideoListener(VideoListener listener) Removes a specific VideoListener from this CallSession in order to no longer have it receive notifications when visual/video Components are being added and removed.
void	setLocalVideoAllowed(boolean allowed) Sets the indicator which determines whether the streaming of local video in this CallSession is allowed.
void	setMute(boolean mute) Sets the mute state of the audio of this session.
void	setReceiveStreaming(int mediaFlags) Modifies the current setup of the stream receiving in accord with a specific set of media flags (which are usually obtained through getSdpOfferMediaFlags(String).
void	setSessionCreatorCallback(SessionCreatorCallback sessionCreatorCallBack) Sets a SessionCreatorCallback that will listen for security events.
boolean	setZrtpSASVerification(boolean verified) Sets the SAS verification
void	startStreaming() Starts the streaming of the local media (to the remote destinations).
void	startStreamingAndProcessingMedia() Calls startStreaming() in order to start the streaming of the local media and then begins processing the received and sent media streams.
boolean	stopStreaming() Stops and closes the audio and video streams flowing through this session.

Field Detail

ON_HOLD_REMOTELY

static final byte ON_HOLD_REMOTELY

The media flag which signals that the other side of the call has put this on hold.

See Also:

Constant Field Values

RECEIVE_AUDIO

static final byte RECEIVE_AUDIO

The media flag which signals that audio streams being received are to be handled (e.g. played).

See Also:

Constant Field Values

RECEIVE_VIDEO

static final byte RECEIVE_VIDEO

The media flag which signals that video streams being received are to be handled (e.g. played).

See Also:

Constant Field Values

LOCAL_VIDEO_STREAMING

static final String LOCAL_VIDEO_STREAMING

The property which indicates whether a CallSession is currently streaming the local video (to a remote destination).

See Also:

Constant Field Values

Method Detail

createSdpOffer

String createSdpOffer()
                      throws MediaException

The method is meant for use by protocol service implementations when willing to send an invitation to a remote callee.

Returns:

a String containing an SDP offer describing parameters of the Call associated with this session.

Throws:

MediaException - code INTERNAL_ERROR if generating the offer fails for some reason.

createSdpOffer

String createSdpOffer(InetAddress intendedDestination)
                      throws MediaException

The method is meant for use by protocol service implementations when willing to send an invitation to a remote callee. The intendedDestination parameter, may contain the address that the offer is to be sent to. In case it is null we'll try our best to determine a default local address.

Parameters:

intendedDestination - the address of the call peer that the descriptions is to be sent to.

Returns:

a new SDP description String advertising all params of callSession.

Throws:

MediaException - code SERVICE_NOT_STARTED if this method is called before the service was started.

createSdpOffer

String createSdpOffer(String peerSdpDescription)
                      throws MediaException

Creates a SDP description including the current state of the local media setup and in accord with a specific SDP description of a call peer (who is to be offered the created SDP description, for example, as part of a re-INVITE).

Parameters:

peerSdpDescription - the SDP description (of a call peer) to have the created SDP description in accord with

Returns:

a SDP description including the current state of the local media setup and in accord with the specified SDP description of a call peer

Throws:

MediaException

createSdpDescriptionForHold

String createSdpDescriptionForHold(String peerSdpDescription,
                                   boolean onHold)
                                   throws MediaException

The method is meant for use by protocol service implementations when willing to send an in-dialog invitation to a remote callee to put her on/off hold or to send an answer to an offer to be put on/off hold.

Parameters:

peerSdpDescription - the last SDP description of the remote callee

onHold - true if the SDP description should offer the remote callee to be put on hold or answer an offer from the remote callee to be put on hold; false to work in the context of a put-off-hold offer

Returns:

an SDP description String which offers the remote callee to be put her on/off hold or answers an offer from the remote callee to be put on/off hold

Throws:

MediaException

getSdpOfferMediaFlags

int getSdpOfferMediaFlags(String sdpOffer)
                          throws MediaException

Determines whether a specific SDP description String offers this party to be put on hold and which media types are offered to be received.

Parameters:

sdpOffer - the SDP description String to be examined for an offer to this party to be put on hold and media types to be received

Returns:

an int bit mask containing ON_HOLD_REMOTELY if the specified SDP description offers this party to be put on hold, RECEIVE_AUDIO and/or RECEIVE_VIDEO if audio and/or video, respectively, are to be received

Throws:

MediaException

setReceiveStreaming

void setReceiveStreaming(int mediaFlags)

Modifies the current setup of the stream receiving in accord with a specific set of media flags (which are usually obtained through getSdpOfferMediaFlags(String). For example, if RECEIVE_VIDEO isn't present and video is currently being received and played, stops its receiving and playback.

Parameters:

mediaFlags - an int bit mask containing any of the media-related flags such as RECEIVE_AUDIO and RECEIVE_VIDEO and thus specifying which media types are to be received

putOnHold

void putOnHold(boolean on,
               boolean here)

Puts the media of this CallSession on/off hold depending on the origin of the request.

For example, a remote request to have this party put off hold cannot override an earlier local request to put the remote party on hold.

Parameters:

on - true to request the media of this CallSession be put on hold; false, otherwise

here - true if the request comes from this side of the call; false if the remote party is the issuer of the request i.e. it's the result of a remote offer

processSdpOffer

String processSdpOffer(CallPeer offerer,
                       String sdpOffer)
                       throws MediaException,
                              ParseException

The method is meant for use by protocol service implementations when willing to respond to an invitation received from a remote caller. Apart from simply generating an SDP response description, the method records details

Parameters:

sdpOffer - the SDP offer that we'd like to create an answer for.

offerer - the peer that has sent the offer.

Returns:

a String containing an SDP answer describing parameters of the Call associated with this session and matching those advertised by the caller in their sdpOffer.

Throws:

MediaException - code INTERNAL_ERROR if processing the offer and/or generating the answer fail for some reason.

ParseException - if sdpOfferStr does not contain a valid sdp string.

processSdpAnswer

void processSdpAnswer(CallPeer responder,
                      String sdpAnswer)
                      throws MediaException,
                             ParseException

The method is meant for use by protocol service implementations upon reception of an SDP answer in response to an offer sent by us earlier.

Parameters:

sdpAnswer - the SDP answer that we'd like to handle.

responder - the peer that has sent the answer.

Throws:

MediaException - code SERVICE_NOT_STARTED if this method is called before the service was started.

ParseException - if sdpAnswerStr does not contain a valid sdp string.

getVideoPort

int getVideoPort()

Returns the port that we are using for receiving video data in this CallSession.

Returns:

the port number we are using for receiving video data in this CallSession.

getAudioPort

int getAudioPort()

Returns the port that we are using for receiving audio data in this CallSession.

Returns:

the port number we are using for receiving audio data in this CallSession.

getCallInfoURL

URL getCallInfoURL()

Returns a URL pointing to a location with call control information for this call or null if no such URL is available.

Returns:

a URL link to a location with call information or a call control web interface for the specified peer or null if no such URL is available.

isMute

boolean isMute()

Determines whether the audio of this session is (set to) mute.

Returns:

true if the audio of this session is (set to) mute; otherwise, false

setMute

void setMute(boolean mute)

Sets the mute state of the audio of this session.

Parameters:

mute - true to mute the audio of this session; otherwise, false

startStreaming

void startStreaming()
                    throws MediaException

Starts the streaming of the local media (to the remote destinations).

Throws:

MediaException

startStreamingAndProcessingMedia

void startStreamingAndProcessingMedia()
                                      throws MediaException

Calls startStreaming() in order to start the streaming of the local media and then begins processing the received and sent media streams.

Throws:

MediaException

stopStreaming

boolean stopStreaming()

Stops and closes the audio and video streams flowing through this session.

Returns:

true if there was an actual change in the streaming i.e. the streaming wasn't already stopped before this request; false, otherwise

getSecureCommunicationStatus

boolean getSecureCommunicationStatus()

Gets the default secure/unsecure communication status for the supported call sessions.

Returns:

default secure communication status for the supported call sessions

setZrtpSASVerification

boolean setZrtpSASVerification(boolean verified)

Sets the SAS verification

Returns:

True if SAS functions were called in ZrtpEngine

getCall

Call getCall()

Gets the call associated with this session

Returns:

the call associated with this session

addVideoListener

void addVideoListener(VideoListener listener)

Adds a specific VideoListener to this CallSession in order to receive notifications when visual/video Components are being added and removed.

Parameters:

listener - the VideoListener to be notified when visual/video Components are being added or removed in this CallSession

createLocalVisualComponent

Component createLocalVisualComponent(VideoListener listener)
                                     throws MediaException

Creates a visual Component which represents the local video streamed by this CallSession (to remote destinations). If the synchronous creation of the Component isn't supported, it will be carried out asynchronously and the progress of the operation and its result will be delivered through a specific VideoListener.

Parameters:

listener - the VideoListener to track the progress of the creation and deliver its result in case the operation is carried out asynchronously by this implementation

Returns:

a visual Component which represents the local video if this implementation creates it synchronously; null if this implementation attempts asynchronous creation in which case the result will be delivered to the specified VideoListener

Throws:

MediaException

disposeLocalVisualComponent

void disposeLocalVisualComponent(Component component)

Disposes of a specific visual Component representing local video which has been created by this instance with createLocalVisualComponent(VideoListener).

Parameters:

component - the visual Component representing local video to be disposed

getVisualComponents

Component[] getVisualComponents()

Gets the visual/video Components available in this CallSession.

Returns:

an array of the visual Components available in this CallSession

removeVideoListener

void removeVideoListener(VideoListener listener)

Removes a specific VideoListener from this CallSession in order to no longer have it receive notifications when visual/video Components are being added and removed.

Parameters:

listener - the VideoListener to no longer be notified when visual/video Components are being added or removed in this CallSession

setLocalVideoAllowed

void setLocalVideoAllowed(boolean allowed)
                          throws MediaException

Sets the indicator which determines whether the streaming of local video in this CallSession is allowed. The setting does not reflect the availability of actual video capture devices, it just expresses the desire of the user to have the local video streamed in the case the system is actually able to do so.

Parameters:

allowed - true to allow the streaming of local video for this CallSession; false to disallow it

Throws:

MediaException

isLocalVideoAllowed

boolean isLocalVideoAllowed()

Gets the indicator which determines whether the streaming of local video in this CallSession is allowed. The setting does not reflect the availability of actual video capture devices, it just expresses the desire of the user to have the local video streamed in the case the system is actually able to do so.

Returns:

true if the streaming of local video in this CallSession is allowed; otherwise, false

setSessionCreatorCallback

void setSessionCreatorCallback(SessionCreatorCallback sessionCreatorCallBack)

Sets a SessionCreatorCallback that will listen for security events.

Parameters:

sessionCreatorCallBack - the SessionCreatorCallback to set

getSessionCreatorCallback

SessionCreatorCallback getSessionCreatorCallback()

Returns the SessionCreatorCallback which listens for security events.

Returns:

the SessionCreatorCallback which listens for security events

isLocalVideoStreaming

boolean isLocalVideoStreaming()

Gets the indicator which determines whether this CallSession is currently streaming the local video (to a remote destination).

Returns:

true if this CallSession is currently streaming the local video (to a remote destination); otherwise, false

addPropertyChangeListener

void addPropertyChangeListener(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 CallSession change their values.

Parameters:

listener - the PropertyChangeListener to be notified when the properties associated with this CallSession change their values

removePropertyChangeListener

void removePropertyChangeListener(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 CallSession change their values.

Parameters:

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