ice4j/src/org/ice4j/ice/Agent.java

2430 lines
84 KiB
Java

/*
* ice4j, the OpenSource Java Solution for NAT and Firewall Traversal.
* Maintained by the Jitsi community (https://jitsi.org).
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package org.ice4j.ice;
import java.beans.*;
import java.io.*;
import java.math.*;
import java.net.*;
import java.security.*;
import java.util.*;
import java.util.logging.*;
import org.ice4j.*;
import org.ice4j.ice.harvest.*;
import org.ice4j.ice.harvest.TrickleCallback;
import org.ice4j.stack.*;
/**
* An <tt>Agent</tt> could be described as the main class (i.e. the chef
* d'orchestre) of an ICE implementation.
* <p>
* As defined in RFC 3264, an agent is the protocol implementation involved in
* the offer/answer exchange. There are two agents involved in an offer/answer
* exchange.
* </p>
* <p>
* <b>Note</b>: An <tt>Agent</tt> instance should be explicitly prepared for
* garbage collection by calling {@link #free()} on it if timely freeing of the
* associated resources is of importance; otherwise, it will wait for the
* garbage collector to call {@link #finalize()} on it.
* </p>
*
* @author Emil Ivov
* @author Lyubomir Marinov
* @author Sebastien Vincent
*/
public class Agent
{
/**
* The default maximum size for check lists.
*/
public static final int DEFAULT_MAX_CHECK_LIST_SIZE = 100;
/**
* The default number of milliseconds we should wait before moving from
* {@link IceProcessingState#COMPLETED} into {@link
* IceProcessingState#TERMINATED}.
*/
public static final int DEFAULT_TERMINATION_DELAY = 3000;
/**
* The constant which defines an empty array with element type
* <tt>PropertyChangeListener</tt> and represents the fact that there are no
* <tt>IceProcessingState</tt> change listeners added to an <tt>Agent</tt>
* (using {@link #addStateChangeListener(PropertyChangeListener)}.
*/
private static final PropertyChangeListener[] NO_STATE_CHANGE_LISTENERS
= new PropertyChangeListener[0];
/**
* The <tt>Logger</tt> used by the <tt>Agent</tt> class and its instances
* for logging output.
*/
private static final Logger logger
= Logger.getLogger(Agent.class.getName());
/**
* The LinkedHashMap used to store the media streams
* This map preserves the insertion order of the media streams.
*/
private final Map<String, IceMediaStream> mediaStreams
= new LinkedHashMap<String, IceMediaStream>();
/**
* The candidate harvester that we use to gather candidate on the local
* machine.
*/
private final HostCandidateHarvester hostCandidateHarvester
= new HostCandidateHarvester();
/**
* The set of harvesters (i.e. STUN, TURN, and others) that the agent should
* use when gathering candidates for components.
*/
private final CandidateHarvesterSet harvesters
= new CandidateHarvesterSet();
/**
* Manages statisics about harvesting time.
*/
private HarvestStatistics harvestStats = new HarvestStatistics();
/**
* We use the <tt>FoundationsRegistry</tt> to keep track of the foundations
* we assign within a session (i.e. the entire life time of an
* <tt>Agent</tt>)
*/
private final FoundationsRegistry foundationsRegistry
= new FoundationsRegistry();
/**
* Our internal nominator implementing several nomination strategies.
*/
private final DefaultNominator nominator;
/**
* ICE compatibility mode for this agent.
*/
private CompatibilityMode compatibilityMode = CompatibilityMode.RFC5245;
/**
* The name of the {@link PropertyChangeEvent} that we use to deliver
* events on changes in the state of ICE processing in this agent.
*/
public static final String PROPERTY_ICE_PROCESSING_STATE
= "IceProcessingState";
/**
* the value of <tt>Ta</tt> as specified by the application or <tt>-1</tt>
* if non was specified and we should calculate one ourselves.
*/
private long taValue = -1;
/**
* The <tt>List</tt> of remote addresses that we have discovered through
* incoming connectivity checks, before actually receiving a session
* description from the peer and that may potentially contain peer reflexive
* addresses. This list is stored and only if and while connectivity checks
* are not running. Once they start, we are able to determine whether the
* addresses in here are actually peer-reflexive or not, and schedule
* the necessary triggered checks.
*/
private final List<CandidatePair> preDiscoveredPairsQueue
= new LinkedList<CandidatePair>();
/**
* The lock that we use while starting connectivity establishment.
*/
private final Object startLock = new Object();
/**
* The user fragment that we should use for the ice-ufrag attribute.
*/
private final String ufrag;
/**
* The password that we should use for the ice-pwd attribute.
*/
private final String password;
/**
* The tie-breaker number is used in connectivity checks to detect and
* repair the case where both agents believe to have the controlling or the
* controlled role.
*/
private final long tieBreaker;
/**
* Determines whether this is the controlling agent in a an ICE interaction.
*/
private boolean isControlling = true;
/**
* The entity that will be taking care of outgoing connectivity checks.
*/
private final ConnectivityCheckClient connCheckClient;
/**
* The entity that will be taking care of incoming connectivity checks.
*/
private final ConnectivityCheckServer connCheckServer;
/**
* Indicates the state of ICE processing in this <tt>Agent</tt>. An
* <tt>Agent</tt> is in the Waiting state until it has both sent and
* received candidate lists and started connectivity establishment. The
* difference between the Waiting and the Running states is important in
* cases like determining whether a remote address we've just discovered is
* peer reflexive or not. If iceStarted is true and we don't know about the
* address then we should add it to the list of candidates. Otherwise
* we should wait for the remote party to send their media description
* before being able to determine.
*/
private IceProcessingState state = IceProcessingState.WAITING;
/**
* Contains {@link PropertyChangeListener}s registered with this {@link
* Agent} and following its changes of state.
*/
private final List<PropertyChangeListener> stateListeners
= new LinkedList<PropertyChangeListener>();
/**
* The <tt>StunStack</tt> used by this <tt>Agent</tt>.
*/
private StunStack stunStack;
/**
* The thread that we use for moving from COMPLETED into a TERMINATED state.
*/
private TerminationThread terminationThread;
/**
* The thread that we use for STUN keep-alive.
*/
private StunKeepAliveThread stunKeepAliveThread;
/**
* Some protocols, such as XMPP, need to be able to distinguish the separate
* ICE sessions that occur as a result of ICE restarts, which is why we need
* to keep track of generations. A generation is an index, starting at 0,
* that enables the parties to keep track of updates to the candidate
* throughout the life of the session.
*/
private int generation = 0;
/**
* Determines whether this agent should perform trickling.
*/
private boolean trickle = false;
/**
* Indicates that ICE will be shutdown.
*/
private boolean shutdown = false;
/**
* Indicates that harvesting has been started at least ones. Used to warn
* users who are trying to trickle, that they have already completed a
* harvest. We may use it to throw an exception at some point if it's ever
* a problem.
*/
private boolean harvestingStarted = false;
/**
* Creates an empty <tt>Agent</tt> with no streams, and no address.
*/
public Agent()
{
this(CompatibilityMode.RFC5245);
}
/**
* Creates an empty <tt>Agent</tt> with no streams, and no address.
*
* @param compatibilityMode ICE compatibility mode
*/
public Agent(CompatibilityMode compatibilityMode)
{
SecureRandom random = new SecureRandom();
this.compatibilityMode = compatibilityMode;
connCheckServer = new ConnectivityCheckServer(this);
connCheckClient = new ConnectivityCheckClient(this);
//add the FINGERPRINT attribute to all messages.
System.setProperty(StackProperties.ALWAYS_SIGN, "true");
//add the software attribute to all messages
if (StackProperties.getString(StackProperties.SOFTWARE) == null)
System.setProperty(StackProperties.SOFTWARE, "ice4j.org");
if(compatibilityMode == CompatibilityMode.GTALK)
{
/* username is 16 byte in Google Talk dialect but it is set
* for each candidate and not globally
*/
ufrag = null;
/* no password in Google Talk dialect (at least libnice does not use
* one)
*/
password = "";
}
else
{
ufrag = new BigInteger(24, random).toString(32);
password = new BigInteger(128, random).toString(32);
}
tieBreaker = Math.abs(random.nextLong());
nominator = new DefaultNominator(this);
}
/**
* Creates a new media stream and stores it.
*
* @param mediaStreamName the name of the media stream
*
* @return the newly created and stored <tt>IceMediaStream</tt>
*/
public IceMediaStream createMediaStream(String mediaStreamName)
{
logger.fine("Create media stream for " + mediaStreamName);
IceMediaStream mediaStream
= new IceMediaStream(Agent.this, mediaStreamName);
mediaStreams.put(mediaStreamName, mediaStream);
// Since we add a new stream, we must wait to add the component and the
// remote candidates before starting to "RUN" this Agent.
// This is usefull if this Agent is already in COMPLETED state
// (isStarted() == true) due to a previous successful ICE preocedure:
// this way incoming connectivity checks are registered in the
// preDiscoveredPairsQueue until this Agent is in RUNNING state.
this.setState(IceProcessingState.WAITING);
return mediaStream;
}
/**
* Creates a new {@link Component} for the specified <tt>stream</tt> and
* allocates potentially all local candidates that should belong to it.
*
* @param stream the {@link IceMediaStream} that the new {@link Component}
* should belong to.
* @param transport the transport protocol used by the component
* @param preferredPort the port number that should be tried first when
* binding local <tt>Candidate</tt> sockets for this <tt>Component</tt>.
* @param minPort the port number where we should first try to bind before
* moving to the next one (i.e. <tt>minPort + 1</tt>)
* @param maxPort the maximum port number where we should try binding
* before giving up and throwinG an exception.
*
* @return the newly created {@link Component} and with a list containing
* all and only local candidates.
*
* @throws IllegalArgumentException if either <tt>minPort</tt> or
* <tt>maxPort</tt> is not a valid port number or if <tt>minPort >
* maxPort</tt>, or if <tt>transport</tt> is not currently supported.
* @throws IOException if an error occurs while the underlying resolver lib
* is using sockets.
* @throws BindException if we couldn't find a free port between
* <tt>minPort</tt> and <tt>maxPort</tt> before reaching the maximum allowed
* number of retries.
*/
public Component createComponent( IceMediaStream stream,
Transport transport,
int preferredPort,
int minPort,
int maxPort)
throws IllegalArgumentException,
IOException,
BindException
{
if(transport != Transport.UDP)
{
throw new IllegalArgumentException(
"This implementation does not currently support transport: "
+ transport);
}
Component component = stream.createComponent(transport);
gatherCandidates(component, preferredPort, minPort, maxPort);
for(Candidate<?> candidate : component.getLocalCandidates())
{
logger.info("\t" + candidate.getTransportAddress() + " (" +
candidate.getType() + ")");
if(compatibilityMode == CompatibilityMode.GTALK)
{
/* assign a local ufrag of 16 bytes for each candidate */
LocalCandidate localCand = (LocalCandidate)candidate;
/* Google relayed candidate should have already set their
* ufrag since it must be the same as username present in
* HTTP response
*/
if(localCand.getUfrag() != null)
{
continue;
}
localCand.setUfrag(generateGTalkUfrag());
}
}
/*
* Lyubomir: After we've gathered the LocalCandidate for a Component and
* before we've make them available to the caller, we have to make sure
* that the ConnectivityCheckServer is started. If there's been a
* previous connectivity establishment which has completed, it has
* stopped the ConnectivityCheckServer. If the ConnectivtyCheckServer is
* not started after we've made the gathered LocalCandidates available
* to the caller, the caller may send them and a connectivity check may
* arrive from the remote Agent.
*/
connCheckServer.start();
return component;
}
/**
* Generates Ufrag for GTalk mode.
*
* @return 16 bytes Ufrag
*/
public String generateGTalkUfrag()
{
SecureRandom random = new SecureRandom();
String s = null;
while(s == null || s.length() != 16)
{
s = new BigInteger(80, random).toString(32);
}
return s;
}
/**
* Uses all <tt>CandidateHarvester</tt>s currently registered with this
* <tt>Agent</tt> to obtain whatever addresses they can discover.
* <p>
* Not that the method would only use existing harvesters so make sure
* you've registered all harvesters that you would want to use before
* calling it.
* </p>
* @param component the <tt>Component</tt> that we'd like to gather
* candidates for.
* @param preferredPort the port number that should be tried first when
* binding local <tt>Candidate</tt> sockets for this <tt>Component</tt>.
* @param minPort the port number where we should first try to bind before
* moving to the next one (i.e. <tt>minPort + 1</tt>)
* @param maxPort the maximum port number where we should try binding
* before giving up and throwing an exception.
*
* @throws IllegalArgumentException if either <tt>minPort</tt> or
* <tt>maxPort</tt> is not a valid port number or if <tt>minPort &gt;
* maxPort</tt>.
* @throws IOException if an error occurs while the underlying resolver lib
* is gathering candidates and we end up without even a single one.
*/
private void gatherCandidates( Component component,
int preferredPort,
int minPort,
int maxPort)
throws IllegalArgumentException,
IOException
{
logger.info("Gather candidates for component " +
component.toShortString());
hostCandidateHarvester.harvest(
component,
preferredPort, minPort, maxPort, Transport.UDP);
if(compatibilityMode == CompatibilityMode.GTALK)
{
hostCandidateHarvester.harvest(
component,
preferredPort, minPort, maxPort, Transport.TCP);
}
logger.fine("host candidate count: " +
component.getLocalCandidateCount());
//in case we are not trickling, apply other harvesters here
if(!isTrickling())
{
harvestingStarted = true; //raise a flag to warn on a second call.
harvesters.harvest(component);
}
logger.fine("Candidate count in first harvest: " +
component.getLocalCandidateCount());
//Emil: because of trickle we now assign foundations, compute priorities
//and eliminate redundancies while adding candidates on a component.
// This means that we no longer need to do it here, where we did before.
//computeFoundations(component);
//component.prioritizeCandidates();
//component.eliminateRedundantCandidates();
//select the candidate to put in the media line.
component.selectDefaultCandidate();
}
/**
* Starts an asynchronous harvest across all components and reports newly
* discovered candidates to <tt>trickleCallback</tt>.
*
* @param trickleCallback the callback that will be notified for all newly
* discovered candidates.
*
* @throws IllegalStateException if we try calling this method without being
* in a trickling state.
*/
public void startCandidateTrickle(TrickleCallback trickleCallback)
throws IllegalStateException
{
if(!isTrickling())
{
throw new IllegalStateException(
"Trying to start trickling without enabling it on the agent!");
}
if(harvestingStarted)
{
logger.warning(
"Hmmm ... why are you harvesting twice? You shouldn't be!");
}
//create a list of components and start harvesting
List<Component> components = new LinkedList<Component>();
for (IceMediaStream stream : getStreams())
{
components.addAll( stream.getComponents());
}
harvesters.harvest(components, trickleCallback);
//tell the tricklers that we are done (the WebRTC way, with null):
trickleCallback.onIceCandidates(null);
}
/**
* Initializes all stream check lists and begins the checks.
*/
public void startConnectivityEstablishment()
{
synchronized(startLock)
{
logger.info("Start ICE connectivity establishment");
shutdown = false;
pruneNonMatchedStreams();
try
{
initCheckLists();
}
catch(ArithmeticException e)
{
setState(IceProcessingState.FAILED);
return;
}
//change state before we actually send checks so that we don't
//miss responses and hence the possibility to nominate a pair.
setState(IceProcessingState.RUNNING);
//if we have received connectivity checks before RUNNING state,
//trigger a check for those candidate pairs.
if(this.preDiscoveredPairsQueue.size() > 0)
{
logger.info("Trigger checks for pairs that were received " +
"before running state");
Iterator<CandidatePair> it = preDiscoveredPairsQueue.iterator();
while(it.hasNext())
{
triggerCheck(it.next());
}
this.preDiscoveredPairsQueue.clear();
}
connCheckClient.startChecks();
}
}
/**
* <tt>Free()</tt>s and removes from this agent components or entire streams
* if they do not contain remote candidates. A possible reason for this
* could be the fact that the remote party canceled some of the streams or
* that it is using rtcp-mux or bundle.
*/
private void pruneNonMatchedStreams()
{
for (IceMediaStream stream : getStreams())
{
for(Component cmp : stream.getComponents())
{
if(cmp.getRemoteCandidateCount() == 0)
stream.removeComponent(cmp);
}
if(stream.getComponentCount() == 0)
removeStream(stream);
}
}
/**
* Indicates whether this {@link Agent} is currently in the process of
* running connectivity checks and establishing connectivity. Connectivity
* establishment is considered to have started after both {@link Agent}s
* have exchanged their media descriptions. Determining whether the actual
* process has started is important, for example, when determining whether
* a remote address we've just discovered is peer reflexive or not.
* If ICE has started and we don't know about the address then we should
* add it to the list of candidates. Otherwise we should hold to it until
* it does and check later.
* <p>
* Note that an {@link Agent} would be ready to and will send responses to
* connectivity checks as soon as it streams get created, which is well
* before we actually start the checks.
*
* @return <tt>true</tt> after media descriptions have been exchanged both
* ways and connectivity checks have started (regardless of their current
* state) and <tt>false</tt> otherwise.
*/
public boolean isStarted()
{
return state != IceProcessingState.WAITING
&& state != IceProcessingState.COMPLETED
&& state != IceProcessingState.TERMINATED;
}
/**
* Indicates whether this {@link Agent} has finished ICE processing.
*
* @return <tt>true</tt> if ICE processing is in the {@link
* IceProcessingState#FAILED}, {@link IceProcessingState#COMPLETED} or
* {@link IceProcessingState#TERMINATED} and <tt>false</tt> otherwise.
*/
public boolean isOver()
{
return state == IceProcessingState.COMPLETED
|| state == IceProcessingState.TERMINATED
|| state == IceProcessingState.FAILED;
}
/**
* Returns the state of ICE processing for this <tt>Agent</tt>.
*
* @return the state of ICE processing for this <tt>Agent</tt>.
*/
public IceProcessingState getState()
{
return state;
}
/**
* Adds <tt>l</tt> to the list of listeners tracking changes of the
* {@link IceProcessingState} of this <tt>Agent</tt>
*
* @param l the listener to register.
*/
public void addStateChangeListener(PropertyChangeListener l)
{
synchronized(stateListeners)
{
if(!stateListeners.contains(l))
this.stateListeners.add(l);
}
}
/**
* Removes <tt>l</tt> from the list of listeners tracking changes of the
* {@link IceProcessingState} of this <tt>Agent</tt>
*
* @param l the listener to remove.
*/
public void removeStateChangeListener(PropertyChangeListener l)
{
synchronized(stateListeners)
{
this.stateListeners.remove(l);
}
}
/**
* Creates a new {@link PropertyChangeEvent} and delivers it to all
* currently registered state listeners.
*
* @param oldState the {@link IceProcessingState} we had before the change
* @param newState the {@link IceProcessingState} we had after the change
*/
private void fireStateChange(IceProcessingState oldState,
IceProcessingState newState)
{
PropertyChangeListener[] stateListenersCopy;
synchronized(stateListeners)
{
stateListenersCopy
= stateListeners.toArray(NO_STATE_CHANGE_LISTENERS);
}
if (stateListenersCopy.length != 0)
{
PropertyChangeEvent evt
= new PropertyChangeEvent(
this,
PROPERTY_ICE_PROCESSING_STATE,
oldState, newState);
for(PropertyChangeListener l : stateListenersCopy)
l.propertyChange(evt);
}
}
/**
* Sets the {@link IceProcessingState} of this <tt>Agent</tt> to
* <tt>newState</tt> and triggers the corresponding change event.
*
* @param newState the new state of ICE processing for this <tt>Agent</tt>.
*/
private void setState(IceProcessingState newState)
{
IceProcessingState oldState = state;
this.state = newState;
fireStateChange(oldState, newState);
}
/**
* Creates, initializes and orders the list of candidate pairs that would
* be used for the connectivity checks for all components in this stream.
*/
protected void initCheckLists()
{
//first init the check list.
List<IceMediaStream> streams
= getStreamsWithPendingConnectivityEstablishment();
//init the maximum number of check list entries per stream.
int maxCheckListSize = Integer.getInteger(
StackProperties.MAX_CHECK_LIST_SIZE,
DEFAULT_MAX_CHECK_LIST_SIZE);
int maxPerStreamSize = maxCheckListSize / streams.size();
for(IceMediaStream stream : streams)
{
logger.info("Init checklist for stream " + stream.getName());
stream.setMaxCheckListSize(maxPerStreamSize);
stream.initCheckList();
}
//init the states of the first media stream as per 5245
streams.get(0).getCheckList().computeInitialCheckListPairStates();
}
/**
* Computes and sets the foundations foundation for all <tt>Candidate</tt>s
* currently found in <tt>component</tt>.
*
* @param component the component whose candidate foundations we'd like to
* compute and assign.
*/
private void computeFoundations(Component component)
{
List<LocalCandidate> candidates = component.getLocalCandidates();
for (Candidate<?> cand : candidates)
foundationsRegistry.assignFoundation(cand);
}
/**
* Adds <tt>harvester</tt> to the list of harvesters that this agent will
* use when gathering <tt>Candidate</tt>s.
*
* @param harvester a <tt>CandidateHarvester</tt> that this agent should use
* when gathering candidates.
*/
public void addCandidateHarvester(CandidateHarvester harvester)
{
harvesters.add(harvester);
}
/**
* Returns the set of harvesters currently in use by this agent.
*
* @return the set of harvesters currently in use by this agent.
*/
public CandidateHarvesterSet getHarvesters()
{
return harvesters;
}
/**
* Returns that user name that should be advertised in session descriptions
* containing ICE data from this agent.
*
* @return that user name that should be advertised in session descriptions
* containing ICE data from this agent.
*/
public String getLocalUfrag()
{
return ufrag;
}
/**
* Returns that password that should be advertised in session descriptions
* containing ICE data from this agent.
*
* @return that password that should be advertised in session descriptions
* containing ICE data from this agent.
*/
public String getLocalPassword()
{
return password;
}
/**
* Returns the user name that this <tt>Agent</tt> should use in connectivity
* checks for outgoing Binding Requests. According to RFC 5245, a Binding
* Request serving as a connectivity check MUST utilize the STUN short term
* credential mechanism. The username for the credential is formed by
* concatenating the username fragment provided by the peer with the
* username fragment of the agent sending the request, separated by a
* colon (":"). The password is equal to the password provided by the peer.
* For example, consider the case where agent L is the offerer, and agent R
* is the answerer. Agent L included a username fragment of LFRAG for its
* candidates, and a password of LPASS. Agent R provided a username
* fragment of RFRAG and a password of RPASS. A connectivity check from L
* to R (and its response of course) utilize the username RFRAG:LFRAG and a
* password of RPASS. A connectivity check from R to L (and its response)
* utilize the username LFRAG:RFRAG and a password of LPASS.
*
* @param media media name that we want to generate local username for.
* @return a user name that this <tt>Agent</tt> can use in connectivity
* check for outgoing Binding Requests.
*/
public String generateLocalUserName(String media)
{
IceMediaStream stream = getStream(media);
String ret = null;
if(stream == null || stream.getRemoteUfrag() == null)
{
return null;
}
ret = stream.getRemoteUfrag() + ":" + getLocalUfrag();
return ret;
}
/**
* Returns the user name that we should expect a peer <tt>Agent</tt> to use
* in connectivity checks for Binding Requests its sending our way.
* According to RFC 5245, a Binding Request serving as a connectivity check
* MUST utilize the STUN short term credential mechanism. The username for
* the credential is formed by concatenating the username fragment provided
* by the peer with the username fragment of the agent sending the request,
* separated by a colon (":"). The password is equal to the password
* provided by the peer. For example, consider the case where agent
* L is the offerer, and agent R is the answerer. Agent L
* included a username fragment of LFRAG for its candidates,
* and a password of LPASS. Agent R provided a username fragment
* of RFRAG and a password of RPASS. A connectivity check from L
* to R (and its response of course) utilize the username RFRAG:LFRAG and a
* password of RPASS. A connectivity check from R to L (and its response)
* utilize the username LFRAG:RFRAG and a password of LPASS.
*
* @param media media name that we want to generate local username for.
* @return a user name that a peer <tt>Agent</tt> would use in connectivity
* check for outgoing Binding Requests.
*/
public String generateRemoteUserName(String media)
{
IceMediaStream stream = getStream(media);
String ret = null;
if(stream == null)
{
return null;
}
if(compatibilityMode == CompatibilityMode.RFC5245)
{
ret = getLocalUfrag() + ":" + stream.getRemoteUfrag();
}
else if(compatibilityMode == CompatibilityMode.GTALK)
{
ret = getLocalUfrag() + stream.getRemoteUfrag();
}
return ret;
}
/**
* Returns the user name that this <tt>Agent</tt> should use in connectivity
* checks for outgoing Binding Requests in a Google Talk session.
*
* @param remoteCandidate remote candidate
* @param localCandidate local candidate
* @return a user name that this <tt>Agent</tt> can use in connectivity
* check for outgoing Binding Requests.
*/
public String generateLocalUserName(RemoteCandidate remoteCandidate,
LocalCandidate localCandidate)
{
return generateUserName(remoteCandidate, localCandidate);
}
/**
* Returns the user name that we should expect a peer <tt>Agent</tt> to use
* in connectivity checks for Binding Requests its sending our way in a
* Google Talk session.
*
* @param remoteCandidate remote candidate
* @param localCandidate local candidate
* @return a user name that a peer <tt>Agent</tt> would use in connectivity
* check for outgoing Binding Requests.
*/
public String generateRemoteUserName(RemoteCandidate remoteCandidate,
LocalCandidate localCandidate)
{
return generateUserName(localCandidate, remoteCandidate);
}
/**
* Returns the user name that we should expect a peer <tt>Agent</tt> to use
* in connectivity checks for Binding Requests its sending our way in a
* Google Talk session.
*
* @param candidate1 The first candidate of a candidatePair.
* @param candidate2 The second candidate of a candidatePair.
* @return a user name that a peer <tt>Agent</tt> would use in connectivity
* check for outgoing Binding Requests.
*/
private String generateUserName(
Candidate<?> candidate1,
Candidate<?> candidate2)
{
String ret = null;
String ufrag1 = candidate1.getUfrag();
String ufrag2 = candidate2.getUfrag();
/* Google Talk specific
* each candidate has its own username/password
*/
if(ufrag1 != null
&& ufrag2 != null
&& compatibilityMode == CompatibilityMode.GTALK)
{
ret = ufrag1 + ufrag2;
}
return ret;
}
/**
* Returns the {@link FoundationsRegistry} this agent is using to assign
* candidate foundations. We use the <tt>FoundationsRegistry</tt> to keep
* track of the foundations we assign within a session (i.e. the entire life
* time of an <tt>Agent</tt>)
*/
public final FoundationsRegistry getFoundationsRegistry()
{
return foundationsRegistry;
}
/**
* Returns the <tt>IceMediaStream</tt> with the specified <tt>name</tt> or
* <tt>null</tt> if no such stream has been registered with this
* <tt>Agent</tt> yet.
*
* @param name the name of the stream that we'd like to obtain a reference
* to.
*
* @return the <tt>IceMediaStream</tt> with the specified <tt>name</tt> or
* <tt>null</tt> if no such stream has been registered with this
* <tt>Agent</tt> yet.
*/
public IceMediaStream getStream(String name)
{
synchronized(mediaStreams)
{
return mediaStreams.get(name);
}
}
/**
* Returns a <tt>List</tt> containing the names of all currently registered
* media streams.
*
* @return a <tt>List</tt> containing the names of all currently registered
* media streams.
*/
public List<String> getStreamNames()
{
synchronized(mediaStreams)
{
return new LinkedList<String>(mediaStreams.keySet());
}
}
/**
* Returns a <tt>List</tt> containing all <tt>IceMediaStream</tt>s currently
* registered with this agent.
*
* @return a <tt>List</tt> containing all <tt>IceMediaStream</tt>s currently
* registered with this agent.
*/
public List<IceMediaStream> getStreams()
{
synchronized(mediaStreams)
{
return new LinkedList<IceMediaStream>(mediaStreams.values());
}
}
/**
* Returns the number of <tt>IceMediaStream</tt>s currently registered with
* this agent.
*
* @return the number of <tt>IceMediaStream</tt>s currently registered with
* this agent.
*
*/
public int getStreamCount()
{
synchronized(mediaStreams)
{
return mediaStreams.size();
}
}
/**
* Gets the <tt>IceMediaStream</tt>s registered with this <tt>Agent</tt> for
* which connectivity establishment is pending. For example, after a set of
* <tt>IceMediaStream</tt>s is registered with this <tt>Agent</tt>,
* connectivity establishment completes for them and then a new set of
* <tt>IceMediaStream</tt>s is registered with this <tt>Agent</tt>, the
* <tt>IceMediaStream</tt>s with pending connectivity establishment are
* those from the second set.
*
* @return a <tt>List</tt> of the <tt>IceMediaStream</tt>s registered with
* this <tt>Agent</tt> for which connectivity is pending.
*/
List<IceMediaStream> getStreamsWithPendingConnectivityEstablishment()
{
/*
* Lyubomir: We want to support establishing connectivity for streams
* which have been created after connectivity has been established for
* previously created streams. That is why we will remove the streams
* which have their connectivity checks completed or failed i.e. these
* streams have been handled by a previous connectivity establishment.
*/
List<IceMediaStream> streams = getStreams();
Iterator<IceMediaStream> streamIter = streams.iterator();
while (streamIter.hasNext())
{
IceMediaStream stream = streamIter.next();
CheckList checkList = stream.getCheckList();
CheckListState checkListState = checkList.getState();
if (CheckListState.COMPLETED.equals(checkListState)
|| CheckListState.FAILED.equals(checkListState))
streamIter.remove();
}
return streams;
}
/**
* Gets the <tt>StunStack</tt> used by this <tt>Agent</tt>.
*
* @return the <tt>StunStack</tt> used by this <tt>Agent</tt>
*/
public synchronized StunStack getStunStack()
{
if (stunStack == null)
stunStack = new StunStack(compatibilityMode);
return stunStack;
}
/**
* Returns the number of {@link CheckList}s that are currently active.
*
* @return the number of {@link CheckList}s that are currently active.
*
*/
protected int getActiveCheckListCount()
{
synchronized(mediaStreams)
{
int i=0;
Collection<IceMediaStream> streams = mediaStreams.values();
for (IceMediaStream stream : streams)
{
if (stream.getCheckList().isActive())
i++;
}
return i;
}
}
/**
* Returns a <tt>String</tt> representation of this agent.
*
* @return a <tt>String</tt> representation of this agent.
*/
@Override
public String toString()
{
StringBuilder buff = new StringBuilder("ICE Agent (stream-count=");
buff.append(getStreamCount()).append(" ice-pwd:")
.append(getLocalPassword());
buff.append(getStreamCount()).append(" ice-ufrag:")
.append(getLocalUfrag());
buff.append(getStreamCount()).append(" tie-breaker:")
.append(getTieBreaker());
buff.append("):\n");
for(IceMediaStream stream : getStreams())
buff.append(stream.toString()).append("\n");
return buff.toString();
}
/**
* Returns this agent's tie-breaker number. The tie-breaker number is used
* in connectivity checks to detect and repair the case where both agents
* believe to have the controlling or the controlled role.
*
* @return this agent's tie-breaker number
*/
public long getTieBreaker()
{
return tieBreaker;
}
/**
* Specifies whether this agent has the controlling role in an ICE exchange.
*
* @param isControlling <tt>true</tt> if this is to be the controlling
* <tt>Agent</tt> and <tt>false</tt> otherwise.
*/
public void setControlling(boolean isControlling)
{
this.isControlling = isControlling;
//in case we have already initialized our check lists we'd need to
//recompute pair priorities.
List<IceMediaStream> streams = getStreams();
for(IceMediaStream stream : streams)
{
CheckList list = stream.getCheckList();
if (list != null)
list.recomputePairPriorities();
}
}
/**
* Removes <tt>stream</tt> and all its child <tt>Component</tt>s and
* <tt>Candidate</tt>s from the this agent and releases all resources that
* they had allocated (like sockets for example)
*
* @param stream the <tt>Component</tt> we'd like to remove and free.
*/
public void removeStream(IceMediaStream stream)
{
synchronized (mediaStreams)
{
mediaStreams.remove(stream.getName());
stream.free();
}
}
/**
* Determines whether this agent has the controlling role in an ICE
* exchange.
*
* @return <tt>true</tt> if this is to be the controlling <tt>Agent</tt>
* and <tt>false</tt> otherwise.
*/
public boolean isControlling()
{
return isControlling;
}
/**
* Returns the local <tt>LocalCandidate</tt> with the specified
* <tt>localAddress</tt> if it belongs to any of this {@link Agent}'s
* streams or <tt>null</tt> if it doesn't.
*
* @param localAddress the {@link TransportAddress} we are looking for.
*
* @return the local <tt>LocalCandidate</tt> with the specified
* <tt>localAddress</tt> if it belongs to any of this {@link Agent}'s
* streams or <tt>null</tt> if it doesn't.
*/
public LocalCandidate findLocalCandidate(TransportAddress localAddress)
{
Collection<IceMediaStream> streamsCollection = mediaStreams.values();
for( IceMediaStream stream : streamsCollection)
{
LocalCandidate cnd = stream.findLocalCandidate(localAddress);
if(cnd != null)
return cnd;
}
return null;
}
/**
* Returns the local <tt>LocalCandidate</tt> with the specified
* <tt>localAddress</tt> if it belongs to any of this {@link Agent}'s
* streams or <tt>null</tt> if it doesn't.
*
* @param localAddress the {@link TransportAddress} we are looking for.
* @param ufrag local ufrag
* @return the local <tt>LocalCandidate</tt> with the specified
* <tt>localAddress</tt> if it belongs to any of this {@link Agent}'s
* streams or <tt>null</tt> if it doesn't.
*/
public LocalCandidate findLocalCandidate(TransportAddress localAddress,
String ufrag)
{
Collection<IceMediaStream> streamsCollection = mediaStreams.values();
for(IceMediaStream stream : streamsCollection)
{
for(Component c : stream.getComponents())
{
for(LocalCandidate cnd : c.getLocalCandidates())
{
if(cnd != null && cnd.getUfrag() != null &&
cnd.getUfrag().equals(ufrag))
return cnd;
}
}
}
return null;
}
/**
* Returns the remote <tt>Candidate</tt> with the specified
* <tt>remoteAddress</tt> if it belongs to any of this {@link Agent}'s
* streams or <tt>null</tt> if it doesn't.
*
* @param remoteAddress the {@link TransportAddress} we are looking for.
*
* @return the remote <tt>Candidate</tt> with the specified
* <tt>remoteAddress</tt> if it belongs to any of this {@link Agent}'s
* streams or <tt>null</tt> if it doesn't.
*/
public RemoteCandidate findRemoteCandidate(TransportAddress remoteAddress)
{
Collection<IceMediaStream> streamsCollection = mediaStreams.values();
for( IceMediaStream stream : streamsCollection)
{
RemoteCandidate cnd = stream.findRemoteCandidate(remoteAddress);
if(cnd != null)
return cnd;
}
return null;
}
/**
* Returns the {@link CandidatePair} with the specified remote and local
* addresses or <tt>null</tt> if neither of the {@link CheckList}s in this
* {@link Agent}'s streams contain such a pair.
*
* @param localAddress the local {@link TransportAddress} of the pair we
* are looking for.
* @param remoteAddress the remote {@link TransportAddress} of the pair we
* are looking for.
*
* @return the {@link CandidatePair} with the specified remote and local
* addresses or <tt>null</tt> if neither of the {@link CheckList}s in this
* {@link Agent}'s streams contain such a pair.
*/
public CandidatePair findCandidatePair(TransportAddress localAddress,
TransportAddress remoteAddress)
{
synchronized(mediaStreams)
{
Collection<IceMediaStream> streamsCollection
= mediaStreams.values();
for (IceMediaStream stream : streamsCollection)
{
CandidatePair pair
= stream.findCandidatePair(localAddress, remoteAddress);
if( pair != null )
return pair;
}
}
return null;
}
/**
* Returns the {@link CandidatePair} with the specified remote and local
* addresses or <tt>null</tt> if neither of the {@link CheckList}s in this
* {@link Agent}'s streams contain such a pair.
*
* @param localUFrag local user fragment
* @param remoteUFrag remote user fragment
* @return the {@link CandidatePair} with the specified remote and local
* addresses or <tt>null</tt> if neither of the {@link CheckList}s in this
* {@link Agent}'s streams contain such a pair.
*/
public CandidatePair findCandidatePair(String localUFrag,
String remoteUFrag)
{
synchronized(mediaStreams)
{
Collection<IceMediaStream> streamsCollection
= mediaStreams.values();
for (IceMediaStream stream : streamsCollection)
{
CandidatePair pair
= stream.findCandidatePair(localUFrag, remoteUFrag);
if( pair != null )
return pair;
}
}
return null;
}
/**
* Notifies the implementation that the {@link ConnectivityCheckServer} has
* just received a message on <tt>localAddress</tt> originating at
* <tt>remoteAddress</tt> carrying the specified <tt>priority</tt>. This
* will cause us to schedule a triggered check for the corresponding
* remote candidate and potentially to the discovery of a PEER-REFLEXIVE
* candidate.
*
* @param remoteAddress the address that we've just seen, and that is
* potentially a peer-reflexive address.
* @param localAddress the address that we were contacted on.
* @param priority the priority that the remote party assigned to
* @param remoteUFrag the user fragment that we should be using when and if
* we decide to send a check to <tt>remoteAddress</tt>.
* @param localUFrag local user fragment
* @param useCandidate indicates whether the incoming check
* {@link org.ice4j.message.Request} contained the USE-CANDIDATE ICE
* attribute.
*/
protected void incomingCheckReceived(TransportAddress remoteAddress,
TransportAddress localAddress,
long priority,
String remoteUFrag,
String localUFrag,
boolean useCandidate)
{
if (isOver())
{
//means we already completed ICE and are happily running media
//the only reason we are called is most probably because the remote
//party is still sending Binding Requests our way and making sure we
//are still alive.
return;
}
String ufrag = null;
LocalCandidate localCandidate = null;
if(compatibilityMode == CompatibilityMode.GTALK
&& localAddress.getTransport() != Transport.TCP)
{
localCandidate = findLocalCandidate(localAddress, remoteUFrag);
}
else
{
localCandidate = findLocalCandidate(localAddress);
}
if(localCandidate == null)
{
logger.info("No localAddress for this incoming checks: " +
localAddress);
return;
}
Component parentComponent = localCandidate.getParentComponent();
RemoteCandidate remoteCandidate = null;
// we need to find the username for the couple
if(compatibilityMode == CompatibilityMode.GTALK)
{
CandidatePair pair = findCandidatePair(localUFrag, remoteUFrag);
if(pair == null)
{
logger.info("No GTalk CandidatePair that match Lufrag/Rufrag" +
" " + localUFrag + " " + remoteUFrag);
return;
}
CandidatePair pair2 = findCandidatePair(
localCandidate.getTransportAddress(),
remoteAddress);
if(pair2 == null)
{
useCandidate = false;
}
else
{
useCandidate = pair2.useCandidateReceived();
}
ufrag = pair.getRemoteCandidate().getUfrag();
}
remoteCandidate = new RemoteCandidate(
remoteAddress,
parentComponent,
CandidateType.PEER_REFLEXIVE_CANDIDATE,
foundationsRegistry.obtainFoundationForPeerReflexiveCandidate(),
priority,
// We can not know the related candidate of a remote peer
// reflexive candidate. We must set it to "null".
null,
ufrag);
CandidatePair triggeredPair
= new CandidatePair(localCandidate, remoteCandidate);
logger.fine("set use-candidate " + useCandidate + " for pair " +
triggeredPair.toShortString());
if(useCandidate)
{
triggeredPair.setUseCandidateReceived();
}
synchronized(startLock)
{
if(isStarted())
{
//we are started, which means we have the remote candidates
//so it's now safe to go and see whether this is a new PR cand.
if(triggeredPair.getParentComponent().getSelectedPair() == null)
{
logger.info("Received check from " +
triggeredPair.toShortString() + " triggered a check");
}
triggerCheck(triggeredPair);
}
else
{
logger.fine("Receive STUN checks before our ICE has started");
//we are not started yet so we'd better wait until we get the
//remote candidates in case we are holding to a new PR one.
this.preDiscoveredPairsQueue.add(triggeredPair);
}
}
}
/**
* Either queues a triggered check for <tt>triggeredPair</tt> or, in case
* there's already a pair with the specified remote and local addresses,
* puts it in the queue instead.
*
* @param triggerPair the pair containing the local and remote candidate
* that we'd need to trigger a check for.
*/
private void triggerCheck(CandidatePair triggerPair)
{
//first check whether we already know about the remote address in case
//we've just discovered a peer-reflexive candidate.
CandidatePair knownPair = null;
knownPair = this.findCandidatePair(
triggerPair.getLocalCandidate().getTransportAddress(),
triggerPair.getRemoteCandidate().getTransportAddress());
IceMediaStream parentStream = triggerPair.getLocalCandidate()
.getParentComponent().getParentStream();
if (knownPair != null)
{
boolean useCand = false;
useCand = triggerPair.useCandidateReceived();
//if the incoming request contained a USE-CANDIDATE attribute then
//make sure we don't lose this piece of info.
if (triggerPair.useCandidateReceived())
knownPair.setUseCandidateReceived();
triggerPair = knownPair;
//we already know about the remote address so we only need to
//trigger a check for the existing pair
if(compatibilityMode != CompatibilityMode.RFC5245 &&
!isControlling())
{
logger.fine("set useCandidateReceived for " +
triggerPair.toShortString());
// we synchronize here because the same pair object can be
// processed (in another thread) in ConnectivityCheckClient's
// processSuccessResponse. A controlled agent select its
// pair here if the pair state is succeeded (set in
// processSuccessResponse) or in processSuccessResponse if
// the pair has useCandidateReceived as true (set here). So be
// sure that if a binding response and a binding request (for
// the same check) from other peer come at the very same time,
// that we will trigger the nominationConfirmed (that will
// pass the pair as selected if it is the first time).
synchronized(triggerPair)
{
//next time we will see a request it will be considered as
//having USE-CANDIDATE
triggerPair.setUseCandidateReceived();
}
}
if (knownPair.getState() == CandidatePairState.SUCCEEDED )
{
//7.2.1.5. Updating the Nominated Flag
if (!isControlling() && useCand)
{
logger.fine("update nominated flag");
// If the Binding request received by the agent had the
// USE-CANDIDATE attribute set, and the agent is in the
// controlled role, the agent looks at the state of the
// pair ....
// If the state of this pair is Succeeded, it means that a
// previous check generated by this pair produced a
// successful response. This would have caused the agent to
// construct a valid pair when that success response was
// received. The agent now sets the nominated flag in the
// valid pair to true.
nominationConfirmed( triggerPair );
//the above may have caused us to exit, and so we need to
//make the call below in order to make sure that we update
//ICE processing state.
checkListStatesUpdated();
}
return;
}
// RFC 5245: If the state of that pair is In-Progress, the agent
// cancels the in-progress transaction.
if (knownPair.getState() == CandidatePairState.IN_PROGRESS )
{
TransactionID checkTransaction
= knownPair.getConnectivityCheckTransaction();
getStunStack().cancelTransaction(checkTransaction);
}
}
else
{
//it appears that we've just discovered a peer-reflexive address.
// RFC 5245: If the pair is not already on the check list:
// The pair is inserted into the check list based on its priority
// Its state is set to Waiting [and it] is enqueued into the
// triggered check queue.
//
if(triggerPair.getParentComponent().getSelectedPair() == null)
logger.info("Add peer CandidatePair with new reflexive " +
"address to checkList");
triggerPair.setUseCandidateReceived();
parentStream.addToCheckList(triggerPair);
}
// RFC 5245: The agent MUST create a new connectivity check for that
// pair (representing a new STUN Binding request transaction) by
// enqueueing the pair in the triggered check queue. The state of
// the pair is then changed to Waiting.
// Emil: This actually applies for all cases.
/*
* Lyubomir: The connectivity checks for a CheckList are started
* elsewhere as soon as and only if the CheckList changes from frozen
* to unfrozen. Since CheckList#scheduleTriggeredCheck will change
* triggerPair to Waiting and will thus unfreeze its CheckList, make
* sure that the connectivity checks for the CheckList are started.
* Otherwise, the connectivity checks for the CheckList may never be
* started (which may make the Agent remain running forever).
*/
CheckList checkList = parentStream.getCheckList();
boolean wasFrozen = checkList.isFrozen();
checkList.scheduleTriggeredCheck(triggerPair);
if (wasFrozen && !checkList.isFrozen())
connCheckClient.startChecks(checkList);
}
/**
* Adds <tt>pair</tt> to that list of valid candidates for its parent
* stream.
*
* @param validPair the {@link CandidatePair} we'd like to validate.
*/
protected void validatePair(CandidatePair validPair)
{
Component parentComponent = validPair.getParentComponent();
IceMediaStream parentStream = parentComponent.getParentStream();
parentStream.addToValidList(validPair);
}
/**
* Raises <tt>pair</tt>'s nomination flag and schedules a triggered check.
* Applications only need to use this method if they disable this
* <tt>Agent</tt>'s internal nomination and implement their own nominator
* and turn off nominations in this agent.
*
* @param pair the {@link CandidatePair} that we'd like to nominate and that
* we'd like to schedule a triggered check for.
*
* @throws IllegalStateException if this <tt>Agent</tt> is not a controlling
* agent and can therefore not nominate pairs.
*
* @see Agent#setNominationStrategy(NominationStrategy)
*/
public synchronized void nominate(CandidatePair pair)
throws IllegalStateException
{
if(! isControlling() )
throw new IllegalStateException("Only controlling agents can "
+"nominate pairs");
Component parentComponent = pair.getParentComponent();
IceMediaStream parentStream = parentComponent.getParentStream();
//If the pair is not already nominated and if its parent component
//does not already contain a nominated pair - nominate it.
if(!pair.isNominated()
&& !parentStream.validListContainsNomineeForComponent(
parentComponent))
{
logger.info("verify if nominated pair answer again");
pair.nominate();
pair.getParentComponent().getParentStream()
.getCheckList().scheduleTriggeredCheck(pair);
}
}
/**
* Specifies the {@link NominationStrategy} that we should use in order to
* decide if and when we should nominate valid pairs.
*
* @param strategy the strategy that we'd like to use for nominating
* valid {@link CandidatePair}s.
*/
public void setNominationStrategy(NominationStrategy strategy)
{
this.nominator.setStrategy(strategy);
}
/**
* Indicates that we have received a response to a request that either
* contained the <tt>USE-CANDIDATE</tt> attribute or was triggered by an
* incoming request that did.
*
* @param nominatedPair the {@link CandidatePair} whose nomination has
* just been confirmed.
*/
protected void nominationConfirmed(CandidatePair nominatedPair)
{
nominatedPair.nominate();
Component parentComponent = nominatedPair.getParentComponent();
IceMediaStream parentStream = parentComponent.getParentStream();
CheckList checkList = parentStream.getCheckList();
if( checkList.getState() == CheckListState.RUNNING )
checkList.handleNominationConfirmed(nominatedPair);
//Once there is at least one nominated pair in the valid list for
//every component of the media stream and the state of the
//check list is Running
if(parentStream.allComponentsHaveSelected()
&& checkList.getState() == CheckListState.RUNNING)
{
//The agent MUST change the state of processing for its check
//list for that media stream to Completed.
checkList.setState(CheckListState.COMPLETED);
}
}
/**
* After updating check list states as a result of an incoming response
* or a timeout event the method goes through all check lists and tries
* to assess the state of ICE processing.
*/
protected void checkListStatesUpdated()
{
boolean allListsEnded = true;
boolean atLeastOneListSucceeded = false;
if(getState() == IceProcessingState.COMPLETED)
return;
List<IceMediaStream> streams = getStreams();
for(IceMediaStream stream : streams)
{
CheckListState checkListState = stream.getCheckList().getState();
if(checkListState == CheckListState.RUNNING)
{
allListsEnded = false;
break;
}
else if(checkListState == CheckListState.COMPLETED)
{
logger.info("CheckList of stream " + stream.getName() +
" is COMPLETED");
atLeastOneListSucceeded = true;
}
}
if(!allListsEnded)
return;
if(!atLeastOneListSucceeded)
{
//all lists ended but none succeeded. No love today ;(
logger.info("ICE state is FAILED");
terminate(IceProcessingState.FAILED);
return;
}
//Once the state of each check list is Completed:
//The agent sets the state of ICE processing overall to Completed.
if(getState() != IceProcessingState.RUNNING)
{
//Oh, seems like we already did this.
return;
}
logger.info("ICE state is COMPLETED");
setState(IceProcessingState.COMPLETED);
// keep ICE running (answer binding request)
if(stunKeepAliveThread == null)
{
// schedule STUN checks for selected candidates
scheduleSTUNKeepAlive();
}
if(compatibilityMode == CompatibilityMode.RFC5245)
{
scheduleTermination();
}
//print logs for the types of addresses we chose.
logCandTypes();
}
/**
* Goes through all streams and components and prints into the logs the type
* of local candidates that were selected as well as the server that
* were used (if any) to obtain them.
*/
private void logCandTypes()
{
List<IceMediaStream> strms = getStreams();
for(IceMediaStream stream : strms)
{
for(Component component : stream.getComponents())
{
CandidatePair selectedPair = component.getSelectedPair();
StringBuffer buf
= new StringBuffer( "Harvester used for selected pair for ");
buf.append(component.toShortString());
buf.append(": ");
if(selectedPair == null)
{
buf.append("none (conn checks failed)");
logger.info(buf.toString());
continue;
}
Candidate localCnd = selectedPair.getLocalCandidate();
TransportAddress serverAddr = localCnd.getStunServerAddress();
TransportAddress relayAddr = localCnd.getRelayServerAddress();
buf.append(localCnd.getType());
if(serverAddr != null)
{
buf.append(" (STUN server = ");
buf.append(localCnd.getStunServerAddress());
buf.append(")");
}
else if(relayAddr != null)
{
buf.append(" (relay = ");
buf.append(localCnd.getRelayServerAddress());
buf.append(")");
}
logger.info(buf.toString());
}
}
}
/**
* Returns the number of host {@link Candidate}s in this {@link Agent}.
*
* @return the number of host {@link Candidate}s in this {@link Agent}.
*/
protected int countHostCandidates()
{
int num = 0;
synchronized (mediaStreams)
{
Collection<IceMediaStream> streamsCol = mediaStreams.values();
for( IceMediaStream stream : streamsCol)
num += stream.countHostCandidates();
}
return num;
}
/**
* Lets the application specify a custom value for the <tt>Ta</tt> timer
* so that we don't calculate one.
*
* @param taValue the value of the <tt>Ta</tt> timer that the application
* would like us to use rather than calculate one.
*/
public void setTa(long taValue)
{
this.taValue = taValue;
}
/**
* Calculates the value of the <tt>Ta</tt> pace timer according to the
* number and type of {@link IceMediaStream}s this agent will be using.
* <p>
* During the gathering phase of ICE (Section 4.1.1) and while ICE is
* performing connectivity checks (Section 7), an agent sends STUN and
* TURN transactions. These transactions are paced at a rate of one
* every <tt>Ta</tt> milliseconds.
* <p>
* As per RFC 5245, the value of <tt>Ta</tt> should be configurable so if
* someone has set a value of their own, we return that value rather than
* calculating a new one.
*
* @return the value of the <tt>Ta</tt> pace timer according to the
* number and type of {@link IceMediaStream}s this agent will be using or
* a pre-configured value if the application has set one.
* <p>
*/
protected long calculateTa()
{
//if application specified a value - use it. other wise return ....
// eeeer ... a "dynamically" calculated one ;)
if (taValue != -1)
return taValue;
/* RFC 5245 says that Ta is:
*
* Ta_i = (stun_packet_size / rtp_packet_size) * rtp_ptime
*
* 1
* Ta = MAX (20ms, ------------------- )
* k
* ----
* \ 1
* > ------
* / Ta_i
* ----
* i=1
*
* In this implementation we assume equal values of
* stun_packet_size and rtp_packet_size. rtp_ptime is also assumed to be
* 20ms. One day we should probably let the application modify them.
* Until then however the above formula would always be equal to.
* 1
* Ta = MAX (20ms, ------- )
* k
* ---
* 20
* which gives us Ta = MAX (20ms, 20/k) which is always 20.
*/
return 20;
}
/**
* Calculates the value of the retransmission timer to use in STUN
* transactions, while harvesting addresses (not to confuse with the RTO
* for the STUN transactions used in connectivity checks).
*
* @return the value of the retransmission timer to use in STUN
* transactions, while harvesting addresses.
*/
protected long calculateStunHarvestRTO()
{
/* RFC 5245 says:
* RTO = MAX (100ms, Ta * (number of pairs))
* where the number of pairs refers to the number of pairs of candidates
* with STUN or TURN servers.
*
* Go figure what "pairs of candidates with STUN or TURN servers" means.
* Let's assume they meant the number stun transactions we'll start
* while harvesting.
*/
return Math.max(100, calculateTa() * 2 * countHostCandidates());
}
/**
* Calculates the value of the retransmission timer to use in STUN
* transactions, used in connectivity checks (not to confused with the RTO
* for the STUN address harvesting).
*
* @return the value of the retransmission timer to use in STUN connectivity
* check transactions..
*/
protected long calculateStunConnCheckRTO()
{
/* RFC 5245 says:
* For connectivity checks, RTO SHOULD be configurable and SHOULD have
* a default of:
*
* RTO = MAX (100ms, Ta*N * (Num-Waiting + Num-In-Progress))
*
* where Num-Waiting is the number of checks in the check list in the
* Waiting state, Num-In-Progress is the number of checks in the
* In-Progress state, and N is the number of checks to be performed.
*
* Emil: I am not sure I like the formula so we'll simply be returning
* 100 for the time being.
*/
return 100;
}
/**
* Initializes and starts the {@link TerminationThread}
*/
private void scheduleTermination()
{
if (terminationThread == null)
{
terminationThread = new TerminationThread();
terminationThread.start();
}
}
/**
* Initializes and starts the {@link StunKeepAliveThread}
*/
private void scheduleSTUNKeepAlive()
{
if (stunKeepAliveThread == null)
{
stunKeepAliveThread = new StunKeepAliveThread();
stunKeepAliveThread.start();
}
}
/**
* RFC 5245 says: Once ICE processing has reached the Completed state for
* all peers for media streams using those candidates, the agent SHOULD
* wait an additional three seconds, and then it MAY cease responding to
* checks or generating triggered checks on that candidate. It MAY free
* the candidate at that time.
* <p>
* This <tt>TerminationThread</tt> is scheduling such a termination and
* garbage collection in three seconds.
*/
private class TerminationThread
extends Thread
{
/**
* Creates a new termination timer.
*/
private TerminationThread()
{
super("TerminationThread");
}
/**
* Waits for a period of three seconds (or whatever termination
* interval the user has specified) and then moves this <tt>Agent</tt>
* into the terminated state and frees all non-nominated candidates.
*/
@Override
public synchronized void run()
{
long terminationDelay
= Integer.getInteger(
StackProperties.TERMINATION_DELAY,
DEFAULT_TERMINATION_DELAY);
if (terminationDelay >= 0)
{
try
{
wait(terminationDelay);
}
catch (InterruptedException ie)
{
logger.log(
Level.FINEST, "Interrupted while waiting. Will "
+"speed up termination",
ie);
}
}
logger.info("ICE state is TERMINATED");
terminate(IceProcessingState.TERMINATED);
terminationThread = null;
}
}
/**
* Terminates this <tt>Agent</tt> by stopping the handling of connectivity
* checks and setting a specific termination state on it.
*
* @param terminationState the state that we'd like processing to terminate
* with i.e. either {@link IceProcessingState#TERMINATED} or
* {@link IceProcessingState#FAILED}
*/
private void terminate(IceProcessingState terminationState)
{
if (!IceProcessingState.FAILED.equals(terminationState)
&& !IceProcessingState.TERMINATED.equals(terminationState))
throw new IllegalArgumentException("terminationState");
// stop making any checks.
connCheckClient.stop();
//do not stop the conn check server here because it may still need to
//process STUN Binding Requests that remote agents may send our way.
//we'll do this in "free()" instead.
//connCheckServer.stop();
setState(terminationState);
}
/**
* Called by the garbage collector when garbage collection determines that
* there are no more references to this instance. Calls {@link #free()} on
* this instance.
*
* @throws Throwable if anything goes wrong and the finalization of this
* instance is to be halted
* @see #free()
*/
@Override
protected void finalize()
throws Throwable
{
free();
super.finalize();
}
/**
* Prepares this <tt>Agent</tt> for garbage collection by ending all related
* processes and freeing its <tt>IceMediaStream</tt>s, <tt>Component</tt>s
* and <tt>Candidate</tt>s. This method will also place the agent in the
* terminated state in case it wasn't already there.
*/
public void free()
{
logger.info("Free ICE agent");
shutdown = true;
//stop sending keep alives (STUN Binding Indications).
if(stunKeepAliveThread != null)
stunKeepAliveThread.interrupt();
//stop responding to STUN Binding Requests.
connCheckServer.stop();
/*
* Set the IceProcessingState#TERMINATED state on this Agent unless it
* is in a termination state already.
*/
IceProcessingState state = getState();
if ( !IceProcessingState.FAILED.equals(state)
&& !IceProcessingState.TERMINATED.equals(state))
{
terminate(IceProcessingState.TERMINATED);
}
logger.info("remove streams");
// Free its IceMediaStreams, Components and Candidates.
for(IceMediaStream stream : getStreams())
{
try
{
removeStream(stream);
}
catch(Throwable t)
{
logger.info("remove stream failed: " + t);
}
logger.info("remove stream " + stream.getName());
}
getStunStack().shutDown();
logger.info("ICE agent freed");
}
/**
* Returns the current generation of this ICE Agent. A generation is an
* index, starting at 0, that enables the parties to keep track of updates
* to the candidate throughout the life of the session.
*
* @return the current generation of this ICE Agent
*/
public int getGeneration()
{
return generation;
}
/**
* Specifies the current generation of this ICE Agent. A generation is an
* index, starting at 0, that enables the parties to keep track of updates
* to the candidate throughout the life of the session.
*
* @param generation the current generation of this ICE Agent
*/
public void setGeneration(int generation)
{
this.generation = generation;
}
/**
* Returns the compatibility mode used by this agent.
*
* @return compatibility mode
*/
public CompatibilityMode getCompatibilityMode()
{
return compatibilityMode;
}
/**
* Thread that performs STUN keep-alive once ICE has COMPLETED.
*/
private class StunKeepAliveThread
extends Thread
{
/**
* Creates a new termination timer.
*/
private StunKeepAliveThread()
{
super("StunKeepAliveThread");
}
/**
* Thread entry to point.
*/
@Override
public synchronized void run()
{
runInStunKeepAliveThread();
}
}
/**
* Schedule STUN checks for selected pair.
*/
public void runInStunKeepAliveThread()
{
while(state == IceProcessingState.COMPLETED || state ==
IceProcessingState.TERMINATED)
{
if(shutdown)
break;
List<IceMediaStream> streams = getStreams();
for(IceMediaStream stream : streams)
{
List<Component> cmps = stream.getComponents();
for(Component cmp : cmps)
{
CandidatePair pair = cmp.getSelectedPair();
if(pair != null)
{
if(compatibilityMode == CompatibilityMode.GTALK)
{
//apparently GTalk insists on seeing binding
//requests or else it believes we are dead
//Emil: I am not sure this is true. I think it would
//be enough for us to respond to their binding
//requests. At least that's how it seems to work for
//Chrome and WebRTC.
//TODO: check and maybe remove
connCheckClient.startCheckForPair(pair);
}
else if(compatibilityMode == CompatibilityMode.RFC5245)
{
connCheckClient.sendBindingIndicationForPair(pair);
}
}
}
}
if(shutdown)
break;
try
{
Thread.sleep(15000);
Thread.yield();
}
catch(InterruptedException e)
{
}
}
logger.info("KeepAliveThread ends");
}
/**
* Returns the selected pair for this Agent.
*
* @param streamName The stream name (AUDIO, VIDEO);
*
* @return The selected pair for this Agent. Null if no pair is selected.
*/
private CandidatePair getSelectedPair(String streamName)
{
List<IceMediaStream> iceMediaStreams = this.getStreams();
for(int i = 0; i < iceMediaStreams.size(); ++i)
{
if(iceMediaStreams.get(i).getName().equals(streamName))
{
List<org.ice4j.ice.Component> components =
iceMediaStreams.get(i).getComponents();
for(int j = 0; j < components.size(); ++j)
{
Component component = components.get(i);
if(component.getComponentID()
== org.ice4j.ice.Component.RTP)
{
return component.getSelectedPair();
}
}
}
}
return null;
}
/**
* Returns the selected local candidate for this Agent.
*
* @param streamName The stream name (AUDIO, VIDEO);
*
* @return The selected local candidate for this Agent. Null if no pair is
* selected.
*/
public LocalCandidate getSelectedLocalCandidate(String streamName)
{
CandidatePair candidatePair = this.getSelectedPair(streamName);
if(candidatePair != null)
{
return candidatePair.getLocalCandidate();
}
return null;
}
/**
* Returns the selected remote candidate for this Agent.
*
* @param streamName The stream name (AUDIO, VIDEO);
*
* @return The selected remote candidate for this Agent. Null if no pair is
* selected.
*/
public RemoteCandidate getSelectedRemoteCandidate(String streamName)
{
CandidatePair candidatePair = this.getSelectedPair(streamName);
if(candidatePair != null)
{
return candidatePair.getRemoteCandidate();
}
return null;
}
/**
* Indicates whether this agent is currently set to trickle candidates
* rather than gathering them synchronously while components are being
* added. When trickling is turned on, the agent will only gather host
* addresses for newly added components. When trickling is off, all
* harvesting for a specific component will be executed when that component
* is being added.
*
* @return <tt>false</tt> if this agent is configured to perform all
* harvesting when components are being added and <tt>false</tt> otherwise.
*/
public boolean isTrickling()
{
return trickle;
}
/**
* Determines whether this agent will trickle candidates rather than
* gather them synchronously while components are being added. When
* trickling is turned on, the agent will only gather host addresses for
* newly added components. When trickling is off, all harvesting for a
* specific component will be executed when that component is being added.
*
* @param trickle <tt>false</tt> if this agent is configured to perform all
* harvesting when components are being added and <tt>false</tt> otherwise.
*/
public void setTrickling(boolean trickle)
{
this.trickle = trickle;
}
/**
* Returns the harvesting time (in ms) for the harvester given in parameter.
*
* @param harvesterName The class name if the harvester.
*
* @return The harvesting time (in ms) for the harvester given in parameter.
*/
public long getHarvestingTime(String harvesterName)
{
long harvestingTime = 0;
for(CandidateHarvester harvester : harvesters)
{
if(harvester.getClass().getName().endsWith(harvesterName))
{
harvestingTime = harvester.getHarvestStatistics()
.getHarvestDuration();
// There may be several harvester with the same class name.
// Thus, returns only an active one (if any).
if(harvestingTime != 0)
{
return harvestingTime;
}
}
}
return 0;
}
/**
* Returns the number of harvesting time for the harvester given in
* parameter.
*
* @param harvesterName The class name if the harvester.
*
* @return The number of harvesting time for the harvester given in
* parameter.
*/
public int getHarvestCount(String harvesterName)
{
int harvestCount;
for(CandidateHarvester harvester : harvesters)
{
if(harvester.getClass().getName().endsWith(harvesterName))
{
harvestCount
= harvester.getHarvestStatistics().getHarvestCount();
// There may be several harvester with the same class name.
// Thus, returns only an active one (if any).
if(harvestCount != 0)
{
return harvestCount;
}
}
}
return 0;
}
/**
* Returns the combined harvesting time for all harvesters in this agent.
*
* @return the total time this agent has spent harvesting.
*/
public long getTotalHarvestingTime()
{
long harvestDuration = 0;
for(CandidateHarvester harvester : harvesters)
{
harvestDuration += harvester
.getHarvestStatistics().getHarvestDuration();
}
return harvestDuration;
}
/**
* Returns the total number of harvests completed by this agent. Normally
* this number should be equal to NB_HARVESTERS*NB_COMPONENTS but could be
* less if some harvesters were disabled for inefficiency or more ... if
* there's a bug ;).
*
* @return the number of harvest this agent has completed.
*/
public int getHarvestCount()
{
int harvestCount = 0;
for(CandidateHarvester harvester : harvesters)
{
harvestCount += harvester
.getHarvestStatistics().getHarvestDuration();
}
return harvestCount;
}
}