* 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. *
* @param intendedDestination the address of the destination that we'd like * to access through the local address that we are requesting. * * @return an InetAddress instance representing the local host, and that * a socket can bind upon or distribute to peers as a contact address. */ public InetAddress getLocalHost(InetAddress intendedDestination); /** * 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. * * @param intendedDestination the destination that we'd like to use this * address with. * @param port the port whose mapping we are interested in. * * @return 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. * @throws BindException if the port is already in use. */ public InetSocketAddress getPublicAddressFor( InetAddress intendedDestination, int port) throws 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. * * @param laddr the address that we'd like to bind the socket on. * @param preferredPort the port number that we should try to bind to first. * @param minPort the port number where we should first try to bind before * moving to the next one (i.e. minPort + 1) * @param maxPort the maximum port number where we should try binding * before giving up and throwinG an exception. * * @return the newly created DatagramSocket. * * @throws IllegalArgumentException if either minPort or * maxPort is not a valid port number. * @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 * minPort and maxPort before reaching the maximum allowed * number of retries. */ public DatagramSocket createDatagramSocket(InetAddress laddr, int preferredPort, int minPort, int maxPort) throws IllegalArgumentException, IOException, BindException; /** * Adds new NetworkConfigurationChangeListener which will * be informed for network configuration changes. * @param listener the listener. */ public void addNetworkConfigurationChangeListener( NetworkConfigurationChangeListener listener); /** * Remove NetworkConfigurationChangeListener. * @param listener the listener. */ public void removeNetworkConfigurationChangeListener( NetworkConfigurationChangeListener listener); /** * 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. * * @return the newly created ICE Agent. */ public Agent createIceAgent(); /** * 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. * * @param domainName the domain name that we are trying to discover a * TURN server for. * @param 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). * @param 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). * * @return A {@link StunCandidateHarvester} corresponding to the TURN or * STUN server we discovered or null if there were no such records * for the specified domainName */ public StunCandidateHarvester discoverStunServer(String domainName, byte[] userName, byte[] password); /** * 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. * * @param rtpPort the port that we should try to bind the RTP component on * (the RTCP one would automatically go to rtpPort + 1) * @param streamName the name of the stream to create * @param agent the Agent that should create the stream. * *@return the newly created IceMediaStream. * * @throws IllegalArgumentException if rtpPort is not a valid port * number. * @throws IOException if an error occurs while the underlying resolver * is using sockets. * @throws BindException if we couldn't find a free port between within the * default number of retries. */ public IceMediaStream createStream( int rtpPort, String streamName, Agent agent) throws IllegalArgumentException, IOException, BindException; }