net.java.sip.communicator.service.netaddr
Interface NetworkAddressManagerService

All Known Implementing Classes:

NetworkAddressManagerServiceImpl

public interface NetworkAddressManagerService

The NetworkAddressManagerService takes care of problems such as

Author:

Emil Ivov

Field Summary

static int	BIND_RETRIES_DEFAULT_VALUE The default number of binds that a NetworkAddressManagerService implementation should execute in case a port is already bound to (each retry would be on a different port).
static String	BIND_RETRIES_PROPERTY_NAME The name of the property containing number of binds that a NetworkAddressManagerService implementation should execute in case a port is already bound to (each retry would be on a different port).

Method Summary

void	addNetworkConfigurationChangeListener(NetworkConfigurationChangeListener listener) Adds new NetworkConfigurationChangeListener which will be informed for network configuration changes.
DatagramSocket	createDatagramSocket(InetAddress laddr, int preferredPort, int minPort, int maxPort) Creates a DatagramSocket and binds it to on the specified localAddress and a port in the range specified by the minPort and maxPort parameters.
org.ice4j.ice.Agent	createIceAgent() Creates and returns an ICE agent that a protocol could use for the negotiation of media transport addresses.
org.ice4j.ice.IceMediaStream	createIceStream(int rtpPort, String streamName, org.ice4j.ice.Agent agent) Creates an IceMediaStrean and adds to it an RTP and and RTCP component, which also implies running the currently installed harvesters so that they would.
org.ice4j.ice.harvest.StunCandidateHarvester	discoverStunServer(String domainName, byte[] userName, byte[] password) Tries to discover a TURN or a STUN server for the specified domainName.
byte[]	getHardwareAddress(NetworkInterface iface) Returns the hardware address (i.e.
InetAddress	getLocalHost(InetAddress intendedDestination) Returns an InetAddress instance that represents the localhost, and that a socket can bind upon or distribute to peers as a contact address.
InetSocketAddress	getPublicAddressFor(InetAddress intendedDestination, int port) Tries to obtain a mapped/public address for the specified port.
void	removeNetworkConfigurationChangeListener(NetworkConfigurationChangeListener listener) Remove NetworkConfigurationChangeListener.

Field Detail

BIND_RETRIES_DEFAULT_VALUE

static final int BIND_RETRIES_DEFAULT_VALUE

The default number of binds that a NetworkAddressManagerService implementation should execute in case a port is already bound to (each retry would be on a different port).

See Also:

Constant Field Values

BIND_RETRIES_PROPERTY_NAME

static final String BIND_RETRIES_PROPERTY_NAME

The name of the property containing number of binds that a NetworkAddressManagerService implementation should execute in case a port is already bound to (each retry would be on a different port).

See Also:

Constant Field Values

Method Detail

getLocalHost

InetAddress getLocalHost(InetAddress intendedDestination)

Returns an InetAddress instance that represents the localhost, and that a socket can bind upon or distribute to peers as a contact address.

This method tries to make for the ambiguity in the implementation of the InetAddress.getLocalHost() method. (see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4665037).

To put it briefly, the issue is about choosing a local source address to bind to or to distribute to peers. It is possible and even quite probable to expect that a machine may dispose with multiple addresses and each of them may be valid for a specific destination. Example cases include:

1) A dual stack IPv6/IPv4 box.
2) A double NIC box with a leg on the Internet and another one in a private LAN
3) In the presence of a virtual interface over a VPN or a MobileIP(v6) tunnel.

In all such cases a source local address needs to be chosen according to the intended destination and after consulting the local routing table.

Parameters:

intendedDestination - the address of the destination that we'd like to access through the local address that we are requesting.

Returns:

an InetAddress instance representing the local host, and that a socket can bind upon or distribute to peers as a contact address.

getPublicAddressFor

InetSocketAddress getPublicAddressFor(InetAddress intendedDestination,
                                      int port)
                                      throws IOException,
                                             BindException

Tries to obtain a mapped/public address for the specified port. If the STUN lib fails, tries to retrieve localhost, if that fails too, returns null.

Parameters:

intendedDestination - the destination that we'd like to use this address with.

port - the port whose mapping we are interested in.

Returns:

a public address corresponding to the specified port or null if all attempts to retrieve such an address have failed.

Throws:

IOException - if an error occurs while the underlying resolver lib is using sockets.

BindException - if the port is already in use.

getHardwareAddress

byte[] getHardwareAddress(NetworkInterface iface)

Returns the hardware address (i.e. MAC address) of the specified interface name.

Parameters:

iface - the NetworkInterface

Returns:

array of bytes representing the layer 2 address

createDatagramSocket

DatagramSocket createDatagramSocket(InetAddress laddr,
                                    int preferredPort,
                                    int minPort,
                                    int maxPort)
                                    throws IllegalArgumentException,
                                           IOException,
                                           BindException

Creates a DatagramSocket and binds it to on the specified localAddress and a port in the range specified by the minPort and maxPort parameters. We first try to bind the newly created socket on the preferredPort port number and then proceed incrementally upwards until we succeed or reach the bind retries limit. If we reach the maxPort port number before the bind retries limit, we will then start over again at minPort and keep going until we run out of retries.

Parameters:

laddr - the address that we'd like to bind the socket on.

preferredPort - the port number that we should try to bind to first.

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

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

Returns:

the newly created DatagramSocket.

Throws:

IllegalArgumentException - if either minPort or maxPort is not a valid port number.

IOException - if an error occurs while the underlying resolver lib is using sockets.

BindException - if we couldn't find a free port between minPort and maxPort before reaching the maximum allowed number of retries.

addNetworkConfigurationChangeListener

void addNetworkConfigurationChangeListener(NetworkConfigurationChangeListener listener)

Adds new NetworkConfigurationChangeListener which will be informed for network configuration changes.

Parameters:

listener - the listener.

removeNetworkConfigurationChangeListener

void removeNetworkConfigurationChangeListener(NetworkConfigurationChangeListener listener)

Remove NetworkConfigurationChangeListener.

Parameters:

listener - the listener.

createIceAgent

org.ice4j.ice.Agent createIceAgent()

Creates and returns an ICE agent that a protocol could use for the negotiation of media transport addresses. One ICE agent should only be used for a single session negotiation.

Returns:

the newly created ICE Agent.

discoverStunServer

org.ice4j.ice.harvest.StunCandidateHarvester discoverStunServer(String domainName,
                                                                byte[] userName,
                                                                byte[] password)

Tries to discover a TURN or a STUN server for the specified domainName. The method would first try to discover a TURN server and then fall back to STUN only. In both cases we would only care about a UDP transport.

Parameters:

domainName - the domain name that we are trying to discover a TURN server for.

userName - the name of the user we'd like to use when connecting to a TURN server (we won't be using credentials in case we only have a STUN server).

password - the password that we'd like to try when connecting to a TURN server (we won't be using credentials in case we only have a STUN server).

Returns:

A StunCandidateHarvester corresponding to the TURN or STUN server we discovered or null if there were no such records for the specified domainName

createIceStream

org.ice4j.ice.IceMediaStream createIceStream(int rtpPort,
                                             String streamName,
                                             org.ice4j.ice.Agent agent)
                                             throws IllegalArgumentException,
                                                    IOException,
                                                    BindException

Creates an IceMediaStrean and adds to it an RTP and and RTCP component, which also implies running the currently installed harvesters so that they would.

Parameters:

rtpPort - the port that we should try to bind the RTP component on (the RTCP one would automatically go to rtpPort + 1)

streamName - the name of the stream to create

agent - the Agent that should create the stream.

Returns:

the newly created IceMediaStream.

Throws:

IllegalArgumentException - if rtpPort is not a valid port number.

IOException - if an error occurs while the underlying resolver is using sockets.

BindException - if we couldn't find a free port between within the default number of retries.