Constructor Detail

• Agent

  Agent()

  Creates an empty Agent with no streams, and no address.

• Agent

  Agent(Logger parentLogger)

• Agent

  Agent(String ufragPrefix, Logger parentLogger)

  Creates an empty Agent with no streams, and no address.

  Parameters:

  ufragPrefix - an optional prefix to the generated local ICE username fragment.

Method Detail

• getHarvesters

   CandidateHarvesterSet getHarvesters()

  Returns the set of harvesters currently in use by this agent.

• getFoundationsRegistry

   final FoundationsRegistry getFoundationsRegistry()

  Returns the FoundationsRegistry this agent is using to assign candidate foundations. We use the FoundationsRegistry to keep track of the foundations we assign within a session (i.e. the entire life time of an Agent)

• getTieBreaker

   long getTieBreaker()

  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.

• setTieBreaker

   void setTieBreaker(long tieBreakerInput)

  Sets the tie breaker value. Note that to this should be set early (before connectivity checks start).

  Parameters:

  tieBreakerInput - the value to set.

• isControlling

   boolean isControlling()

  Determines whether this agent has the controlling role in an ICE exchange.

• getState

   IceProcessingState getState()

  Returns the state of ICE processing for this Agent.

• setState

   boolean setState(IceProcessingState newState)

  Sets the IceProcessingState of this Agent to newState and triggers the corresponding change event.

  Parameters:

  newState - the new state of ICE processing for this Agent.

• getStunStack

   synchronized StunStack getStunStack()

  Gets the StunStack used by this Agent.

• setStunStack

   void setStunStack(StunStack stunStack)

  Sets the StunStack used by this Agent.

  Parameters:

  stunStack - the stunStack to be used by this Agent.

• getGeneration

   int getGeneration()

  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.

• setGeneration

   void setGeneration(int 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.

  Parameters:

  generation - the current generation of this ICE Agent

• getPerformConsentFreshness

   boolean getPerformConsentFreshness()

  Gets the indicator which determines whether this Agent is to perform consent freshness.

• setPerformConsentFreshness

   void setPerformConsentFreshness(boolean performConsentFreshness)

  Sets the indicator which determines whether this Agent is to perform consent freshness.

  Parameters:

  performConsentFreshness - true if this Agent is to perform consent freshness; otherwise, false

• setUseDynamicPorts

   void setUseDynamicPorts(boolean value)

  Sets the flag for whether this Agent instance should use dynamic ports.

• createMediaStream

   IceMediaStream createMediaStream(String mediaStreamName)

  Creates a new media stream and stores it.

  Parameters:

  mediaStreamName - the name of the media stream

• createComponent

   Component createComponent(IceMediaStream stream, int preferredPort, int minPort, int maxPort)

  Creates a new Component for the specified stream and allocates potentially all local candidates that should belong to it.

  Parameters:

  stream - the IceMediaStream that the new Component should belong to.

  preferredPort - the port number that should be tried first when binding local Candidate sockets for this Component.

  minPort - the port number where we should first try to bind before moving to the next one (i.e.

  maxPort - the maximum port number where we should try binding before giving up and throwing an exception.

• createComponent

   Component createComponent(IceMediaStream stream, int preferredPort, int minPort, int maxPort, KeepAliveStrategy keepAliveStrategy)

  Creates a new Component for the specified stream and allocates potentially all local candidates that should belong to it.

  Parameters:

  stream - the IceMediaStream that the new Component should belong to.

  preferredPort - the port number that should be tried first when binding local Candidate sockets for this Component.

  minPort - the port number where we should first try to bind before moving to the next one (i.e.

  maxPort - the maximum port number where we should try binding before giving up and throwing an exception.

  keepAliveStrategy - the keep-alive strategy, which dictates which candidates pairs are going to be kept alive.

• createComponent

   Component createComponent(IceMediaStream stream, int preferredPort, int minPort, int maxPort, KeepAliveStrategy keepAliveStrategy, boolean useComponentSocket)

  Creates a new Component for the specified stream and allocates potentially all local candidates that should belong to it. If 0, 0, 0 are specified for preferred, min and max port, an ephemeral port will be used instead.

  Parameters:

  stream - the IceMediaStream that the new Component should belong to.

  preferredPort - the port number that should be tried first when binding local Candidate sockets for this Component.

  minPort - the port number where we should first try to bind before moving to the next one (i.e.

  maxPort - the maximum port number where we should try binding before giving up and throwing an exception.

  keepAliveStrategy - the keep-alive strategy, which dictates which candidates pairs are going to be kept alive.

  useComponentSocket - whether to use the component socket mode (in which case the socket is available through the Component directly), or not (in which case the socket is available through the selected CandidatePair).

• createComponent

   Component createComponent(IceMediaStream stream, KeepAliveStrategy keepAliveStrategy, boolean useComponentSocket)

  Creates a new Component for the specified stream and allocates potentially all local candidates that should belong to it. If dynamic ports are enabled, an ephemeral port will be used.

  Parameters:

  stream - the IceMediaStream that the new Component should belong to.

  keepAliveStrategy - the keep-alive strategy, which dictates which candidates pairs are going to be kept alive.

  useComponentSocket - whether to use the component socket mode (in which case the socket is available through the Component directly), or not (in which case the socket is available through the selected CandidatePair).

• startCandidateTrickle

   void startCandidateTrickle(TrickleCallback trickleCallback)

  Starts an asynchronous(?) harvest across all components and reports newly discovered candidates to trickleCallback.

  Parameters:

  trickleCallback - the callback that will be notified for all newly discovered candidates.

• startConnectivityEstablishment

   void startConnectivityEstablishment()

  Initializes all stream check lists and begins the checks.

• isStarted

   boolean isStarted()

  Indicates whether this Agent is currently in the process of running connectivity checks and establishing connectivity. Connectivity establishment is considered to have started after both Agents 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.

  Note that an 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.

• isOver

   boolean isOver()

  Indicates whether this Agent has finished ICE processing.

• addStateChangeListener

   void addStateChangeListener(PropertyChangeListener l)

  Adds l to the list of listeners tracking changes of the IceProcessingState of this Agent

  Parameters:

  l - the listener to register.

• removeStateChangeListener

   void removeStateChangeListener(PropertyChangeListener l)

  Removes l from the list of listeners tracking changes of the IceProcessingState of this Agent

  Parameters:

  l - the listener to remove.

• addCandidateHarvester

   void addCandidateHarvester(CandidateHarvester harvester)

  Adds harvester to the list of harvesters that this agent will use when gathering Candidates.

  Parameters:

  harvester - a CandidateHarvester that this agent should use when gathering candidates.

• getLocalUfrag

   String getLocalUfrag()

  Returns that user name that should be advertised in session descriptions containing ICE data from this agent.

• getLocalPassword

   String getLocalPassword()

  Returns that password that should be advertised in session descriptions containing ICE data from this agent.

• generateLocalUserName

   String generateLocalUserName(String media)

  Returns the user name that this Agent 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.

  Parameters:

  media - media name that we want to generate local username for.

• generateRemoteUserName

   String generateRemoteUserName(String media)

  Returns the user name that we should expect a peer Agent 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.

  Parameters:

  media - media name that we want to generate local username for.

• generateLocalUserName

   String generateLocalUserName(RemoteCandidate remoteCandidate, LocalCandidate localCandidate)

  Returns the user name that this Agent should use in connectivity checks for outgoing Binding Requests in a Google Talk session.

  Parameters:

  remoteCandidate - remote candidate

  localCandidate - local candidate

• generateRemoteUserName

   String generateRemoteUserName(RemoteCandidate remoteCandidate, LocalCandidate localCandidate)

  Returns the user name that we should expect a peer Agent to use in connectivity checks for Binding Requests its sending our way in a Google Talk session.

  Parameters:

  remoteCandidate - remote candidate

  localCandidate - local candidate

• getStream

   IceMediaStream getStream(String name)

  Returns the IceMediaStream with the specified name or null if no such stream has been registered with this Agent yet.

  Parameters:

  name - the name of the stream that we'd like to obtain a reference to.

• getStreamNames

   List<String> getStreamNames()

  Returns a List containing the names of all currently registered media streams.

• getStreams

   List<IceMediaStream> getStreams()

  Returns a List containing all IceMediaStreams currently registered with this agent.

• getStreamCount

   int getStreamCount()

  Returns the number of IceMediaStreams currently registered with this agent.

• toString

   String toString()

  Returns a String representation of this agent.

• setControlling

   void setControlling(boolean isControlling)

  Specifies whether this agent has the controlling role in an ICE exchange.

  Parameters:

  isControlling - true if this is to be the controlling Agent and false otherwise.

• removeStream

   void removeStream(IceMediaStream stream)

  Removes stream and all its child Components and Candidates from the this agent and releases all resources that they had allocated (like sockets for example)

  Parameters:

  stream - the Component we'd like to remove and free.

• findLocalCandidate

   LocalCandidate findLocalCandidate(TransportAddress address)

  Returns the local LocalCandidate with the specified address if it belongs to any of this Agent's streams or null if it doesn't.

  Parameters:

  address - the TransportAddress we are looking for.

• findLocalCandidate

   LocalCandidate findLocalCandidate(TransportAddress address, LocalCandidate base)

  Returns the local LocalCandidate with the specified address if it belongs to any of this Agent's streams or null if it doesn't. If base is also specified, tries to find a candidate whose base matches base.

  Parameters:

  address - the TransportAddress we are looking for.

  base - an optional base to match.

• findRemoteCandidate

   RemoteCandidate findRemoteCandidate(TransportAddress remoteAddress)

  Returns the remote Candidate with the specified remoteAddress if it belongs to any of this Agent's streams or null if it doesn't.

  Parameters:

  remoteAddress - the TransportAddress we are looking for.

• findCandidatePair

   CandidatePair findCandidatePair(TransportAddress localAddress, TransportAddress remoteAddress)

  Returns the CandidatePair with the specified remote and local addresses or null if neither of the CheckLists in this Agent's streams contain such a pair.

  Parameters:

  localAddress - the local TransportAddress of the pair we are looking for.

  remoteAddress - the remote TransportAddress of the pair we are looking for.

• findCandidatePair

   CandidatePair findCandidatePair(String localUFrag, String remoteUFrag)

  Returns the CandidatePair with the specified remote and local addresses or null if neither of the CheckLists in this Agent's streams contain such a pair.

  Parameters:

  localUFrag - local user fragment

  remoteUFrag - remote user fragment

• nominate

   synchronized void nominate(CandidatePair pair)

  Raises pair's nomination flag and schedules a triggered check. Applications only need to use this method if they disable this Agent's internal nomination and implement their own nominator and turn off nominations in this agent.

  Parameters:

  pair - the CandidatePair that we'd like to nominate and that we'd like to schedule a triggered check for.

• getNominationStrategy

   NominationStrategy getNominationStrategy()

  Returns the NominationStrategy that we use in order to decide if and when we should nominate valid pairs.

• setNominationStrategy

   void setNominationStrategy(NominationStrategy strategy)

  Specifies the NominationStrategy that we should use in order to decide if and when we should nominate valid pairs.

  Parameters:

  strategy - the strategy that we'd like to use for nominating valid CandidatePairs.

• setTa

   void setTa(long taValue)

  Lets the application specify a custom value for the Ta timer so that we don't calculate one.

  Parameters:

  taValue - the value of the Ta timer that the application would like us to use rather than calculate one.

• free

   void free()

  Prepares this Agent for garbage collection by ending all related processes and freeing its IceMediaStreams, Components and Candidates. This method will also place the agent in the terminated state in case it wasn't already there.

• getSelectedLocalCandidate

   LocalCandidate getSelectedLocalCandidate(String streamName)

  Returns the selected local candidate for this Agent.

  Parameters:

  streamName - The stream name (AUDIO, VIDEO);

• getSelectedRemoteCandidate

   RemoteCandidate getSelectedRemoteCandidate(String streamName)

  Returns the selected remote candidate for this Agent.

  Parameters:

  streamName - The stream name (AUDIO, VIDEO);

• isTrickling

   boolean isTrickling()

  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.

• setTrickling

   void setTrickling(boolean 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.

  Parameters:

  trickle - false if this agent is configured to perform all harvesting when components are being added and false otherwise.

• getHarvestingTime

   long getHarvestingTime(String harvesterName)

  Returns the harvesting time (in ms) for the harvester given in parameter.

  Parameters:

  harvesterName - The class name if the harvester.

• getHarvestCount

   int getHarvestCount(String harvesterName)

  Returns the number of harvests that a harvester with a specific class name has completed so far.

  Parameters:

  harvesterName - the class name of the harvester for which the number of completed harvests is to be returned

• getTotalHarvestingTime

   long getTotalHarvestingTime()

  Returns the combined harvesting time for all harvesters in this agent.

• getHarvestCount

   int getHarvestCount()

  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, for example, if some harvesters were disabled for inefficiency.

• setLoggingLevel

   void setLoggingLevel(Level level)

  Sets the logging level for this Agent and its components.

  Parameters:

  level - the level to set.

• getLoggingLevel

   Level getLoggingLevel()

  Gets the logging level for this Agent and its components.