1/*
2 * Copyright (c) 1996, 2006, 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
26package 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
44public interface SocketOptions {
45
46    /**
47     * Enable/disable the option specified by <I>optID</I>.  If the option
48     * is to be enabled, and it takes an option-specific "value",  this is
49     * passed in <I>value</I>.  The actual type of value is option-specific,
50     * and it is an error to pass something that isn't of the expected type:
51     * <BR><PRE>
52     * SocketImpl s;
53     * ...
54     * s.setOption(SO_LINGER, new Integer(10));
55     *    // OK - set SO_LINGER w/ timeout of 10 sec.
56     * s.setOption(SO_LINGER, new Double(10));
57     *    // ERROR - expects java.lang.Integer
58     *</PRE>
59     * If the requested option is binary, it can be set using this method by
60     * a java.lang.Boolean:
61     * <BR><PRE>
62     * s.setOption(TCP_NODELAY, new Boolean(true));
63     *    // OK - enables TCP_NODELAY, a binary option
64     * </PRE>
65     * <BR>
66     * Any option can be disabled using this method with a Boolean(false):
67     * <BR><PRE>
68     * s.setOption(TCP_NODELAY, new Boolean(false));
69     *    // OK - disables TCP_NODELAY
70     * s.setOption(SO_LINGER, new Boolean(false));
71     *    // OK - disables SO_LINGER
72     * </PRE>
73     * <BR>
74     * For an option that has a notion of on and off, and requires
75     * a non-boolean parameter, setting its value to anything other than
76     * <I>Boolean(false)</I> implicitly enables it.
77     * <BR>
78     * Throws SocketException if the option is unrecognized,
79     * the socket is closed, or some low-level error occurred
80     * <BR>
81     * @param optID identifies the option
82     * @param value the parameter of the socket option
83     * @throws SocketException if the option is unrecognized,
84     * the socket is closed, or some low-level error occurred
85     * @see #getOption(int)
86     */
87    public void
88        setOption(int optID, Object value) throws SocketException;
89
90    /**
91     * Fetch the value of an option.
92     * Binary options will return java.lang.Boolean(true)
93     * if enabled, java.lang.Boolean(false) if disabled, e.g.:
94     * <BR><PRE>
95     * SocketImpl s;
96     * ...
97     * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));
98     * if (noDelay.booleanValue()) {
99     *     // 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}
330