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 /** 29 * Interface of methods to get/set socket options. This interface is 30 * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>. 31 * Subclasses of these should override the methods 32 * of this interface in order to support their own options. 33 * <P> 34 * The methods and constants which specify options in this interface are 35 * for implementation only. If you're not subclassing SocketImpl or 36 * DatagramSocketImpl, <B>you won't use these directly.</B> There are 37 * type-safe methods to get/set each of these options in Socket, ServerSocket, 38 * DatagramSocket and MulticastSocket. 39 * <P> 40 * @author David Brown 41 */ 42 43 44 public interface SocketOptions { 45 46 /** 47 * Enable/disable the option specified by <I>optID</I>. If the option 120 * protocol stack (including the SocketImpl) 121 * @see #setOption(int, java.lang.Object) 122 */ 123 public Object getOption(int optID) throws SocketException; 124 125 /** 126 * The java-supported BSD-style options. 127 */ 128 129 /** 130 * Disable Nagle's algorithm for this connection. Written data 131 * to the network is not buffered pending acknowledgement of 132 * previously written data. 133 *<P> 134 * Valid for TCP only: SocketImpl. 135 * <P> 136 * @see Socket#setTcpNoDelay 137 * @see Socket#getTcpNoDelay 138 */ 139 140 public final static int TCP_NODELAY = 0x0001; 141 142 /** 143 * Fetch the local address binding of a socket (this option cannot 144 * be "set" only "gotten", since sockets are bound at creation time, 145 * and so the locally bound address cannot be changed). The default local 146 * address of a socket is INADDR_ANY, meaning any local address on a 147 * multi-homed host. A multi-homed host can use this option to accept 148 * connections to only one of its addresses (in the case of a 149 * ServerSocket or DatagramSocket), or to specify its return address 150 * to the peer (for a Socket or DatagramSocket). The parameter of 151 * this option is an InetAddress. 152 * <P> 153 * This option <B>must</B> be specified in the constructor. 154 * <P> 155 * Valid for: SocketImpl, DatagramSocketImpl 156 * <P> 157 * @see Socket#getLocalAddress 158 * @see DatagramSocket#getLocalAddress 159 */ 160 161 public final static int SO_BINDADDR = 0x000F; 162 163 /** Sets SO_REUSEADDR for a socket. This is used only for MulticastSockets 164 * in java, and it is set by default for MulticastSockets. 165 * <P> 166 * Valid for: DatagramSocketImpl 167 */ 168 169 public final static int SO_REUSEADDR = 0x04; 170 171 /** 172 * Sets SO_BROADCAST for a socket. This option enables and disables 173 * the ability of the process to send broadcast messages. It is supported 174 * for only datagram sockets and only on networks that support 175 * the concept of a broadcast message (e.g. Ethernet, token ring, etc.), 176 * and it is set by default for DatagramSockets. 177 * @since 1.4 178 */ 179 180 public final static int SO_BROADCAST = 0x0020; 181 182 /** Set which outgoing interface on which to send multicast packets. 183 * Useful on hosts with multiple network interfaces, where applications 184 * want to use other than the system default. Takes/returns an InetAddress. 185 * <P> 186 * Valid for Multicast: DatagramSocketImpl 187 * <P> 188 * @see MulticastSocket#setInterface(InetAddress) 189 * @see MulticastSocket#getInterface() 190 */ 191 192 public final static int IP_MULTICAST_IF = 0x10; 193 194 /** Same as above. This option is introduced so that the behaviour 195 * with IP_MULTICAST_IF will be kept the same as before, while 196 * this new option can support setting outgoing interfaces with either 197 * IPv4 and IPv6 addresses. 198 * 199 * NOTE: make sure there is no conflict with this 200 * @see MulticastSocket#setNetworkInterface(NetworkInterface) 201 * @see MulticastSocket#getNetworkInterface() 202 * @since 1.4 203 */ 204 public final static int IP_MULTICAST_IF2 = 0x1f; 205 206 /** 207 * This option enables or disables local loopback of multicast datagrams. 208 * This option is enabled by default for Multicast Sockets. 209 * @since 1.4 210 */ 211 212 public final static int IP_MULTICAST_LOOP = 0x12; 213 214 /** 215 * This option sets the type-of-service or traffic class field 216 * in the IP header for a TCP or UDP socket. 217 * @since 1.4 218 */ 219 220 public final static int IP_TOS = 0x3; 221 222 /** 223 * Specify a linger-on-close timeout. This option disables/enables 224 * immediate return from a <B>close()</B> of a TCP Socket. Enabling 225 * this option with a non-zero Integer <I>timeout</I> means that a 226 * <B>close()</B> will block pending the transmission and acknowledgement 227 * of all data written to the peer, at which point the socket is closed 228 * <I>gracefully</I>. Upon reaching the linger timeout, the socket is 229 * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a 230 * timeout of zero does a forceful close immediately. If the specified 231 * timeout value exceeds 65,535 it will be reduced to 65,535. 232 * <P> 233 * Valid only for TCP: SocketImpl 234 * 235 * @see Socket#setSoLinger 236 * @see Socket#getSoLinger 237 */ 238 public final static int SO_LINGER = 0x0080; 239 240 /** Set a timeout on blocking Socket operations: 241 * <PRE> 242 * ServerSocket.accept(); 243 * SocketInputStream.read(); 244 * DatagramSocket.receive(); 245 * </PRE> 246 * 247 * <P> The option must be set prior to entering a blocking 248 * operation to take effect. If the timeout expires and the 249 * operation would continue to block, 250 * <B>java.io.InterruptedIOException</B> is raised. The Socket is 251 * not closed in this case. 252 * 253 * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl 254 * 255 * @see Socket#setSoTimeout 256 * @see ServerSocket#setSoTimeout 257 * @see DatagramSocket#setSoTimeout 258 */ 259 public final static int SO_TIMEOUT = 0x1006; 260 261 /** 262 * Set a hint the size of the underlying buffers used by the 263 * platform for outgoing network I/O. When used in set, this is a 264 * suggestion to the kernel from the application about the size of 265 * buffers to use for the data to be sent over the socket. When 266 * used in get, this must return the size of the buffer actually 267 * used by the platform when sending out data on this socket. 268 * 269 * Valid for all sockets: SocketImpl, DatagramSocketImpl 270 * 271 * @see Socket#setSendBufferSize 272 * @see Socket#getSendBufferSize 273 * @see DatagramSocket#setSendBufferSize 274 * @see DatagramSocket#getSendBufferSize 275 */ 276 public final static int SO_SNDBUF = 0x1001; 277 278 /** 279 * Set a hint the size of the underlying buffers used by the 280 * platform for incoming network I/O. When used in set, this is a 281 * suggestion to the kernel from the application about the size of 282 * buffers to use for the data to be received over the 283 * socket. When used in get, this must return the size of the 284 * buffer actually used by the platform when receiving in data on 285 * this socket. 286 * 287 * Valid for all sockets: SocketImpl, DatagramSocketImpl 288 * 289 * @see Socket#setReceiveBufferSize 290 * @see Socket#getReceiveBufferSize 291 * @see DatagramSocket#setReceiveBufferSize 292 * @see DatagramSocket#getReceiveBufferSize 293 */ 294 public final static int SO_RCVBUF = 0x1002; 295 296 /** 297 * When the keepalive option is set for a TCP socket and no data 298 * has been exchanged across the socket in either direction for 299 * 2 hours (NOTE: the actual value is implementation dependent), 300 * TCP automatically sends a keepalive probe to the peer. This probe is a 301 * TCP segment to which the peer must respond. 302 * One of three responses is expected: 303 * 1. The peer responds with the expected ACK. The application is not 304 * notified (since everything is OK). TCP will send another probe 305 * following another 2 hours of inactivity. 306 * 2. The peer responds with an RST, which tells the local TCP that 307 * the peer host has crashed and rebooted. The socket is closed. 308 * 3. There is no response from the peer. The socket is closed. 309 * 310 * The purpose of this option is to detect if the peer host crashes. 311 * 312 * Valid only for TCP socket: SocketImpl 313 * 314 * @see Socket#setKeepAlive 315 * @see Socket#getKeepAlive 316 */ 317 public final static int SO_KEEPALIVE = 0x0008; 318 319 /** 320 * When the OOBINLINE option is set, any TCP urgent data received on 321 * the socket will be received through the socket input stream. 322 * When the option is disabled (which is the default) urgent data 323 * is silently discarded. 324 * 325 * @see Socket#setOOBInline 326 * @see Socket#getOOBInline 327 */ 328 public final static int SO_OOBINLINE = 0x1003; 329 } | 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.lang.annotation.Native; 29 30 /** 31 * Interface of methods to get/set socket options. This interface is 32 * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>. 33 * Subclasses of these should override the methods 34 * of this interface in order to support their own options. 35 * <P> 36 * The methods and constants which specify options in this interface are 37 * for implementation only. If you're not subclassing SocketImpl or 38 * DatagramSocketImpl, <B>you won't use these directly.</B> There are 39 * type-safe methods to get/set each of these options in Socket, ServerSocket, 40 * DatagramSocket and MulticastSocket. 41 * <P> 42 * @author David Brown 43 */ 44 45 46 public interface SocketOptions { 47 48 /** 49 * Enable/disable the option specified by <I>optID</I>. If the option 122 * protocol stack (including the SocketImpl) 123 * @see #setOption(int, java.lang.Object) 124 */ 125 public Object getOption(int optID) throws SocketException; 126 127 /** 128 * The java-supported BSD-style options. 129 */ 130 131 /** 132 * Disable Nagle's algorithm for this connection. Written data 133 * to the network is not buffered pending acknowledgement of 134 * previously written data. 135 *<P> 136 * Valid for TCP only: SocketImpl. 137 * <P> 138 * @see Socket#setTcpNoDelay 139 * @see Socket#getTcpNoDelay 140 */ 141 142 @Native public final static int TCP_NODELAY = 0x0001; 143 144 /** 145 * Fetch the local address binding of a socket (this option cannot 146 * be "set" only "gotten", since sockets are bound at creation time, 147 * and so the locally bound address cannot be changed). The default local 148 * address of a socket is INADDR_ANY, meaning any local address on a 149 * multi-homed host. A multi-homed host can use this option to accept 150 * connections to only one of its addresses (in the case of a 151 * ServerSocket or DatagramSocket), or to specify its return address 152 * to the peer (for a Socket or DatagramSocket). The parameter of 153 * this option is an InetAddress. 154 * <P> 155 * This option <B>must</B> be specified in the constructor. 156 * <P> 157 * Valid for: SocketImpl, DatagramSocketImpl 158 * <P> 159 * @see Socket#getLocalAddress 160 * @see DatagramSocket#getLocalAddress 161 */ 162 163 @Native public final static int SO_BINDADDR = 0x000F; 164 165 /** Sets SO_REUSEADDR for a socket. This is used only for MulticastSockets 166 * in java, and it is set by default for MulticastSockets. 167 * <P> 168 * Valid for: DatagramSocketImpl 169 */ 170 171 @Native public final static int SO_REUSEADDR = 0x04; 172 173 /** 174 * Sets SO_BROADCAST for a socket. This option enables and disables 175 * the ability of the process to send broadcast messages. It is supported 176 * for only datagram sockets and only on networks that support 177 * the concept of a broadcast message (e.g. Ethernet, token ring, etc.), 178 * and it is set by default for DatagramSockets. 179 * @since 1.4 180 */ 181 182 @Native public final static int SO_BROADCAST = 0x0020; 183 184 /** Set which outgoing interface on which to send multicast packets. 185 * Useful on hosts with multiple network interfaces, where applications 186 * want to use other than the system default. Takes/returns an InetAddress. 187 * <P> 188 * Valid for Multicast: DatagramSocketImpl 189 * <P> 190 * @see MulticastSocket#setInterface(InetAddress) 191 * @see MulticastSocket#getInterface() 192 */ 193 194 @Native public final static int IP_MULTICAST_IF = 0x10; 195 196 /** Same as above. This option is introduced so that the behaviour 197 * with IP_MULTICAST_IF will be kept the same as before, while 198 * this new option can support setting outgoing interfaces with either 199 * IPv4 and IPv6 addresses. 200 * 201 * NOTE: make sure there is no conflict with this 202 * @see MulticastSocket#setNetworkInterface(NetworkInterface) 203 * @see MulticastSocket#getNetworkInterface() 204 * @since 1.4 205 */ 206 @Native public final static int IP_MULTICAST_IF2 = 0x1f; 207 208 /** 209 * This option enables or disables local loopback of multicast datagrams. 210 * This option is enabled by default for Multicast Sockets. 211 * @since 1.4 212 */ 213 214 @Native public final static int IP_MULTICAST_LOOP = 0x12; 215 216 /** 217 * This option sets the type-of-service or traffic class field 218 * in the IP header for a TCP or UDP socket. 219 * @since 1.4 220 */ 221 222 @Native public final static int IP_TOS = 0x3; 223 224 /** 225 * Specify a linger-on-close timeout. This option disables/enables 226 * immediate return from a <B>close()</B> of a TCP Socket. Enabling 227 * this option with a non-zero Integer <I>timeout</I> means that a 228 * <B>close()</B> will block pending the transmission and acknowledgement 229 * of all data written to the peer, at which point the socket is closed 230 * <I>gracefully</I>. Upon reaching the linger timeout, the socket is 231 * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a 232 * timeout of zero does a forceful close immediately. If the specified 233 * timeout value exceeds 65,535 it will be reduced to 65,535. 234 * <P> 235 * Valid only for TCP: SocketImpl 236 * 237 * @see Socket#setSoLinger 238 * @see Socket#getSoLinger 239 */ 240 @Native public final static int SO_LINGER = 0x0080; 241 242 /** Set a timeout on blocking Socket operations: 243 * <PRE> 244 * ServerSocket.accept(); 245 * SocketInputStream.read(); 246 * DatagramSocket.receive(); 247 * </PRE> 248 * 249 * <P> The option must be set prior to entering a blocking 250 * operation to take effect. If the timeout expires and the 251 * operation would continue to block, 252 * <B>java.io.InterruptedIOException</B> is raised. The Socket is 253 * not closed in this case. 254 * 255 * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl 256 * 257 * @see Socket#setSoTimeout 258 * @see ServerSocket#setSoTimeout 259 * @see DatagramSocket#setSoTimeout 260 */ 261 @Native public final static int SO_TIMEOUT = 0x1006; 262 263 /** 264 * Set a hint the size of the underlying buffers used by the 265 * platform for outgoing network I/O. When used in set, this is a 266 * suggestion to the kernel from the application about the size of 267 * buffers to use for the data to be sent over the socket. When 268 * used in get, this must return the size of the buffer actually 269 * used by the platform when sending out data on this socket. 270 * 271 * Valid for all sockets: SocketImpl, DatagramSocketImpl 272 * 273 * @see Socket#setSendBufferSize 274 * @see Socket#getSendBufferSize 275 * @see DatagramSocket#setSendBufferSize 276 * @see DatagramSocket#getSendBufferSize 277 */ 278 @Native public final static int SO_SNDBUF = 0x1001; 279 280 /** 281 * Set a hint the size of the underlying buffers used by the 282 * platform for incoming network I/O. When used in set, this is a 283 * suggestion to the kernel from the application about the size of 284 * buffers to use for the data to be received over the 285 * socket. When used in get, this must return the size of the 286 * buffer actually used by the platform when receiving in data on 287 * this socket. 288 * 289 * Valid for all sockets: SocketImpl, DatagramSocketImpl 290 * 291 * @see Socket#setReceiveBufferSize 292 * @see Socket#getReceiveBufferSize 293 * @see DatagramSocket#setReceiveBufferSize 294 * @see DatagramSocket#getReceiveBufferSize 295 */ 296 @Native public final static int SO_RCVBUF = 0x1002; 297 298 /** 299 * When the keepalive option is set for a TCP socket and no data 300 * has been exchanged across the socket in either direction for 301 * 2 hours (NOTE: the actual value is implementation dependent), 302 * TCP automatically sends a keepalive probe to the peer. This probe is a 303 * TCP segment to which the peer must respond. 304 * One of three responses is expected: 305 * 1. The peer responds with the expected ACK. The application is not 306 * notified (since everything is OK). TCP will send another probe 307 * following another 2 hours of inactivity. 308 * 2. The peer responds with an RST, which tells the local TCP that 309 * the peer host has crashed and rebooted. The socket is closed. 310 * 3. There is no response from the peer. The socket is closed. 311 * 312 * The purpose of this option is to detect if the peer host crashes. 313 * 314 * Valid only for TCP socket: SocketImpl 315 * 316 * @see Socket#setKeepAlive 317 * @see Socket#getKeepAlive 318 */ 319 @Native public final static int SO_KEEPALIVE = 0x0008; 320 321 /** 322 * When the OOBINLINE option is set, any TCP urgent data received on 323 * the socket will be received through the socket input stream. 324 * When the option is disabled (which is the default) urgent data 325 * is silently discarded. 326 * 327 * @see Socket#setOOBInline 328 * @see Socket#getOOBInline 329 */ 330 @Native public final static int SO_OOBINLINE = 0x1003; 331 } |