1 /*
2 * Copyright (C) 2013 4th Line GmbH, Switzerland
3 *
4 * The contents of this file are subject to the terms of either the GNU
5 * Lesser General Public License Version 2 or later ("LGPL") or the
6 * Common Development and Distribution License Version 1 or later
7 * ("CDDL") (collectively, the "License"). You may not use this file
8 * except in compliance with the License. See LICENSE.txt for more
9 * information.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
14 */
15
16 package org.fourthline.cling.transport.spi;
17
18 import java.net.InetAddress;
19 import java.net.NetworkInterface;
20 import java.util.Iterator;
21
22 /**
23 * Configuration utility for network interfaces and addresses.
24 * <p>
25 * An implementation has to be thread-safe.
26 * </p>
27 *
28 * @author Christian Bauer
29 */
30 public interface NetworkAddressFactory {
31
32 // An implementation can honor these if it wants (the default does)
33 public static final String SYSTEM_PROPERTY_NET_IFACES = "org.fourthline.cling.network.useInterfaces";
34 public static final String SYSTEM_PROPERTY_NET_ADDRESSES = "org.fourthline.cling.network.useAddresses";
35
36
37 /**
38 * @return The UDP multicast group to join.
39 */
40 public InetAddress getMulticastGroup();
41
42 /**
43 * @return The UDP multicast port to listen on.
44 */
45 public int getMulticastPort();
46
47 /**
48 * @return The TCP (HTTP) stream request port to listen on.
49 */
50 public int getStreamListenPort();
51
52 /**
53 * The caller might <code>remove()</code> an interface if initialization fails.
54 *
55 * @return The local network interfaces on which multicast groups will be joined.
56 */
57 public Iterator<NetworkInterface> getNetworkInterfaces();
58
59 /**
60 * The caller might <code>remove()</code> an address if initialization fails.
61 *
62 * @return The local addresses of the network interfaces bound to
63 * sockets listening for unicast datagrams and TCP requests.
64 */
65 public Iterator<InetAddress> getBindAddresses();
66
67 /**
68 * @return <code>true</code> if there is at least one usable network interface and bind address.
69 */
70 public boolean hasUsableNetwork();
71
72 /**
73 * @return The network prefix length of this address or <code>null</code>.
74 */
75 public Short getAddressNetworkPrefixLength(InetAddress inetAddress);
76
77 /**
78 * @param inetAddress An address of a local network interface.
79 * @return The MAC hardware address of the network interface or <code>null</code> if no
80 * hardware address could be obtained.
81 */
82 public byte[] getHardwareAddress(InetAddress inetAddress);
83
84 /**
85 * @param inetAddress An address of a local network interface.
86 * @return The broadcast address of the network (interface) or <code>null</code> if no
87 * broadcast address could be obtained.
88 */
89 public InetAddress getBroadcastAddress(InetAddress inetAddress);
90
91 /**
92 * Best-effort attempt finding a reachable local address for a given remote host.
93 * <p>
94 * This method is called whenever a multicast datagram has been received. We need to be
95 * able to communicate with the sender using UDP unicast and we need to tell the sender
96 * how we are reachable with TCP requests. We need a local address that is in the same
97 * subnet as the senders address, that is reachable from the senders point of view.
98 * </p>
99 *
100 * @param networkInterface The network interface to examine.
101 * @param isIPv6 True if the given remote address is an IPv6 address.
102 * @param remoteAddress The remote address for which to find a local address in the same subnet.
103 * @return A local address that is reachable from the given remote address.
104 * @throws IllegalStateException If no local address reachable by the remote address has been found.
105 */
106 public InetAddress getLocalAddress(NetworkInterface networkInterface,
107 boolean isIPv6,
108 InetAddress remoteAddress) throws IllegalStateException;
109
110 /**
111 * For debugging, logs all "usable" network interface(s) details with INFO level.
112 */
113 public void logInterfaceInformation();
114 }