1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty5.channel.socket;
17
18 import io.netty5.channel.Channel;
19 import io.netty5.channel.ChannelOption;
20 import io.netty5.util.concurrent.Future;
21
22 import java.net.InetAddress;
23 import java.net.NetworkInterface;
24
25 /**
26 * A UDP/IP {@link Channel}.
27 *
28 * <h3>Available options</h3>
29 *
30 * In addition to the options provided by {@link Channel},
31 * {@link DatagramChannel} allows the following options in the option map:
32 *
33 * <table border="1" cellspacing="0" cellpadding="6">
34 * <tr>
35 * <th>{@link ChannelOption}</th>
36 * <th>{@code INET}</th>
37 * <th>{@code INET6}</th>
38 * <th>{@code UNIX}</th>
39 * </tr><tr>
40 * <td>{@link ChannelOption#DATAGRAM_CHANNEL_ACTIVE_ON_REGISTRATION}</td><td>X</td><td>X</td><td>-</td>
41 * </tr><tr>
42 * <td>{@link ChannelOption#SO_BROADCAST}</td><td>X</td><td>X</td><td>-</td>
43 * </tr><tr>
44 * <td>{@link ChannelOption#SO_REUSEADDR}</td><td>X</td><td>X</td><td>-</td>
45 * </tr><tr>
46 * <td>{@link ChannelOption#SO_RCVBUF}</td><td>X</td><td>X</td><td>X</td>
47 * </tr><tr>
48 * <td>{@link ChannelOption#SO_SNDBUF}</td><td>X</td><td>X</td><td>X</td>
49 * </tr><tr>
50 * <td>{@link ChannelOption#IP_MULTICAST_LOOP_DISABLED}</td><td>X</td><td>X</td><td>-</td>
51 * </tr><tr>
52 * <td>{@link ChannelOption#IP_MULTICAST_IF}</td><td>X</td><td>X</td><td>-</td>
53 * </tr><tr>
54 * <td>{@link ChannelOption#IP_MULTICAST_TTL}</td><td>X</td><td>X</td><td>-</td>
55 * </tr><tr>
56 * <td>{@link ChannelOption#IP_TOS}</td><td>X</td><td>X</td><td>-</td>
57 * </tr>
58 * </table>
59 */
60 public interface DatagramChannel extends Channel {
61
62 /**
63 * Return {@code true} if the {@link DatagramChannel} is connected to the remote peer.
64 */
65 boolean isConnected();
66
67 /**
68 * Joins a multicast group and notifies the {@link Future} once the operation completes.
69 * <p>
70 * If the underlying implementation does not support this operation it will return a {@link Future} which
71 * is failed with an {@link UnsupportedOperationException}.
72 *
73 * @param multicastAddress the multicast group address.
74 * @return a {@link Future} which is notified once the operation completes.
75 */
76 Future<Void> joinGroup(InetAddress multicastAddress);
77
78 /**
79 * Joins the specified multicast group at the specified interface and notifies the {@link Future}
80 * once the operation completes.
81 *
82 * <p>
83 * If the underlying implementation does not support this operation it will return a {@link Future} which
84 * is failed with an {@link UnsupportedOperationException}.
85 *
86 * @param multicastAddress the multicast group address.
87 * @param networkInterface the interface to use.
88 * @param source the source address (might be {@code null}).
89 * @return a {@link Future} which is notified once the operation completes.
90 */
91 Future<Void> joinGroup(InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source);
92
93 /**
94 * Leaves a multicast group and notifies the {@link Future} once the operation completes.
95 *
96 * <p>
97 * If the underlying implementation does not support this operation it will return a {@link Future} which
98 * is failed with an {@link UnsupportedOperationException}.
99 *
100 * @param multicastAddress the multicast group address.
101 * @return a {@link Future} which is notified once the operation completes.
102 */
103 Future<Void> leaveGroup(InetAddress multicastAddress);
104
105 /**
106 * Leave the specified multicast group at the specified interface using the specified source and notifies
107 * the {@link Future} once the operation completes.
108 *
109 * <p>
110 * If the underlying implementation does not support this operation it will return a {@link Future} which
111 * is failed with an {@link UnsupportedOperationException}.
112 *
113 * @param multicastAddress the multicast group address.
114 * @param networkInterface the interface to use.
115 * @param source the source address (might be {@code null}).
116 * @return a {@link Future} which is notified once the operation completes.
117 */
118 Future<Void> leaveGroup(InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source);
119
120 /**
121 * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface and notifies
122 * the {@link Future} once the operation completes.
123 *
124 * <p>
125 * If the underlying implementation does not support this operation it will return a {@link Future} which
126 * is failed with an {@link UnsupportedOperationException}.
127 *
128 * @param multicastAddress the multicast group address.
129 * @param networkInterface the interface to use.
130 * @param sourceToBlock the source address.
131 * @return a {@link Future} which is notified once the operation completes.
132 */
133 Future<Void> block(InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress sourceToBlock);
134
135 /**
136 * Block the given sourceToBlock address for the given multicastAddress and notifies the {@link Future} once
137 * the operation completes.
138 *
139 * <p>
140 * If the underlying implementation does not support this operation it will return a {@link Future} which
141 * is failed with an {@link UnsupportedOperationException}.
142 *
143 * @param multicastAddress the multicast group address.
144 * @param sourceToBlock the source address.
145 * @return a {@link Future} which is notified once the operation completes.
146 */
147 Future<Void> block(InetAddress multicastAddress, InetAddress sourceToBlock);
148 }