org.restcomm.media.ice

Class IceAgent

java.lang.Object

org.restcomm.media.ice.IceAgent

All Implemented Interfaces:

IceAuthenticator

Direct Known Subclasses:

IceLiteAgent

public abstract class IceAgent
extends Object
implements IceAuthenticator

Agent responsible for ICE negotiation.

Author:

Henrique Rosa (henrique.rosa@telestax.com)

Field Summary

Fields

Modifier and Type	Field and Description
protected ConnectivityCheckServer	connectivityCheckServer
protected List<IceEventListener>	iceListeners
protected String	password
protected boolean	running
protected Selector	selector
protected String	ufrag

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IceAgent()

Method Summary

Methods

Modifier and Type	Method and Description
void	addIceListener(IceEventListener listener)
IceMediaStream	addMediaStream(String streamName) Creates an IceMediaStream and adds to it an RTP and an RTCP components.
IceMediaStream	addMediaStream(String streamName, boolean rtcp) Creates and registers a new media stream with an RTP component. An secondary component may be created if the stream supports RTCP.
IceMediaStream	addMediaStream(String streamName, boolean rtcp, boolean rtcpMux) Creates and registers a new media stream with an RTP component. An secondary component may be created if the stream supports RTCP.
void	generateIceCredentials()
InetAddress	getExternalAddress()
byte[]	getLocalKey(String ufrag) Gets the password assigned to a local user.
IceMediaStream	getMediaStream(String streamName) Gets a media stream by name
List<IceMediaStream>	getMediaStreams()
String	getPassword() Gets the password of the local user fragment
byte[]	getRemoteKey(String ufrag, String media) Gets the password assigned to a remote user.
CandidatePair	getSelectedRtcpCandidate(String stream)
CandidatePair	getSelectedRtpCandidate(String stream)
String	getUfrag() Gets the local user fragment.
void	harvest(RtpPortManager portManager) Gathers all available candidates and sets the components of each media stream.
abstract boolean	isControlling() Checks whether the Agent is controlling the ICE process.
abstract boolean	isLite() Checks whether the Agent implements ICE Lite
boolean	isRunning() Indicates whether the ICE agent is currently started.
boolean	isSelectionFinished()
boolean	isUserRegistered(String ufrag) Verifies whether a local user is registered.
void	removeIceListener(IceEventListener listener)
void	reset()
CandidatePair	selectCandidatePair(DatagramChannel channel)
void	setExternalAddress(InetAddress externalAddress)
abstract void	start() Starts the ICE agent by activating its STUN stack.
abstract void	stop() Stops the ICE agent.
boolean	validateUsername(String username) Validates the autenticity of a STUN USERNAME attribute. The agent MUST consider the username to be valid if it consists of two values separated by a colon, where the first value is equal to the username fragment generated by the agent in an offer or answer for a session in-progress.

Methods inherited from class java.lang.Object

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

Field Detail

ufrag

protected String ufrag

password

protected String password

selector

protected Selector selector

connectivityCheckServer

protected ConnectivityCheckServer connectivityCheckServer

running

protected volatile boolean running

iceListeners

protected final List<IceEventListener> iceListeners

Constructor Detail

IceAgent

protected IceAgent()

Method Detail

generateIceCredentials

public void generateIceCredentials()

isLite

public abstract boolean isLite()

Checks whether the Agent implements ICE Lite

Returns:

true if the agent implements ICE Lite. False, in case of full ICE.

isControlling

public abstract boolean isControlling()

Checks whether the Agent is controlling the ICE process.

Returns:

isRunning

public boolean isRunning()

Indicates whether the ICE agent is currently started.

Returns:

getUfrag

public String getUfrag()

Gets the local user fragment.

Returns:

the local ice-ufrag

getPassword

public String getPassword()

Gets the password of the local user fragment

Returns:

the local ice-pwd

addMediaStream

public IceMediaStream addMediaStream(String streamName)

Creates an IceMediaStream and adds to it an RTP and an RTCP components.

Parameters:

streamName - the name of the stream to create

agent - the Agent that should create the stream.

Returns:

the newly created IceMediaStream.

addMediaStream

public IceMediaStream addMediaStream(String streamName,
                            boolean rtcp)

Creates and registers a new media stream with an RTP component.
An secondary component may be created if the stream supports RTCP.

Parameters:

streamName - the name of the media stream

rtcp - Indicates whether the media server supports RTCP.

Returns:

The newly created media stream.

addMediaStream

public IceMediaStream addMediaStream(String streamName,
                            boolean rtcp,
                            boolean rtcpMux)

Creates and registers a new media stream with an RTP component.
An secondary component may be created if the stream supports RTCP.

Parameters:

streamName - the name of the media stream

rtcp - Indicates whether the media server supports RTCP.

rtcpMux - Indicates whether the media stream supports rtcp-mux

Returns:

The newly created media stream.

getMediaStream

public IceMediaStream getMediaStream(String streamName)

Gets a media stream by name

Parameters:

streamName - The name of the media stream

Returns:

The media stream. Returns null, if no media stream exists with such name.

getMediaStreams

public List<IceMediaStream> getMediaStreams()

harvest

public void harvest(RtpPortManager portManager)
             throws HarvestException,
                    NoCandidatesGatheredException

Gathers all available candidates and sets the components of each media stream.

Parameters:

portManager - The manager that handles port range for ICE candidate harvest

Throws:

HarvestException - An error occurred while harvesting candidates

NoCandidatesGatheredException

start

public abstract void start()

Starts the ICE agent by activating its STUN stack.

Full ICE implementations start connectivity checks while listening for incoming checks.
Lite implementations are restricted to listen to incoming connectivity checks.

stop

public abstract void stop()

Stops the ICE agent.

isSelectionFinished

public boolean isSelectionFinished()

selectCandidatePair

public CandidatePair selectCandidatePair(DatagramChannel channel)

getSelectedRtpCandidate

public CandidatePair getSelectedRtpCandidate(String stream)

getSelectedRtcpCandidate

public CandidatePair getSelectedRtcpCandidate(String stream)

addIceListener

public void addIceListener(IceEventListener listener)

removeIceListener

public void removeIceListener(IceEventListener listener)

getLocalKey

public byte[] getLocalKey(String ufrag)

Description copied from interface: IceAuthenticator

Gets the password assigned to a local user.

Specified by:

getLocalKey in interface IceAuthenticator

Parameters:

ufrag - the fragment of the local user

Returns:

The password of the specified user.
If the user has no password associated, returns an empty key.
If the user does not exist, returns null.

getRemoteKey

public byte[] getRemoteKey(String ufrag,
                  String media)

Description copied from interface: IceAuthenticator

Gets the password assigned to a remote user.

Specified by:

getRemoteKey in interface IceAuthenticator

Parameters:

ufrag - the fragment of the remote user

media - the name of the target media stream

Returns:

The password of the specified user.
If the user has no password associated, returns an empty key.
If the user or media stream do not exist, returns null.

isUserRegistered

public boolean isUserRegistered(String ufrag)

Description copied from interface: IceAuthenticator

Verifies whether a local user is registered.

Specified by:

isUserRegistered in interface IceAuthenticator

Parameters:

ufrag - the fragment of the local user

Returns:

true if the user exists, false otherwise.

getExternalAddress

public InetAddress getExternalAddress()

setExternalAddress

public void setExternalAddress(InetAddress externalAddress)

validateUsername

public boolean validateUsername(String username)

Description copied from interface: IceAuthenticator

Validates the autenticity of a STUN USERNAME attribute.
The agent MUST consider the username to be valid if it consists of two values separated by a colon, where the first value is equal to the username fragment generated by the agent in an offer or answer for a session in-progress.

Specified by:

validateUsername in interface IceAuthenticator

Parameters:

username - The username to be validated

Returns:

Whether the username is valid or not.

reset

public void reset()