-
Notifications
You must be signed in to change notification settings - Fork 668
/
MulticastChannel.java
223 lines (216 loc) · 11.6 KB
/
MulticastChannel.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
/*
* Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.nio.channels;
import java.io.IOException;
import java.net.InetAddress;
import java.net.NetworkInterface;
import java.net.ProtocolFamily;
import java.net.StandardProtocolFamily;
import java.net.StandardSocketOptions;
/**
* A network channel that supports Internet Protocol (IP) multicasting.
*
* <p> IP multicasting is the transmission of IP datagrams to members of
* a <em>group</em> that is zero or more hosts identified by a single destination
* address.
*
* <p> In the case of a channel to an {@link StandardProtocolFamily#INET IPv4} socket,
* the underlying operating system optionally supports
* <a href="http://www.ietf.org/rfc/rfc2236.txt"> <i>RFC 2236: Internet Group
* Management Protocol, Version 2 (IGMPv2)</i></a>. When IGMPv2 is supported then
* the operating system may additionally support source filtering as specified by
* <a href="http://www.ietf.org/rfc/rfc3376.txt"> <i>RFC 3376: Internet Group
* Management Protocol, Version 3 (IGMPv3)</i></a>.
* For channels to an {@link StandardProtocolFamily#INET6 IPv6} socket, the equivalent
* standards are <a href="http://www.ietf.org/rfc/rfc2710.txt"> <i>RFC 2710:
* Multicast Listener Discovery (MLD) for IPv6</i></a> and <a
* href="http://www.ietf.org/rfc/rfc3810.txt"> <i>RFC 3810: Multicast Listener
* Discovery Version 2 (MLDv2) for IPv6</i></a>.
*
* <p> The {@link #join(InetAddress, NetworkInterface)} method is used to
* join a group and receive all multicast datagrams sent to the group. A channel
* may join several multicast groups and may join the same group on several
* {@link NetworkInterface interfaces}. Membership is dropped by invoking the {@link
* MembershipKey#drop drop} method on the returned {@link MembershipKey}. If the
* underlying platform supports source filtering then the {@link MembershipKey#block
* block} and {@link MembershipKey#unblock unblock} methods can be used to block or
* unblock multicast datagrams from particular source addresses.
*
* <p> The {@link #join(InetAddress, NetworkInterface, InetAddress)} method
* is used to begin receiving datagrams sent to a group whose source address matches
* a given source address. This method throws {@link UnsupportedOperationException}
* if the underlying platform does not support source filtering. Membership is
* <em>cumulative</em> and this method may be invoked again with the same group
* and interface to allow receiving datagrams from other source addresses. The
* method returns a {@link MembershipKey} that represents membership to receive
* datagrams from the given source address. Invoking the key's {@link
* MembershipKey#drop drop} method drops membership so that datagrams from the
* source address can no longer be received.
*
* <h2>Platform dependencies</h2>
*
* The multicast implementation is intended to map directly to the native
* multicasting facility. Consequently, the following items should be considered
* when developing an application that receives IP multicast datagrams:
*
* <ol>
*
* <li><p> The creation of the channel should specify the {@link ProtocolFamily}
* that corresponds to the address type of the multicast groups that the channel
* will join. There is no guarantee that a channel to a socket in one protocol
* family can join and receive multicast datagrams when the address of the
* multicast group corresponds to another protocol family. For example, it is
* implementation specific if a channel to an {@link StandardProtocolFamily#INET6 IPv6}
* socket can join an {@link StandardProtocolFamily#INET IPv4} multicast group and receive
* multicast datagrams sent to the group. </p></li>
*
* <li><p> The channel's socket should be bound to the {@link
* InetAddress#isAnyLocalAddress wildcard} address. If the socket is bound to
* a specific address, rather than the wildcard address then it is implementation
* specific if multicast datagrams are received by the socket. </p></li>
*
* <li><p> The {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} option should be
* enabled prior to {@link NetworkChannel#bind binding} the socket. This is
* required to allow multiple members of the group to bind to the same
* address. </p></li>
*
* </ol>
*
* <p> <b>Usage Example:</b>
* <pre>
* // join multicast group on this interface, and also use this
* // interface for outgoing multicast datagrams
* NetworkInterface ni = NetworkInterface.getByName("hme0");
*
* DatagramChannel dc = DatagramChannel.open(StandardProtocolFamily.INET)
* .setOption(StandardSocketOptions.SO_REUSEADDR, true)
* .bind(new InetSocketAddress(5000))
* .setOption(StandardSocketOptions.IP_MULTICAST_IF, ni);
*
* InetAddress group = InetAddress.getByName("225.4.5.6");
*
* MembershipKey key = dc.join(group, ni);
* </pre>
*
* @since 1.7
*/
// 组播通道接口，由UDP-Socket通道实现
public interface MulticastChannel extends NetworkChannel {
/**
* Closes this channel.
*
* <p> If the channel is a member of a multicast group then the membership
* is {@link MembershipKey#drop dropped}. Upon return, the {@link
* MembershipKey membership-key} will be {@link MembershipKey#isValid
* invalid}.
*
* <p> This method otherwise behaves exactly as specified by the {@link
* Channel} interface.
*
* @throws IOException If an I/O error occurs
*/
// 关闭组播通道
@Override
void close() throws IOException;
/**
* Joins a multicast group to begin receiving all datagrams sent to the group,
* returning a membership key.
*
* <p> If this channel is currently a member of the group on the given
* interface to receive all datagrams then the membership key, representing
* that membership, is returned. Otherwise this channel joins the group and
* the resulting new membership key is returned. The resulting membership key
* is not {@link MembershipKey#sourceAddress source-specific}.
*
* <p> A multicast channel may join several multicast groups, including
* the same group on more than one interface. An implementation may impose a
* limit on the number of groups that may be joined at the same time.
*
* @param group The multicast address to join
* @param interf The network interface on which to join the group
*
* @return The membership key
*
* @throws IllegalArgumentException If the group parameter is not a {@link InetAddress#isMulticastAddress
* multicast} address, or the group parameter is an address type
* that is not supported by this channel
* @throws IllegalStateException If the channel already has source-specific membership of the
* group on the interface
* @throws UnsupportedOperationException If the channel's socket is not an Internet Protocol socket, or
* the platform does not support multicasting
* @throws ClosedChannelException If this channel is closed
* @throws IOException If an I/O error occurs
* @throws SecurityException If a security manager is set, and its
* {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
* method denies access to the multiast group
*/
/*
* 将当前组播Socket加入到group处的组播小组中，后续它将接收到该小组中的数据；interf是用来接收消息的网络接口(网卡)
* 注：不会过滤消息
*/
MembershipKey join(InetAddress group, NetworkInterface interf) throws IOException;
/**
* Joins a multicast group to begin receiving datagrams sent to the group
* from a given source address.
*
* <p> If this channel is currently a member of the group on the given
* interface to receive datagrams from the given source address then the
* membership key, representing that membership, is returned. Otherwise this
* channel joins the group and the resulting new membership key is returned.
* The resulting membership key is {@link MembershipKey#sourceAddress
* source-specific}.
*
* <p> Membership is <em>cumulative</em> and this method may be invoked
* again with the same group and interface to allow receiving datagrams sent
* by other source addresses to the group.
*
* @param group The multicast address to join
* @param interf The network interface on which to join the group
* @param source The source address
*
* @return The membership key
*
* @throws IllegalArgumentException If the group parameter is not a {@link
* InetAddress#isMulticastAddress multicast} address, the
* source parameter is not a unicast address, the group
* parameter is an address type that is not supported by this channel,
* or the source parameter is not the same address type as the group
* @throws IllegalStateException If the channel is currently a member of the group on the given
* interface to receive all datagrams
* @throws UnsupportedOperationException If the channel's socket is not an Internet Protocol socket, or
* source filtering is not supported, or the platform does not
* support multicasting
* @throws ClosedChannelException If this channel is closed
* @throws IOException If an I/O error occurs
* @throws SecurityException If a security manager is set, and its
* {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
* method denies access to the multiast group
*/
/*
* 将当前组播Socket加入到group处的组播小组中，后续它将接收到该小组中的数据；interf是用来接收消息的网络接口(网卡)
* 注：如果source不为null，则会过滤消息，即只处理源地址是source的那些数据包
*/
MembershipKey join(InetAddress group, NetworkInterface interf, InetAddress source) throws IOException;
}