1 /*
  2  * Copyright (c) 1995, 2021, Oracle and/or its affiliates. All rights reserved.
  3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  4  *
  5  * This code is free software; you can redistribute it and/or modify it
  6  * under the terms of the GNU General Public License version 2 only, as
  7  * published by the Free Software Foundation.  Oracle designates this
  8  * particular file as subject to the "Classpath" exception as provided
  9  * by Oracle in the LICENSE file that accompanied this code.
 10  *
 11  * This code is distributed in the hope that it will be useful, but WITHOUT
 12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 14  * version 2 for more details (a copy is included in the LICENSE file that
 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.net;
 27 
 28 import java.io.IOException;
 29 import java.nio.channels.DatagramChannel;
 30 import java.nio.channels.MulticastChannel;
 31 
 32 /**
 33  * A {@code MulticastSocket} is a datagram socket that is
 34  * convenient for sending and receiving IP multicast datagrams.
 35  * The {@code MulticastSocket} constructors create a socket
 36  * with appropriate socket options enabled that make
 37  * it suitable for receiving multicast datagrams.
 38  * The {@code MulticastSocket} class additionally defines
 39  * convenient setter and getter methods for socket options
 40  * that are commonly used by multicasting applications.
 41  * <P>
 42  * Joining one or more multicast groups makes it possible to
 43  * receive multicast datagrams sent to these groups.
 44  * <P>
 45  * An IPv4 multicast group is specified by a class D IP address
 46  * and by a standard UDP port number. Class D IP addresses
 47  * are in the range {@code 224.0.0.0} to {@code 239.255.255.255},
 48  * inclusive. The address 224.0.0.0 is reserved and should not be used.
 49  * <P>
 50  * One would join a multicast group by first creating a MulticastSocket
 51  * with the desired port, then invoking the
 52  * <CODE>joinGroup</CODE> method, specifying the group address and
 53  * the network interface through which multicast datagrams will be
 54  * received:
 55  * <PRE>{@code
 56  * // join a Multicast group and send the group salutations
 57  * ...
 58  * String msg = "Hello";
 59  * InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
 60  * InetSocketAddress group = new InetSocketAddress(mcastaddr, 6789);
 61  * NetworkInterface netIf = NetworkInterface.getByName("bge0");
 62  * MulticastSocket s = new MulticastSocket(6789);
 63  *
 64  * s.joinGroup(new InetSocketAddress(mcastaddr, 0), netIf);
 65  * byte[] msgBytes = msg.getBytes(StandardCharsets.UTF_8);
 66  * DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length, group);
 67  * s.send(hi);
 68  * // get their responses!
 69  * byte[] buf = new byte[1000];
 70  * DatagramPacket recv = new DatagramPacket(buf, buf.length);
 71  * s.receive(recv);
 72  * ...
 73  * // OK, I'm done talking - leave the group...
 74  * s.leaveGroup(group, netIf);
 75  * }</PRE>
 76  *
 77  * When one sends a message to a multicast group, <B>all</B> subscribing
 78  * recipients to that host and port receive the message (within the
 79  * time-to-live range of the packet, see below). The socket needn't
 80  * be a member of the multicast group to send messages to it.
 81  * <P>
 82  * When a socket subscribes to a multicast group/port, it receives
 83  * datagrams sent by other hosts to the group/port, as do all other
 84  * members of the group and port.  A socket relinquishes membership
 85  * in a group by the leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
 86  * method.
 87  * <B>Multiple MulticastSockets</B> may subscribe to a multicast group
 88  * and port concurrently, and they will all receive group datagrams.
 89  *
 90  * <p> The {@code DatagramSocket} and {@code MulticastSocket}
 91  * classes define convenience methods to set and get several
 92  * socket options. Like {@code DatagramSocket} this class also
 93  * supports the {@link #setOption(SocketOption, Object) setOption}
 94  * and {@link #getOption(SocketOption) getOption} methods to set
 95  * and query socket options.
 96  * <a id="MulticastOptions"></a>The set of supported socket options
 97  * is defined in <a href="DatagramSocket.html#SocketOptions">{@code DatagramSocket}</a>.
 98  * Additional (implementation specific) options may also be supported.
 99  *
100  * @apiNote {@link DatagramSocket} may be used directly for
101  *          sending and receiving multicast datagrams.
102  *          {@link DatagramChannel} implements the {@link MulticastChannel} interface
103  *          and provides an alternative API for sending and receiving multicast datagrams.
104  *          The {@link MulticastChannel} API supports both {@linkplain
105  *          MulticastChannel#join(InetAddress, NetworkInterface) any-source} and
106  *          {@linkplain MulticastChannel#join(InetAddress, NetworkInterface, InetAddress)
107  *          source-specific} multicast. Consider using {@link DatagramChannel} for
108  *          multicasting.
109  *
110  * @author Pavani Diwanji
111  * @since 1.1
112  */
113 public class MulticastSocket extends DatagramSocket {
114 
115     @Override
116     final MulticastSocket delegate() {
117         return (MulticastSocket) super.delegate();
118     }
119 
120     /**
121      * Create a MulticastSocket that delegates to the given delegate if not null.
122      * @param delegate the delegate, can be null.
123      */
124     MulticastSocket(MulticastSocket delegate)  {
125         super(delegate);
126     }
127 
128 
129     /**
130      * Constructs a multicast socket and binds it to any available port
131      * on the local host machine.  The socket will be bound to the
132      * {@link InetAddress#isAnyLocalAddress wildcard} address.
133      *
134      * <p>
135      * If there is a security manager, its {@code checkListen} method is first
136      * called with 0 as its argument to ensure the operation is allowed. This
137      * could result in a SecurityException.
138      * <p>
139      * When the socket is created the
140      * {@link DatagramSocket#setReuseAddress(boolean)} method is called to
141      * enable the SO_REUSEADDR socket option.
142      *
143      * @throws    IOException if an I/O exception occurs while creating the
144      * MulticastSocket
145      * @throws    SecurityException if a security manager exists and its
146      * {@code checkListen} method doesn't allow the operation.
147      * @see SecurityManager#checkListen
148      * @see java.net.DatagramSocket#setReuseAddress(boolean)
149      * @see java.net.DatagramSocketImpl#setOption(SocketOption, Object)
150      */
151     public MulticastSocket() throws IOException {
152         this(new InetSocketAddress(0));
153     }
154 
155     /**
156      * Constructs a multicast socket and binds it to the specified port
157      * on the local host machine. The socket will be bound to the
158      * {@link InetAddress#isAnyLocalAddress wildcard} address.
159      *
160      * <p>If there is a security manager,
161      * its {@code checkListen} method is first called
162      * with the {@code port} argument
163      * as its argument to ensure the operation is allowed.
164      * This could result in a SecurityException.
165      * <p>
166      * When the socket is created the
167      * {@link DatagramSocket#setReuseAddress(boolean)} method is
168      * called to enable the SO_REUSEADDR socket option.
169      *
170      * @param     port port to use
171      * @throws    IOException if an I/O exception occurs
172      *            while creating the MulticastSocket
173      * @throws    SecurityException  if a security manager exists and its
174      *            {@code checkListen} method doesn't allow the operation.
175      * @throws    IllegalArgumentException  if port is  <a href="DatagramSocket.html#PortRange">
176      *            out of range.</a>
177      *
178      * @see       SecurityManager#checkListen
179      * @see       java.net.DatagramSocket#setReuseAddress(boolean)
180      */
181     public MulticastSocket(int port) throws IOException {
182         this(new InetSocketAddress(port));
183     }
184 
185     /**
186      * Creates a multicast socket, bound to the specified local
187      * socket address.
188      * <p>
189      * If the address is {@code null} an unbound socket will be created.
190      *
191      * <p>If there is a security manager,
192      * its {@code checkListen} method is first called
193      * with the SocketAddress port as its argument to ensure the operation is allowed.
194      * This could result in a SecurityException.
195      * <p>
196      * When the socket is created the
197      * {@link DatagramSocket#setReuseAddress(boolean)} method is
198      * called to enable the SO_REUSEADDR socket option.
199      *
200      * @param    bindaddr Socket address to bind to, or {@code null} for
201      *           an unbound socket.
202      * @throws   IOException if an I/O exception occurs
203      *           while creating the MulticastSocket
204      * @throws   SecurityException  if a security manager exists and its
205      *           {@code checkListen} method doesn't allow the operation.
206      * @see      SecurityManager#checkListen
207      * @see      java.net.DatagramSocket#setReuseAddress(boolean)
208      *
209      * @since 1.4
210      */
211     public MulticastSocket(SocketAddress bindaddr) throws IOException {
212         this(createDelegate(bindaddr, MulticastSocket.class));
213     }
214 
215     /**
216      * Set the default time-to-live for multicast packets sent out
217      * on this {@code MulticastSocket} in order to control the
218      * scope of the multicasts.
219      *
220      * <p>The ttl is an <b>unsigned</b> 8-bit quantity, and so <B>must</B> be
221      * in the range {@code 0 <= ttl <= 0xFF }.
222      *
223      * @param      ttl the time-to-live
224      * @throws     IOException if an I/O exception occurs
225      *             while setting the default time-to-live value
226      * @deprecated use the {@link #setTimeToLive(int)} method instead, which uses
227      *             <b>int</b> instead of <b>byte</b> as the type for ttl.
228      * @see #getTTL()
229      */
230     @Deprecated
231     public void setTTL(byte ttl) throws IOException {
232         delegate().setTTL(ttl);
233     }
234 
235     /**
236      * Set the default time-to-live for multicast packets sent out
237      * on this {@code MulticastSocket} in order to control the
238      * scope of the multicasts.
239      *
240      * <P> The ttl <B>must</B> be in the range {@code  0 <= ttl <=
241      * 255} or an {@code IllegalArgumentException} will be thrown.
242      * Multicast packets sent with a TTL of {@code 0} are not transmitted
243      * on the network but may be delivered locally.
244      *
245      * @apiNote
246      * This method is equivalent to calling {@link #setOption(SocketOption, Object)
247      * setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl)}.
248      *
249      * @param  ttl
250      *         the time-to-live
251      *
252      * @throws  IOException
253      *          if an I/O exception occurs while setting the
254      *          default time-to-live value
255      *
256      * @see #getTimeToLive()
257      * @see StandardSocketOptions#IP_MULTICAST_TTL
258      * @since 1.2
259      */
260     public void setTimeToLive(int ttl) throws IOException {
261         delegate().setTimeToLive(ttl);
262     }
263 
264     /**
265      * Get the default time-to-live for multicast packets sent out on
266      * the socket.
267      *
268      * @throws    IOException if an I/O exception occurs
269      * while getting the default time-to-live value
270      * @return the default time-to-live value
271      * @deprecated use the {@link #getTimeToLive()} method instead,
272      * which returns an <b>int</b> instead of a <b>byte</b>.
273      * @see #setTTL(byte)
274      */
275     @Deprecated
276     public byte getTTL() throws IOException {
277         return delegate().getTTL();
278     }
279 
280     /**
281      * Get the default time-to-live for multicast packets sent out on
282      * the socket.
283      *
284      * @apiNote
285      * This method is equivalent to calling {@link #getOption(SocketOption)
286      * getOption(StandardSocketOptions.IP_MULTICAST_TTL)}.
287      *
288      * @throws    IOException if an I/O exception occurs while
289      * getting the default time-to-live value
290      * @return the default time-to-live value
291      * @see #setTimeToLive(int)
292      * @see StandardSocketOptions#IP_MULTICAST_TTL
293      * @since 1.2
294      */
295     public int getTimeToLive() throws IOException {
296         return delegate().getTimeToLive();
297     }
298 
299     /**
300      * Joins a multicast group. Its behavior may be affected by
301      * {@code setInterface} or {@code setNetworkInterface}.
302      *
303      * <p>If there is a security manager, this method first
304      * calls its {@code checkMulticast} method with the
305      * {@code mcastaddr} argument as its argument.
306      *
307      * @apiNote
308      * Calling this method is equivalent to calling
309      * {@link #joinGroup(SocketAddress, NetworkInterface)
310      * joinGroup(new InetSocketAddress(mcastaddr, 0), null)}.
311      *
312      * @param      mcastaddr is the multicast address to join
313      * @throws     IOException if there is an error joining,
314      *             or when the address is not a multicast address,
315      *             or the platform does not support multicasting
316      * @throws     SecurityException if a security manager exists and its
317      *             {@code checkMulticast} method doesn't allow the join.
318      * @deprecated This method does not accept the network interface on
319      *             which to join the multicast group. Use
320      *             {@link #joinGroup(SocketAddress, NetworkInterface)} instead.
321      * @see        SecurityManager#checkMulticast(InetAddress)
322      */
323     @Deprecated(since="14")
324     public void joinGroup(InetAddress mcastaddr) throws IOException {
325         delegate().joinGroup(mcastaddr);
326     }
327 
328     /**
329      * Leave a multicast group. Its behavior may be affected by
330      * {@code setInterface} or {@code setNetworkInterface}.
331      *
332      * <p>If there is a security manager, this method first
333      * calls its {@code checkMulticast} method with the
334      * {@code mcastaddr} argument as its argument.
335      *
336      * @apiNote
337      * Calling this method is equivalent to calling
338      * {@link #leaveGroup(SocketAddress, NetworkInterface)
339      * leaveGroup(new InetSocketAddress(mcastaddr, 0), null)}.
340      *
341      * @param      mcastaddr is the multicast address to leave
342      * @throws     IOException if there is an error leaving
343      *             or when the address is not a multicast address.
344      * @throws     SecurityException if a security manager exists and its
345      *             {@code checkMulticast} method doesn't allow the operation.
346      * @deprecated This method does not accept the network interface on which
347      *             to leave the multicast group. Use
348      *             {@link #leaveGroup(SocketAddress, NetworkInterface)} instead.
349      * @see        SecurityManager#checkMulticast(InetAddress)
350      */
351     @Deprecated(since="14")
352     public void leaveGroup(InetAddress mcastaddr) throws IOException {
353         delegate().leaveGroup(mcastaddr);
354     }
355 
356     /**
357      * {@inheritDoc}
358      * @throws IOException {@inheritDoc}
359      * @throws SecurityException {@inheritDoc}
360      * @throws IllegalArgumentException {@inheritDoc}
361      * @see    SecurityManager#checkMulticast(InetAddress)
362      * @see    DatagramChannel#join(InetAddress, NetworkInterface)
363      * @see    StandardSocketOptions#IP_MULTICAST_IF
364      * @see    #setNetworkInterface(NetworkInterface)
365      * @see    #setInterface(InetAddress)
366      * @since 1.4
367      */
368     @Override
369     public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)
370             throws IOException {
371         super.joinGroup(mcastaddr, netIf);
372     }
373 
374     /**
375      * {@inheritDoc}
376      * @apiNote {@inheritDoc}
377      * @throws IOException {@inheritDoc}
378      * @throws SecurityException {@inheritDoc}
379      * @throws IllegalArgumentException {@inheritDoc}
380      * @see    SecurityManager#checkMulticast(InetAddress)
381      * @see    #joinGroup(SocketAddress, NetworkInterface)
382      * @since 1.4
383      */
384     @Override
385     public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
386             throws IOException {
387         super.leaveGroup(mcastaddr, netIf);
388     }
389 
390     /**
391      * Set the multicast network interface used by methods
392      * whose behavior would be affected by the value of the
393      * network interface. Useful for multihomed hosts.
394      *
395      * @param      inf the InetAddress
396      * @throws     SocketException if there is an error in
397      *             the underlying protocol, such as a TCP error.
398      * @deprecated The InetAddress may not uniquely identify
399      *             the network interface. Use
400      *             {@link #setNetworkInterface(NetworkInterface)} instead.
401      * @see        #getInterface()
402      */
403     @Deprecated(since="14")
404     public void setInterface(InetAddress inf) throws SocketException {
405         delegate().setInterface(inf);
406     }
407 
408     /**
409      * Retrieve the address of the network interface used for
410      * multicast packets.
411      *
412      * @return     An {@code InetAddress} representing the address
413      *             of the network interface used for multicast packets,
414      *             or if no interface has been set, an {@code InetAddress}
415      *             representing any local address.
416      * @throws     SocketException if there is an error in the
417      *             underlying protocol, such as a TCP error.
418      * @deprecated The network interface may not be uniquely identified by
419      *             the InetAddress returned.
420      *             Use {@link #getNetworkInterface()} instead.
421      * @see        #setInterface(java.net.InetAddress)
422      */
423     @Deprecated(since="14")
424     public InetAddress getInterface() throws SocketException {
425         return delegate().getInterface();
426     }
427 
428     /**
429      * Specify the network interface for outgoing multicast datagrams
430      * sent on this socket.
431      *
432      * @apiNote
433      * This method is equivalent to calling {@link #setOption(SocketOption, Object)
434      * setOption(StandardSocketOptions.IP_MULTICAST_IF, netIf)}.
435      *
436      * @param netIf the interface
437      * @throws    SocketException if there is an error in
438      * the underlying protocol, such as a TCP error.
439      * @see #getNetworkInterface()
440      * @see StandardSocketOptions#IP_MULTICAST_IF
441      * @since 1.4
442      */
443     public void setNetworkInterface(NetworkInterface netIf)
444         throws SocketException {
445         delegate().setNetworkInterface(netIf);
446     }
447 
448     /**
449      * Get the multicast network interface set for outgoing multicast
450      * datagrams sent from this socket.
451      *
452      * @apiNote
453      * When an interface is set, this method is equivalent
454      * to calling {@link #getOption(SocketOption)
455      * getOption(StandardSocketOptions.IP_MULTICAST_IF)}.
456      *
457      * @throws SocketException if there is an error in
458      *         the underlying protocol, such as a TCP error.
459      * @return The multicast {@code NetworkInterface} currently set. A placeholder
460      *         NetworkInterface is returned when there is no interface set; it has
461      *         a single InetAddress to represent any local address.
462      * @see    #setNetworkInterface(NetworkInterface)
463      * @see    StandardSocketOptions#IP_MULTICAST_IF
464      * @since  1.4
465      */
466     public NetworkInterface getNetworkInterface() throws SocketException {
467         return delegate().getNetworkInterface();
468     }
469 
470     /**
471      * Disable/Enable local loopback of multicast datagrams.
472      * The option is used by the platform's networking code as a hint
473      * for setting whether multicast data will be looped back to
474      * the local socket.
475      *
476      * <p>Because this option is a hint, applications that want to
477      * verify what loopback mode is set to should call
478      * {@link #getLoopbackMode()}
479      * @param      disable {@code true} to disable the LoopbackMode
480      * @throws     SocketException if an error occurs while setting the value
481      * @since      1.4
482      * @deprecated Use {@link #setOption(SocketOption, Object)} with
483      *             {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP}
484      *             instead. The loopback mode is enabled by default,
485      *             {@code MulticastSocket.setOption(StandardSocketOptions.IP_MULTICAST_LOOP, false)}
486      *             disables it.
487      * @see        #getLoopbackMode
488      */
489     @Deprecated(since="14")
490     public void setLoopbackMode(boolean disable) throws SocketException {
491         delegate().setLoopbackMode(disable);
492     }
493 
494     /**
495      * Get the setting for local loopback of multicast datagrams.
496      *
497      * @throws     SocketException if an error occurs while getting the value
498      * @return     true if the LoopbackMode has been disabled
499      * @since      1.4
500      * @deprecated Use {@link #getOption(SocketOption)} with
501      *             {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP}
502      *             instead.
503      * @see        #setLoopbackMode
504      */
505     @Deprecated(since="14")
506     public boolean getLoopbackMode() throws SocketException {
507         return delegate().getLoopbackMode();
508     }
509 
510     /**
511      * Sends a datagram packet to the destination, with a TTL (time-to-live)
512      * other than the default for the socket.  This method
513      * need only be used in instances where a particular TTL is desired;
514      * otherwise it is preferable to set a TTL once on the socket, and
515      * use that default TTL for all packets.  This method does <B>not
516      * </B> alter the default TTL for the socket. Its behavior may be
517      * affected by {@code setInterface}.
518      *
519      * <p>If there is a security manager, this method first performs some
520      * security checks. First, if {@code p.getAddress().isMulticastAddress()}
521      * is true, this method calls the
522      * security manager's {@code checkMulticast} method
523      * with {@code p.getAddress()} and {@code ttl} as its arguments.
524      * If the evaluation of that expression is false,
525      * this method instead calls the security manager's
526      * {@code checkConnect} method with arguments
527      * {@code p.getAddress().getHostAddress()} and
528      * {@code p.getPort()}. Each call to a security manager method
529      * could result in a SecurityException if the operation is not allowed.
530      *
531      * @param p is the packet to be sent. The packet should contain
532      * the destination multicast ip address and the data to be sent.
533      * One does not need to be the member of the group to send
534      * packets to a destination multicast address.
535      * @param ttl optional time to live for multicast packet.
536      * default ttl is 1.
537      *
538      * @throws     IOException is raised if an error occurs i.e
539      *             error while setting ttl.
540      * @throws     SecurityException  if a security manager exists and its
541      *             {@code checkMulticast} or {@code checkConnect}
542      *             method doesn't allow the send.
543      * @throws     PortUnreachableException may be thrown if the socket is connected
544      *             to a currently unreachable destination. Note, there is no
545      *             guarantee that the exception will be thrown.
546      * @throws     IllegalArgumentException if the socket is connected,
547      *             and connected address and packet address differ, or
548      *             if the socket is not connected and the packet address
549      *             is not set or if its port is out of range.
550      *
551      *
552      * @deprecated Use the following code or its equivalent instead:
553      *  <pre>{@code   ......
554      *  int ttl = mcastSocket.getOption(StandardSocketOptions.IP_MULTICAST_TTL);
555      *  mcastSocket.setOption(StandardSocketOptions.IP_MULTICAST_TTL, newttl);
556      *  mcastSocket.send(p);
557      *  mcastSocket.setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl);
558      *  ......}</pre>
559      *
560      * @see DatagramSocket#send
561      * @see DatagramSocket#receive
562      * @see SecurityManager#checkMulticast(java.net.InetAddress, byte)
563      * @see SecurityManager#checkConnect
564      */
565     @Deprecated
566     public void send(DatagramPacket p, byte ttl)
567         throws IOException {
568         delegate().send(p, ttl);
569     }
570 }