1/* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18package java.net; 19 20 21/** 22 * Defines an interface for socket implementations to get and set socket 23 * options. It is implemented by the classes {@code SocketImpl} and {@code 24 * DatagramSocketImpl}. 25 * 26 * @see SocketImpl 27 * @see DatagramSocketImpl 28 */ 29public interface SocketOptions { 30 /** 31 * Number of seconds to wait when closing a socket if there is still some buffered data to be 32 * sent. 33 * 34 * <p>The option can be set to disabled using {@link #setOption(int, Object)} with a value of 35 * {@code Boolean.FALSE}. 36 * 37 * <p>If this option is set to 0, the TCP socket is closed forcefully and the call to 38 * {@code close} returns immediately. 39 * 40 * If this option is disabled, closing a socket will return immediately and the close will be 41 * handled in the background. 42 * 43 * <p>If this option is set to a value greater than 0, the value is interpreted as the number of 44 * seconds to wait. If all data could be sent during this time, the socket is closed normally. 45 * Otherwise the connection will be closed forcefully. 46 * 47 * <p>Valid numeric values for this option are in the range 0 to 65535 inclusive. (Larger 48 * timeouts will be treated as 65535s timeouts; roughly 18 hours.) 49 * 50 * <p>This option is intended for use with sockets in blocking mode. The behavior of this option 51 * for non-blocking sockets is undefined. 52 */ 53 public static final int SO_LINGER = 128; 54 55 /** 56 * Integer timeout in milliseconds for blocking accept or read/receive operations (but not 57 * write/send operations). A timeout of 0 means no timeout. Negative 58 * timeouts are not allowed. 59 * 60 * <p>An {@code InterruptedIOException} is thrown if this timeout expires. 61 */ 62 public static final int SO_TIMEOUT = 4102; 63 64 /** 65 * This boolean option specifies whether data is sent immediately on this socket or buffered. 66 * <p> 67 * If set to {@code Boolean.TRUE} the Nagle algorithm is disabled and there is no buffering. 68 * This could lead to low packet efficiency. When set to {@code Boolean.FALSE} the the socket 69 * implementation uses buffering to try to reach a higher packet efficiency. 70 * 71 * <p>See <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122: Requirements for Internet 72 * Hosts -- Communication Layers</a> for more information about buffering and the Nagle 73 * algorithm. 74 */ 75 public static final int TCP_NODELAY = 1; 76 77 /** 78 * This is an IPv4-only socket option whose functionality is subsumed by 79 * {@link #IP_MULTICAST_IF2} and not implemented on Android. 80 */ 81 public static final int IP_MULTICAST_IF = 16; 82 83 /** 84 * This option does not correspond to any Unix socket option and is not implemented on Android. 85 */ 86 public static final int SO_BINDADDR = 15; 87 88 /** 89 * This boolean option specifies whether a reuse of a local address is allowed when another 90 * socket has not yet been removed by the operating system. 91 * 92 * <p>For connection-oriented sockets, if this option is disabled and if there is another socket 93 * in state TIME_WAIT on a given address then another socket binding to that address would fail. 94 * Setting this value after a socket is bound has no effect. 95 * 96 * <p>For datagram sockets this option determines whether several sockets can listen on the 97 * same address; when enabled each socket will receive a copy of the datagram. 98 * 99 * <p>See <a href="https://www.ietf.org/rfc/rfc793.txt">RFC 793: Transmission Control Protocol 100 * </a> for more information about socket re-use. 101 */ 102 public static final int SO_REUSEADDR = 4; 103 104 /** 105 * The size in bytes of a socket's send buffer. This must be an integer greater than 0. 106 * This is a hint to the kernel; the kernel may use a larger buffer. 107 * 108 * <p>For datagram sockets, it is implementation-defined whether packets larger than 109 * this size can be sent. 110 */ 111 public static final int SO_SNDBUF = 4097; 112 113 /** 114 * The size in bytes of a socket's receive buffer. This must be an integer greater than 0. 115 * This is a hint to the kernel; the kernel may use a larger buffer. 116 * 117 * <p>For datagram sockets, packets larger than this value will be discarded. 118 * 119 * <p>See <a href="http://www.ietf.org/rfc/rfc1323.txt">RFC1323: TCP Extensions for High 120 * Performance</a> for more information about TCP/IP buffering. 121 */ 122 public static final int SO_RCVBUF = 4098; 123 124 /** 125 * This boolean option specifies whether the kernel sends keepalive messages on 126 * connection-oriented sockets. 127 * 128 * <p>See <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122: Requirements for Internet 129 * Hosts -- Communication Layers</a> for more information on keep-alive. 130 */ 131 public static final int SO_KEEPALIVE = 8; 132 133 /** 134 * This integer option specifies the value for the type-of-service field of the IPv4 header, 135 * or the traffic class field of the IPv6 header. These correspond to the IP_TOS and IPV6_TCLASS 136 * socket options. These may be ignored by the underlying OS. Values must be between 0 and 255 137 * inclusive. 138 * 139 * <p>See <a href="http://www.ietf.org/rfc/rfc1349.txt">RFC 1349</a> for more about IPv4 140 * and <a href="http://www.ietf.org/rfc/rfc2460.txt">RFC 2460</a> for more about IPv6. 141 */ 142 public static final int IP_TOS = 3; 143 144 /** 145 * This boolean option specifies whether the local loopback of multicast packets is 146 * enabled or disabled. This loopback is enabled by default on multicast sockets. 147 * 148 * <p>See <a href="http://tools.ietf.org/rfc/rfc1112.txt">RFC 1112: Host Extensions for IP 149 * Multicasting</a> for more information about IP multicast. 150 * 151 * <p>See {@link MulticastSocket#setLoopbackMode}. 152 */ 153 public static final int IP_MULTICAST_LOOP = 18; 154 155 /** 156 * This boolean option can be used to enable or disable broadcasting on datagram sockets. This 157 * option must be enabled to send broadcast messages. The default value is false. 158 */ 159 public static final int SO_BROADCAST = 32; 160 161 /** 162 * This boolean option specifies whether sending TCP urgent data is supported on 163 * this socket or not. 164 */ 165 public static final int SO_OOBINLINE = 4099; 166 167 /** 168 * This integer option sets the outgoing interface for multicast packets 169 * using an interface index. 170 * 171 * <p>See <a href="http://tools.ietf.org/rfc/rfc1112.txt">RFC 1112: Host Extensions for IP 172 * Multicasting</a> for more information about IP multicast. 173 */ 174 public static final int IP_MULTICAST_IF2 = 31; 175 176 /** 177 * Gets the value for the specified socket option. 178 * 179 * @return the option value. 180 * @param optID 181 * the option identifier. 182 * @throws SocketException 183 * if an error occurs reading the option value. 184 */ 185 public Object getOption(int optID) throws SocketException; 186 187 /** 188 * Sets the value of the specified socket option. 189 * 190 * @param optID 191 * the option identifier. 192 * @param val 193 * the value to be set for the option. 194 * @throws SocketException 195 * if an error occurs setting the option value. 196 */ 197 public void setOption(int optID, Object val) throws SocketException; 198} 199