toolchain/gcc/libjava/java/net/MulticastSocket.java

   1 /* MulticastSocket.java -- Class for using multicast sockets
   2    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
   3    Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  20 02111-1307 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39 package java.net;
  40
  41 import java.io.IOException;
  42 import java.util.Enumeration;
  43
  44 /**
  45  * Written using on-line Java Platform 1.2 API Specification, as well
  46  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  47  * Status:  Believed complete and correct.
  48  */
  49
  50 /**
  51  * This class models a multicast UDP socket.  A multicast address is a
  52  * class D internet address (one whose most significant bits are 1110).
  53  * A multicast group consists of a multicast address and a well known
  54  * port number.  All members of the group listening on that address and
  55  * port will receive all the broadcasts to the group.
  56  * <p>
  57  * Please note that applets are not allowed to use multicast sockets
  58  *
  59  * Written using on-line Java Platform 1.2 API Specification, as well
  60  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  61  * Status:  Believed complete and correct.
  62  *
  63  * @author Warren Levy <warrenl@cygnus.com>
  64  * @author Aaron M. Renn (arenn@urbanophile.com) (Documentation comments)
  65  * @since 1.1
  66  * @date May 18, 1999.
  67  */
  68 public class MulticastSocket extends DatagramSocket
  69 {
  70   /**
  71    * Create a MulticastSocket that this not bound to any address
  72    *
  73    * @exception IOException If an error occurs
  74    * @exception SecurityException If a security manager exists and its
  75    * checkListen method doesn't allow the operation
  76    */
  77   public MulticastSocket() throws IOException
  78   {
  79     this(new InetSocketAddress(0));
  80   }
  81
  82   /**
  83    * Create a multicast socket bound to the specified port
  84    *
  85    * @param port The port to bind to
  86    *
  87    * @exception IOException If an error occurs
  88    * @exception SecurityException If a security manager exists and its
  89    * checkListen method doesn't allow the operation
  90    */
  91   public MulticastSocket(int port) throws IOException
  92   {
  93     this(new InetSocketAddress(port));
  94   }
  95
  96   /**
  97    * Create a multicast socket bound to the specified SocketAddress.
  98    *
  99    * @param address The SocketAddress the multicast socket will be bound to
 100    *
 101    * @exception IOException If an error occurs
 102    * @exception SecurityException If a security manager exists and its
 103    * checkListen method doesn't allow the operation
 104    *
 105    * @since 1.4
 106    */
 107   public MulticastSocket(SocketAddress address) throws IOException
 108   {
 109     super((SocketAddress) null);
 110     setReuseAddress(true);
 111     if (address != null)
 112       bind(address);
 113   }
 114
 115   /**
 116    * Returns the interface being used for multicast packets
 117    *
 118    * @return The multicast interface
 119    *
 120    * @exception SocketException If an error occurs
 121    */
 122   public InetAddress getInterface() throws SocketException
 123   {
 124     if (isClosed())
 125       throw new SocketException("socket is closed");
 126
 127     return (InetAddress) getImpl().getOption(SocketOptions.IP_MULTICAST_IF);
 128   }
 129
 130   /**
 131    * Returns the current value of the "Time to Live" option.  This is the
 132    * number of hops a packet can make before it "expires".   This method id
 133    * deprecated.  Use <code>getTimeToLive</code> instead.
 134    *
 135    * @return The TTL value
 136    *
 137    * @exception IOException If an error occurs
 138    *
 139    * @deprecated 1.2 Replaced by getTimeToLive()
 140    *
 141    * @see MulticastSocket#getTimeToLive()
 142    */
 143   public byte getTTL() throws IOException
 144   {
 145     if (isClosed())
 146       throw new SocketException("socket is closed");
 147
 148     // Use getTTL here rather than getTimeToLive in case we're using an impl
 149     // other than the default PlainDatagramSocketImpl and it doesn't have
 150     // getTimeToLive yet.
 151     return getImpl().getTTL();
 152   }
 153
 154   /**
 155    * Returns the current value of the "Time to Live" option.  This is the
 156    * number of hops a packet can make before it "expires".
 157    *
 158    * @return The TTL value
 159    *
 160    * @exception IOException If an error occurs
 161    *
 162    * @since 1.2
 163    */
 164   public int getTimeToLive() throws IOException
 165   {
 166     if (isClosed())
 167       throw new SocketException("socket is closed");
 168
 169     return getImpl().getTimeToLive();
 170   }
 171
 172   /**
 173    * Sets the interface to use for sending multicast packets.
 174    *
 175    * @param addr The new interface to use.
 176    *
 177    * @exception SocketException If an error occurs.
 178    *
 179    * @since 1.4
 180    */
 181   public void setInterface(InetAddress addr) throws SocketException
 182   {
 183     if (isClosed())
 184       throw new SocketException("socket is closed");
 185
 186     getImpl().setOption(SocketOptions.IP_MULTICAST_IF, addr);
 187   }
 188
 189   /**
 190    * Sets the local network interface used to send multicast messages
 191    *
 192    * @param netIF The local network interface used to send multicast messages
 193    *
 194    * @exception SocketException If an error occurs
 195    *
 196    * @see MulticastSocket#getNetworkInterface()
 197    *
 198    * @since 1.4
 199    */
 200   public void setNetworkInterface(NetworkInterface netIf)
 201     throws SocketException
 202   {
 203     if (isClosed())
 204       throw new SocketException("socket is closed");
 205
 206     Enumeration e = netIf.getInetAddresses ();
 207
 208     if (!e.hasMoreElements ())
 209       throw new SocketException("no network devices found");
 210
 211     InetAddress address = (InetAddress) e.nextElement ();
 212     getImpl().setOption (SocketOptions.IP_MULTICAST_IF, address);
 213   }
 214
 215   /**
 216    * Gets the local network interface which is used to send multicast messages
 217    *
 218    * @return The local network interface to send multicast messages
 219    *
 220    * @exception SocketException If an error occurs
 221    *
 222    * @see MulticastSocket#setNetworkInterface(NetworkInterface netIf)
 223    *
 224    * @since 1.4
 225    */
 226   public NetworkInterface getNetworkInterface()
 227     throws SocketException
 228   {
 229     if (isClosed())
 230       throw new SocketException("socket is closed");
 231
 232     InetAddress address =
 233       (InetAddress) getImpl().getOption (SocketOptions.IP_MULTICAST_IF);
 234     NetworkInterface netIf = NetworkInterface.getByInetAddress (address);
 235
 236     return netIf;
 237   }
 238
 239   /**
 240    * Disable/Enable local loopback of multicast packets.  The option is used by
 241    * the platform's networking code as a hint for setting whether multicast
 242    * data will be looped back to the local socket.
 243    *
 244    * Because this option is a hint, applications that want to verify what
 245    * loopback mode is set to should call #getLoopbackMode
 246    *
 247    * @param disable True to disable loopback mode
 248    *
 249    * @exception SocketException If an error occurs
 250    *
 251    * @since 1.4
 252    */
 253   public void setLoopbackMode(boolean disable) throws SocketException
 254   {
 255     if (isClosed())
 256       throw new SocketException("socket is closed");
 257
 258     getImpl().setOption (SocketOptions.IP_MULTICAST_LOOP, new Boolean (disable));
 259   }
 260
 261   /**
 262    * Checks if local loopback mode is enabled or not
 263    *
 264    * @exception SocketException If an error occurs
 265    *
 266    * @since 1.4
 267    */
 268   public boolean getLoopbackMode() throws SocketException
 269   {
 270     if (isClosed())
 271       throw new SocketException("socket is closed");
 272
 273     Object buf = getImpl().getOption (SocketOptions.IP_MULTICAST_LOOP);
 274
 275     if (buf instanceof Boolean)
 276       return ((Boolean) buf).booleanValue();
 277
 278     throw new SocketException("unexpected type");
 279   }
 280
 281   /**
 282    * Sets the "Time to Live" value for a socket.  The value must be between
 283    * 1 and 255.
 284    *
 285    * @param ttl The new TTL value
 286    *
 287    * @exception IOException If an error occurs
 288    *
 289    * @deprecated 1.2 Replaced by <code>setTimeToLive</code>
 290    *
 291    * @see MulticastSocket#setTimeToLive(int ttl)
 292    */
 293   public void setTTL(byte ttl) throws IOException
 294   {
 295     if (isClosed())
 296       throw new SocketException("socket is closed");
 297
 298     // Use setTTL here rather than setTimeToLive in case we're using an impl
 299     // other than the default PlainDatagramSocketImpl and it doesn't have
 300     // setTimeToLive yet.
 301     getImpl().setTTL(ttl);
 302   }
 303
 304   /**
 305    * Sets the "Time to Live" value for a socket.  The value must be between
 306    * 1 and 255.
 307    *
 308    * @param ttl The new TTL value
 309    *
 310    * @exception IOException If an error occurs
 311    *
 312    * @since 1.2
 313    */
 314   public void setTimeToLive(int ttl) throws IOException
 315   {
 316     if (isClosed())
 317       throw new SocketException("socket is closed");
 318
 319     if (ttl <= 0 || ttl > 255)
 320       throw new IllegalArgumentException("Invalid ttl: " + ttl);
 321
 322     getImpl().setTimeToLive(ttl);
 323   }
 324
 325   /**
 326    * Joins the specified mulitcast group.
 327    *
 328    * @param addr The address of the group to join
 329    *
 330    * @exception IOException If an error occurs
 331    * @exception SecurityException If a security manager exists and its
 332    * checkMulticast method doesn't allow the operation
 333    */
 334   public void joinGroup(InetAddress mcastaddr) throws IOException
 335   {
 336     if (isClosed())
 337       throw new SocketException("socket is closed");
 338
 339     if (! mcastaddr.isMulticastAddress())
 340       throw new IOException("Not a Multicast address");
 341
 342     SecurityManager s = System.getSecurityManager();
 343     if (s != null)
 344       s.checkMulticast(mcastaddr);
 345
 346     getImpl().join(mcastaddr);
 347   }
 348
 349   /**
 350    * Leaves the specified multicast group
 351    *
 352    * @param addr The address of the group to leave
 353    *
 354    * @exception IOException If an error occurs
 355    * @exception SecurityException If a security manager exists and its
 356    * checkMulticast method doesn't allow the operation
 357    */
 358   public void leaveGroup(InetAddress mcastaddr) throws IOException
 359   {
 360     if (isClosed())
 361       throw new SocketException("socket is closed");
 362
 363     if (! mcastaddr.isMulticastAddress())
 364       throw new IOException("Not a Multicast address");
 365
 366     SecurityManager s = System.getSecurityManager();
 367     if (s != null)
 368       s.checkMulticast(mcastaddr);
 369
 370     getImpl().leave(mcastaddr);
 371   }
 372
 373   /**
 374    * Joins the specified mulitcast group on a specified interface.
 375    *
 376    * @param mcastaddr The multicast address to join
 377    * @param netIf The local network interface to receive the multicast
 378    * messages on or null to defer the interface set by #setInterface or
 379    * #setNetworkInterface
 380    *
 381    * @exception IOException If an error occurs
 382    * @exception IllegalArgumentException If address type is not supported
 383    * @exception SecurityException If a security manager exists and its
 384    * checkMulticast method doesn't allow the operation
 385    *
 386    * @see MulticastSocket#setInterface(InetAddress addr)
 387    * @see MulticastSocket#setNetworkInterface(NetworkInterface netIf)
 388    *
 389    * @since 1.4
 390    */
 391   public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)
 392     throws IOException
 393   {
 394     if (isClosed())
 395       throw new SocketException("socket is closed");
 396
 397     if (! (mcastaddr instanceof InetSocketAddress))
 398       throw new IllegalArgumentException ("SocketAddress type not supported");
 399
 400     InetSocketAddress tmp = (InetSocketAddress) mcastaddr;
 401
 402     if (! tmp.getAddress ().isMulticastAddress ())
 403       throw new IOException ("Not a Multicast address");
 404
 405     SecurityManager s = System.getSecurityManager ();
 406     if (s != null)
 407       s.checkMulticast (tmp.getAddress ());
 408
 409     getImpl().joinGroup (mcastaddr, netIf);
 410   }
 411
 412   /**
 413    * Leaves the specified mulitcast group on a specified interface.
 414    *
 415    * @param mcastaddr The multicast address to leave
 416    * @param netIf The local networki interface or null to defer to the
 417    * interface set by setInterface or setNetworkInterface
 418    *
 419    * @exception IOException If an error occurs
 420    * @exception IllegalArgumentException If address type is not supported
 421    * @exception SecurityException If a security manager exists and its
 422    * checkMulticast method doesn't allow the operation
 423    *
 424    * @see MulticastSocket#setInterface(InetAddress addr)
 425    * @see MulticastSocket#setNetworkInterface(NetworkInterface netIf)
 426    *
 427    * @since 1.4
 428    */
 429   public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
 430     throws IOException
 431   {
 432     if (isClosed())
 433       throw new SocketException("socket is closed");
 434
 435     InetSocketAddress tmp = (InetSocketAddress) mcastaddr;
 436
 437     if (! tmp.getAddress ().isMulticastAddress ())
 438       throw new IOException ("Not a Multicast address");
 439
 440     SecurityManager s = System.getSecurityManager ();
 441     if (s != null)
 442       s.checkMulticast (tmp.getAddress ());
 443
 444     getImpl().leaveGroup (mcastaddr, netIf);
 445   }
 446
 447   /**
 448    * Sends a packet of data to a multicast address with a TTL that is
 449    * different from the default TTL on this socket.  The default TTL for
 450    * the socket is not changed.
 451    *
 452    * @param packet The packet of data to send
 453    * @param ttl The TTL for this packet
 454    *
 455    * @exception IOException If an error occurs
 456    * @exception SecurityException If a security manager exists and its
 457    * checkConnect or checkMulticast method doesn't allow the operation
 458    *
 459    * @deprecated
 460    */
 461   public synchronized void send(DatagramPacket p, byte ttl) throws IOException
 462   {
 463     if (isClosed())
 464       throw new SocketException("socket is closed");
 465
 466     SecurityManager s = System.getSecurityManager();
 467     if (s != null)
 468       {
 469         InetAddress addr = p.getAddress();
 470         if (addr.isMulticastAddress())
 471           s.checkPermission (new SocketPermission
 472                              (addr.getHostName () + p.getPort (),
 473                               "accept,connect"));
 474         else
 475           s.checkConnect(addr.getHostAddress(), p.getPort());
 476       }
 477
 478     int oldttl = getImpl().getTimeToLive();
 479     getImpl().setTimeToLive(((int) ttl) & 0xFF);
 480     getImpl().send(p);
 481     getImpl().setTimeToLive(oldttl);
 482   }
 483 } // class MulticastSocket