1. /*
  2. * @(#)SocketOptions.java 1.32 04/01/28
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.net;
  8. /**
  9. * Interface of methods to get/set socket options. This interface is
  10. * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>.
  11. * Subclasses of these should override the methods
  12. * of this interface in order to support their own options.
  13. * <P>
  14. * The methods and constants which specify options in this interface are
  15. * for implementation only. If you're not subclassing SocketImpl or
  16. * DatagramSocketImpl, <B>you won't use these directly.</B> There are
  17. * type-safe methods to get/set each of these options in Socket, ServerSocket,
  18. * DatagramSocket and MulticastSocket.
  19. * <P>
  20. * @version 1.32, 01/28/04
  21. * @author David Brown
  22. */
  23. public interface SocketOptions {
  24. /**
  25. * Enable/disable the option specified by <I>optID</I>. If the option
  26. * is to be enabled, and it takes an option-specific "value", this is
  27. * passed in <I>value</I>. The actual type of value is option-specific,
  28. * and it is an error to pass something that isn't of the expected type:
  29. * <BR><PRE>
  30. * SocketImpl s;
  31. * ...
  32. * s.setOption(SO_LINGER, new Integer(10));
  33. * // OK - set SO_LINGER w/ timeout of 10 sec.
  34. * s.setOption(SO_LINGER, new Double(10));
  35. * // ERROR - expects java.lang.Integer
  36. *</PRE>
  37. * If the requested option is binary, it can be set using this method by
  38. * a java.lang.Boolean:
  39. * <BR><PRE>
  40. * s.setOption(TCP_NODELAY, new Boolean(true));
  41. * // OK - enables TCP_NODELAY, a binary option
  42. * </PRE>
  43. * <BR>
  44. * Any option can be disabled using this method with a Boolean(false):
  45. * <BR><PRE>
  46. * s.setOption(TCP_NODELAY, new Boolean(false));
  47. * // OK - disables TCP_NODELAY
  48. * s.setOption(SO_LINGER, new Boolean(false));
  49. * // OK - disables SO_LINGER
  50. * </PRE>
  51. * <BR>
  52. * For an option that has a notion of on and off, and requires
  53. * a non-boolean parameter, setting its value to anything other than
  54. * <I>Boolean(false)</I> implicitly enables it.
  55. * <BR>
  56. * Throws SocketException if the option is unrecognized,
  57. * the socket is closed, or some low-level error occurred
  58. * <BR>
  59. * @param optID identifies the option
  60. * @param value the parameter of the socket option
  61. * @throws SocketException if the option is unrecognized,
  62. * the socket is closed, or some low-level error occurred
  63. * @see #getOption(int)
  64. */
  65. public void
  66. setOption(int optID, Object value) throws SocketException;
  67. /**
  68. * Fetch the value of an option.
  69. * Binary options will return java.lang.Boolean(true)
  70. * if enabled, java.lang.Boolean(false) if disabled, e.g.:
  71. * <BR><PRE>
  72. * SocketImpl s;
  73. * ...
  74. * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));
  75. * if (noDelay.booleanValue()) {
  76. * // true if TCP_NODELAY is enabled...
  77. * ...
  78. * }
  79. * </PRE>
  80. * <P>
  81. * For options that take a particular type as a parameter,
  82. * getOption(int) will return the paramter's value, else
  83. * it will return java.lang.Boolean(false):
  84. * <PRE>
  85. * Object o = s.getOption(SO_LINGER);
  86. * if (o instanceof Integer) {
  87. * System.out.print("Linger time is " + ((Integer)o).intValue());
  88. * } else {
  89. * // the true type of o is java.lang.Boolean(false);
  90. * }
  91. * </PRE>
  92. *
  93. * @param optID an <code>int</code> identifying the option to fetch
  94. * @return the value of the option
  95. * @throws SocketException if the socket is closed
  96. * @throws SocketException if <I>optID</I> is unknown along the
  97. * protocol stack (including the SocketImpl)
  98. * @see #setOption(int, java.lang.Object)
  99. */
  100. public Object getOption(int optID) throws SocketException;
  101. /**
  102. * The java-supported BSD-style options.
  103. */
  104. /**
  105. * Disable Nagle's algorithm for this connection. Written data
  106. * to the network is not buffered pending acknowledgement of
  107. * previously written data.
  108. *<P>
  109. * Valid for TCP only: SocketImpl.
  110. * <P>
  111. * @see Socket#setTcpNoDelay
  112. * @see Socket#getTcpNoDelay
  113. */
  114. public final static int TCP_NODELAY = 0x0001;
  115. /**
  116. * Fetch the local address binding of a socket (this option cannot
  117. * be "set" only "gotten", since sockets are bound at creation time,
  118. * and so the locally bound address cannot be changed). The default local
  119. * address of a socket is INADDR_ANY, meaning any local address on a
  120. * multi-homed host. A multi-homed host can use this option to accept
  121. * connections to only one of its addresses (in the case of a
  122. * ServerSocket or DatagramSocket), or to specify its return address
  123. * to the peer (for a Socket or DatagramSocket). The parameter of
  124. * this option is an InetAddress.
  125. * <P>
  126. * This option <B>must</B> be specified in the constructor.
  127. * <P>
  128. * Valid for: SocketImpl, DatagramSocketImpl
  129. * <P>
  130. * @see Socket#getLocalAddress
  131. * @see DatagramSocket#getLocalAddress
  132. */
  133. public final static int SO_BINDADDR = 0x000F;
  134. /** Sets SO_REUSEADDR for a socket. This is used only for MulticastSockets
  135. * in java, and it is set by default for MulticastSockets.
  136. * <P>
  137. * Valid for: DatagramSocketImpl
  138. */
  139. public final static int SO_REUSEADDR = 0x04;
  140. /**
  141. * Sets SO_BROADCAST for a socket. This option enables and disables
  142. * the ability of the process to send broadcast messages. It is supported
  143. * for only datagram sockets and only on networks that support
  144. * the concept of a broadcast message (e.g. Ethernet, token ring, etc.),
  145. * and it is set by default for DatagramSockets.
  146. * @since 1.4
  147. */
  148. public final static int SO_BROADCAST = 0x0020;
  149. /** Set which outgoing interface on which to send multicast packets.
  150. * Useful on hosts with multiple network interfaces, where applications
  151. * want to use other than the system default. Takes/returns an InetAddress.
  152. * <P>
  153. * Valid for Multicast: DatagramSocketImpl
  154. * <P>
  155. * @see MulticastSocket#setInterface(InetAddress)
  156. * @see MulticastSocket#getInterface()
  157. */
  158. public final static int IP_MULTICAST_IF = 0x10;
  159. /** Same as above. This option is introduced so that the behaviour
  160. * with IP_MULTICAST_IF will be kept the same as before, while
  161. * this new option can support setting outgoing interfaces with either
  162. * IPv4 and IPv6 addresses.
  163. *
  164. * NOTE: make sure there is no conflict with this
  165. * @see MulticastSocket#setNetworkInterface(NetworkInterface)
  166. * @see MulticastSocket#getNetworkInterface()
  167. * @since 1.4
  168. */
  169. public final static int IP_MULTICAST_IF2 = 0x1f;
  170. /**
  171. * This option enables or disables local loopback of multicast datagrams.
  172. * This option is enabled by default for Multicast Sockets.
  173. * @since 1.4
  174. */
  175. public final static int IP_MULTICAST_LOOP = 0x12;
  176. /**
  177. * This option sets the type-of-service or traffic class field
  178. * in the IP header for a TCP or UDP socket.
  179. * @since 1.4
  180. */
  181. public final static int IP_TOS = 0x3;
  182. /**
  183. * Specify a linger-on-close timeout. This option disables/enables
  184. * immediate return from a <B>close()</B> of a TCP Socket. Enabling
  185. * this option with a non-zero Integer <I>timeout</I> means that a
  186. * <B>close()</B> will block pending the transmission and acknowledgement
  187. * of all data written to the peer, at which point the socket is closed
  188. * <I>gracefully</I>. Upon reaching the linger timeout, the socket is
  189. * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a
  190. * timeout of zero does a forceful close immediately. If the specified
  191. * timeout value exceeds 65,535 it will be reduced to 65,535.
  192. * <P>
  193. * Valid only for TCP: SocketImpl
  194. *
  195. * @see Socket#setSoLinger
  196. * @see Socket#getSoLinger
  197. */
  198. public final static int SO_LINGER = 0x0080;
  199. /** Set a timeout on blocking Socket operations:
  200. * <PRE>
  201. * ServerSocket.accept();
  202. * SocketInputStream.read();
  203. * DatagramSocket.receive();
  204. * </PRE>
  205. *
  206. * <P> The option must be set prior to entering a blocking
  207. * operation to take effect. If the timeout expires and the
  208. * operation would continue to block,
  209. * <B>java.io.InterruptedIOException</B> is raised. The Socket is
  210. * not closed in this case.
  211. *
  212. * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl
  213. *
  214. * @see Socket#setSoTimeout
  215. * @see ServerSocket#setSoTimeout
  216. * @see DatagramSocket#setSoTimeout
  217. */
  218. public final static int SO_TIMEOUT = 0x1006;
  219. /**
  220. * Set a hint the size of the underlying buffers used by the
  221. * platform for outgoing network I/O. When used in set, this is a
  222. * suggestion to the kernel from the application about the size of
  223. * buffers to use for the data to be sent over the socket. When
  224. * used in get, this must return the size of the buffer actually
  225. * used by the platform when sending out data on this socket.
  226. *
  227. * Valid for all sockets: SocketImpl, DatagramSocketImpl
  228. *
  229. * @see Socket#setSendBufferSize
  230. * @see Socket#getSendBufferSize
  231. * @see DatagramSocket#setSendBufferSize
  232. * @see DatagramSocket#getSendBufferSize
  233. */
  234. public final static int SO_SNDBUF = 0x1001;
  235. /**
  236. * Set a hint the size of the underlying buffers used by the
  237. * platform for incoming network I/O. When used in set, this is a
  238. * suggestion to the kernel from the application about the size of
  239. * buffers to use for the data to be received over the
  240. * socket. When used in get, this must return the size of the
  241. * buffer actually used by the platform when receiving in data on
  242. * this socket.
  243. *
  244. * Valid for all sockets: SocketImpl, DatagramSocketImpl
  245. *
  246. * @see Socket#setReceiveBufferSize
  247. * @see Socket#getReceiveBufferSize
  248. * @see DatagramSocket#setReceiveBufferSize
  249. * @see DatagramSocket#getReceiveBufferSize
  250. */
  251. public final static int SO_RCVBUF = 0x1002;
  252. /**
  253. * When the keepalive option is set for a TCP socket and no data
  254. * has been exchanged across the socket in either direction for
  255. * 2 hours (NOTE: the actual value is implementation dependent),
  256. * TCP automatically sends a keepalive probe to the peer. This probe is a
  257. * TCP segment to which the peer must respond.
  258. * One of three responses is expected:
  259. * 1. The peer responds with the expected ACK. The application is not
  260. * notified (since everything is OK). TCP will send another probe
  261. * following another 2 hours of inactivity.
  262. * 2. The peer responds with an RST, which tells the local TCP that
  263. * the peer host has crashed and rebooted. The socket is closed.
  264. * 3. There is no response from the peer. The socket is closed.
  265. *
  266. * The purpose of this option is to detect if the peer host crashes.
  267. *
  268. * Valid only for TCP socket: SocketImpl
  269. *
  270. * @see Socket#setKeepAlive
  271. * @see Socket#getKeepAlive
  272. */
  273. public final static int SO_KEEPALIVE = 0x0008;
  274. /**
  275. * When the OOBINLINE option is set, any TCP urgent data received on
  276. * the socket will be received through the socket input stream.
  277. * When the option is disabled (which is the default) urgent data
  278. * is silently discarded.
  279. *
  280. * @see Socket#setOOBInline
  281. * @see Socket#getOOBInline
  282. */
  283. public final static int SO_OOBINLINE = 0x1003;
  284. }