001 /*
002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.net;
027
028 /**
029 * Interface of methods to get/set socket options. This interface is
030 * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>.
031 * Subclasses of these should override the methods
032 * of this interface in order to support their own options.
033 * <P>
034 * The methods and constants which specify options in this interface are
035 * for implementation only. If you're not subclassing SocketImpl or
036 * DatagramSocketImpl, <B>you won't use these directly.</B> There are
037 * type-safe methods to get/set each of these options in Socket, ServerSocket,
038 * DatagramSocket and MulticastSocket.
039 * <P>
040 * @version 1.40, 05/05/07
041 * @author David Brown
042 */
043
044 public interface SocketOptions {
045
046 /**
047 * Enable/disable the option specified by <I>optID</I>. If the option
048 * is to be enabled, and it takes an option-specific "value", this is
049 * passed in <I>value</I>. The actual type of value is option-specific,
050 * and it is an error to pass something that isn't of the expected type:
051 * <BR><PRE>
052 * SocketImpl s;
053 * ...
054 * s.setOption(SO_LINGER, new Integer(10));
055 * // OK - set SO_LINGER w/ timeout of 10 sec.
056 * s.setOption(SO_LINGER, new Double(10));
057 * // ERROR - expects java.lang.Integer
058 *</PRE>
059 * If the requested option is binary, it can be set using this method by
060 * a java.lang.Boolean:
061 * <BR><PRE>
062 * s.setOption(TCP_NODELAY, new Boolean(true));
063 * // OK - enables TCP_NODELAY, a binary option
064 * </PRE>
065 * <BR>
066 * Any option can be disabled using this method with a Boolean(false):
067 * <BR><PRE>
068 * s.setOption(TCP_NODELAY, new Boolean(false));
069 * // OK - disables TCP_NODELAY
070 * s.setOption(SO_LINGER, new Boolean(false));
071 * // OK - disables SO_LINGER
072 * </PRE>
073 * <BR>
074 * For an option that has a notion of on and off, and requires
075 * a non-boolean parameter, setting its value to anything other than
076 * <I>Boolean(false)</I> implicitly enables it.
077 * <BR>
078 * Throws SocketException if the option is unrecognized,
079 * the socket is closed, or some low-level error occurred
080 * <BR>
081 * @param optID identifies the option
082 * @param value the parameter of the socket option
083 * @throws SocketException if the option is unrecognized,
084 * the socket is closed, or some low-level error occurred
085 * @see #getOption(int)
086 */
087 public void setOption(int optID, Object value)
088 throws SocketException;
089
090 /**
091 * Fetch the value of an option.
092 * Binary options will return java.lang.Boolean(true)
093 * if enabled, java.lang.Boolean(false) if disabled, e.g.:
094 * <BR><PRE>
095 * SocketImpl s;
096 * ...
097 * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));
098 * if (noDelay.booleanValue()) {
099 * // true if TCP_NODELAY is enabled...
100 * ...
101 * }
102 * </PRE>
103 * <P>
104 * For options that take a particular type as a parameter,
105 * getOption(int) will return the parameter's value, else
106 * it will return java.lang.Boolean(false):
107 * <PRE>
108 * Object o = s.getOption(SO_LINGER);
109 * if (o instanceof Integer) {
110 * System.out.print("Linger time is " + ((Integer)o).intValue());
111 * } else {
112 * // the true type of o is java.lang.Boolean(false);
113 * }
114 * </PRE>
115 *
116 * @param optID an <code>int</code> identifying the option to fetch
117 * @return the value of the option
118 * @throws SocketException if the socket is closed
119 * @throws SocketException if <I>optID</I> is unknown along the
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 }
|