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 18 package java.net; 19 20 import java.io.FileDescriptor; 21 import java.io.IOException; 22 import libcore.io.IoBridge; 23 24 /** 25 * The abstract superclass for datagram and multicast socket implementations. 26 */ 27 public abstract class DatagramSocketImpl implements SocketOptions { 28 29 /** 30 * File descriptor that is used to address this socket. 31 */ 32 protected FileDescriptor fd; 33 34 /** 35 * The number of the local port to which this socket is bound. 36 */ 37 protected int localPort; 38 39 /** 40 * Constructs an unbound datagram socket implementation. 41 */ 42 public DatagramSocketImpl() { 43 localPort = -1; 44 } 45 46 /** 47 * Binds the datagram socket to the given localhost/port. Sockets must be 48 * bound prior to attempting to send or receive data. 49 * 50 * @param port 51 * the port on the localhost to bind. 52 * @param addr 53 * the address on the multihomed localhost to bind. 54 * @throws SocketException 55 * if an error occurs while binding, for example, if the port 56 * has been already bound. 57 */ 58 protected abstract void bind(int port, InetAddress addr) throws SocketException; 59 60 /** 61 * Closes this socket. 62 */ 63 protected abstract void close(); 64 65 /** 66 * This method allocates the socket descriptor in the underlying operating 67 * system. 68 * 69 * @throws SocketException 70 * if an error occurs while creating the socket. 71 */ 72 protected abstract void create() throws SocketException; 73 74 /** 75 * Gets the {@code FileDescriptor} of this datagram socket, which is invalid 76 * if the socket is closed or not bound. 77 * 78 * @return the current file descriptor of this socket. 79 */ 80 protected FileDescriptor getFileDescriptor() { 81 return fd; 82 } 83 84 /** 85 * Returns the local address to which the socket is bound. 86 */ 87 InetAddress getLocalAddress() { 88 return IoBridge.getSocketLocalAddress(fd); 89 } 90 91 /** 92 * Returns the local port to which this socket is bound. 93 */ 94 protected int getLocalPort() { 95 return localPort; 96 } 97 98 /** 99 * Gets the time-to-live (TTL) for multicast packets sent on this socket. 100 * 101 * @return the time-to-live option as a byte value. 102 * @throws IOException 103 * if an error occurs while getting the time-to-live option 104 * value. 105 * @deprecated Replaced by {@link #getTimeToLive} 106 * @see #getTimeToLive() 107 */ 108 @Deprecated 109 protected abstract byte getTTL() throws IOException; 110 111 /** 112 * Gets the time-to-live (TTL) for multicast packets sent on this socket. 113 * The TTL option defines how many routers a packet may be pass before it is 114 * discarded. 115 * 116 * @return the time-to-live option as an integer value. 117 * @throws IOException 118 * if an error occurs while getting the time-to-live option 119 * value. 120 */ 121 protected abstract int getTimeToLive() throws IOException; 122 123 /** 124 * Adds this socket to the multicast group {@code addr}. A socket must join 125 * a group before being able to receive data. Further, a socket may be a 126 * member of multiple groups but may join any group only once. 127 * 128 * @param addr 129 * the multicast group to which this socket has to be joined. 130 * @throws IOException 131 * if an error occurs while joining the specified multicast 132 * group. 133 */ 134 protected abstract void join(InetAddress addr) throws IOException; 135 136 /** 137 * Adds this socket to the multicast group {@code addr}. A socket must join 138 * a group before being able to receive data. Further, a socket may be a 139 * member of multiple groups but may join any group only once. 140 * 141 * @param addr 142 * the multicast group to which this socket has to be joined. 143 * @param netInterface 144 * the local network interface which will receive the multicast 145 * datagram packets. 146 * @throws IOException 147 * if an error occurs while joining the specified multicast 148 * group. 149 */ 150 protected abstract void joinGroup(SocketAddress addr, 151 NetworkInterface netInterface) throws IOException; 152 153 /** 154 * Removes this socket from the multicast group {@code addr}. 155 * 156 * @param addr 157 * the multicast group to be left. 158 * @throws IOException 159 * if an error occurs while leaving the group or no multicast 160 * address was assigned. 161 */ 162 protected abstract void leave(InetAddress addr) throws IOException; 163 164 /** 165 * Removes this socket from the multicast group {@code addr}. 166 * 167 * @param addr 168 * the multicast group to be left. 169 * @param netInterface 170 * the local network interface on which this socket has to be 171 * removed. 172 * @throws IOException 173 * if an error occurs while leaving the group. 174 */ 175 protected abstract void leaveGroup(SocketAddress addr, 176 NetworkInterface netInterface) throws IOException; 177 178 /** 179 * Peeks at the incoming packet to this socket and returns the address of 180 * the {@code sender}. The method will block until a packet is received or 181 * timeout expires. 182 * 183 * @param sender 184 * the origin address of a packet. 185 * @return the address of {@code sender} as an integer value. 186 * @throws IOException 187 * if an error or a timeout occurs while reading the address. 188 */ 189 protected abstract int peek(InetAddress sender) throws IOException; 190 191 /** 192 * Receives data and stores it in the supplied datagram packet {@code pack}. 193 * This call will block until either data has been received or, if a timeout 194 * is set, the timeout has expired. If the timeout expires an {@code 195 * InterruptedIOException} is thrown. 196 * 197 * @param pack 198 * the datagram packet container to fill in the received data. 199 * @throws IOException 200 * if an error or timeout occurs while receiving data. 201 */ 202 protected abstract void receive(DatagramPacket pack) throws IOException; 203 204 /** 205 * Sends the given datagram packet {@code pack}. The packet contains the 206 * data and the address and port information of the target host as well. 207 * 208 * @param pack 209 * the datagram packet to be sent. 210 * @throws IOException 211 * if an error occurs while sending the packet. 212 */ 213 protected abstract void send(DatagramPacket pack) throws IOException; 214 215 /** 216 * Sets the time-to-live (TTL) option for multicast packets sent on this 217 * socket. 218 * 219 * @param ttl 220 * the time-to-live option value. Valid values are 0 < ttl 221 * <= 255. 222 * @throws IOException 223 * if an error occurs while setting the option. 224 */ 225 protected abstract void setTimeToLive(int ttl) throws IOException; 226 227 /** 228 * Sets the time-to-live (TTL) option for multicast packets sent on this 229 * socket. 230 * 231 * @param ttl 232 * the time-to-live option value. Valid values are 0 < ttl 233 * <= 255. 234 * @throws IOException 235 * if an error occurs while setting the option. 236 * @deprecated Replaced by {@link #setTimeToLive} 237 * @see #setTimeToLive(int) 238 */ 239 @Deprecated 240 protected abstract void setTTL(byte ttl) throws IOException; 241 242 /** 243 * Connects this socket to the specified remote address and port. 244 * 245 * @param inetAddr 246 * the address of the target host which has to be connected. 247 * @param port 248 * the port on the target host which has to be connected. 249 * @throws SocketException 250 * if the datagram socket cannot be connected to the 251 * specified remote address and port. 252 */ 253 protected void connect(InetAddress inetAddr, int port) 254 throws SocketException { 255 // do nothing 256 } 257 258 /** 259 * Disconnects this socket from the remote host. 260 */ 261 protected void disconnect() { 262 // do nothing 263 } 264 265 /** 266 * Receives data into the supplied datagram packet by peeking. The data is 267 * not removed from socket buffer and can be received again by another 268 * {@code peekData()} or {@code receive()} call. This call blocks until 269 * either data has been received or, if a timeout is set, the timeout has 270 * been expired. 271 * 272 * @param pack 273 * the datagram packet used to store the data. 274 * @return the port the packet was received from. 275 * @throws IOException 276 * if an error occurs while peeking at the data. 277 */ 278 protected abstract int peekData(DatagramPacket pack) throws IOException; 279 } 280
