1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.net; 18 19 import android.net.LinkCapabilities; 20 import android.net.LinkProperties; 21 import android.net.LinkSocketNotifier; 22 23 import android.util.Log; 24 25 import java.io.IOException; 26 import java.net.Socket; 27 import java.net.SocketAddress; 28 import java.net.SocketTimeoutException; 29 import java.net.UnknownHostException; 30 import java.util.HashSet; 31 import java.util.Set; 32 33 /** @hide */ 34 public class LinkSocket extends Socket { 35 private final static String TAG = "LinkSocket"; 36 private final static boolean DBG = true; 37 38 /** 39 * Default constructor 40 */ 41 public LinkSocket() { 42 if (DBG) log("LinkSocket() EX"); 43 } 44 45 /** 46 * Creates a new unconnected socket. 47 * @param notifier a reference to a class that implements {@code LinkSocketNotifier} 48 */ 49 public LinkSocket(LinkSocketNotifier notifier) { 50 if (DBG) log("LinkSocket(notifier) EX"); 51 } 52 53 /** 54 * Creates a new unconnected socket usign the given proxy type. 55 * @param notifier a reference to a class that implements {@code LinkSocketNotifier} 56 * @param proxy the specified proxy for this socket 57 * @throws IllegalArgumentException if the argument proxy is null or of an invalid type. 58 * @throws SecurityException if a security manager exists and it denies the permission 59 * to connect to the given proxy. 60 */ 61 public LinkSocket(LinkSocketNotifier notifier, Proxy proxy) { 62 if (DBG) log("LinkSocket(notifier, proxy) EX"); 63 } 64 65 /** 66 * @return the {@code LinkProperties} for the socket 67 */ 68 public LinkProperties getLinkProperties() { 69 if (DBG) log("LinkProperties() EX"); 70 return new LinkProperties(); 71 } 72 73 /** 74 * Set the {@code LinkCapabilies} needed for this socket. If the socket is already connected 75 * or is a duplicate socket the request is ignored and {@code false} will 76 * be returned. A needs map can be created via the {@code createNeedsMap} static 77 * method. 78 * @param needs the needs of the socket 79 * @return {@code true} if needs are successfully set, {@code false} otherwise 80 */ 81 public boolean setNeededCapabilities(LinkCapabilities needs) { 82 if (DBG) log("setNeeds() EX"); 83 return false; 84 } 85 86 /** 87 * @return the LinkCapabilites set by setNeededCapabilities, empty if none has been set 88 */ 89 public LinkCapabilities getNeededCapabilities() { 90 if (DBG) log("getNeeds() EX"); 91 return null; 92 } 93 94 /** 95 * @return all of the {@code LinkCapabilities} of the link used by this socket 96 */ 97 public LinkCapabilities getCapabilities() { 98 if (DBG) log("getCapabilities() EX"); 99 return null; 100 } 101 102 /** 103 * Returns this LinkSockets set of capabilities, filtered according to 104 * the given {@code Set}. Capabilities in the Set but not available from 105 * the link will not be reported in the results. Capabilities of the link 106 * but not listed in the Set will also not be reported in the results. 107 * @param capabilities {@code Set} of capabilities requested 108 * @return the filtered {@code LinkCapabilities} of this LinkSocket, may be empty 109 */ 110 public LinkCapabilities getCapabilities(Set<Integer> capabilities) { 111 if (DBG) log("getCapabilities(capabilities) EX"); 112 return new LinkCapabilities(); 113 } 114 115 /** 116 * Provide the set of capabilities the application is interested in tracking 117 * for this LinkSocket. 118 * @param capabilities a {@code Set} of capabilities to track 119 */ 120 public void setTrackedCapabilities(Set<Integer> capabilities) { 121 if (DBG) log("setTrackedCapabilities(capabilities) EX"); 122 } 123 124 /** 125 * @return the {@code LinkCapabilities} that are tracked, empty if none has been set. 126 */ 127 public Set<Integer> getTrackedCapabilities() { 128 if (DBG) log("getTrackedCapabilities(capabilities) EX"); 129 return new HashSet<Integer>(); 130 } 131 132 /** 133 * Connects this socket to the given remote host address and port specified 134 * by dstName and dstPort. 135 * @param dstName the address of the remote host to connect to 136 * @param dstPort the port to connect to on the remote host 137 * @param timeout the timeout value in milliseconds or 0 for infinite timeout 138 * @throws UnknownHostException if the given dstName is invalid 139 * @throws IOException if the socket is already connected or an error occurs 140 * while connecting 141 * @throws SocketTimeoutException if the timeout fires 142 */ 143 public void connect(String dstName, int dstPort, int timeout) 144 throws UnknownHostException, IOException, SocketTimeoutException { 145 if (DBG) log("connect(dstName, dstPort, timeout) EX"); 146 } 147 148 /** 149 * Connects this socket to the given remote host address and port specified 150 * by dstName and dstPort. 151 * @param dstName the address of the remote host to connect to 152 * @param dstPort the port to connect to on the remote host 153 * @throws UnknownHostException if the given dstName is invalid 154 * @throws IOException if the socket is already connected or an error occurs 155 * while connecting 156 */ 157 public void connect(String dstName, int dstPort) 158 throws UnknownHostException, IOException { 159 if (DBG) log("connect(dstName, dstPort, timeout) EX"); 160 } 161 162 /** 163 * Connects this socket to the given remote host address and port specified 164 * by the SocketAddress with the specified timeout. 165 * @deprecated Use {@code connect(String dstName, int dstPort, int timeout)} 166 * instead. Using this method may result in reduced functionality. 167 * @param remoteAddr the address and port of the remote host to connect to 168 * @throws IllegalArgumentException if the given SocketAddress is invalid 169 * @throws IOException if the socket is already connected or an error occurs 170 * while connecting 171 * @throws SocketTimeoutException if the timeout expires 172 */ 173 @Override 174 @Deprecated 175 public void connect(SocketAddress remoteAddr, int timeout) 176 throws IOException, SocketTimeoutException { 177 if (DBG) log("connect(remoteAddr, timeout) EX DEPRECATED"); 178 } 179 180 /** 181 * Connects this socket to the given remote host address and port specified 182 * by the SocketAddress. 183 * TODO add comment on all these that the network selection happens during connect 184 * and may take 30 seconds 185 * @deprecated Use {@code connect(String dstName, int dstPort)} 186 * Using this method may result in reduced functionality. 187 * @param remoteAddr the address and port of the remote host to connect to. 188 * @throws IllegalArgumentException if the SocketAddress is invalid or not supported. 189 * @throws IOException if the socket is already connected or an error occurs 190 * while connecting 191 */ 192 @Override 193 @Deprecated 194 public void connect(SocketAddress remoteAddr) throws IOException { 195 if (DBG) log("connect(remoteAddr) EX DEPRECATED"); 196 } 197 198 /** 199 * Connect a duplicate socket socket to the same remote host address and port 200 * as the original with a timeout parameter. 201 * @param timeout the timeout value in milliseconds or 0 for infinite timeout 202 * @throws IOException if the socket is already connected or an error occurs 203 * while connecting 204 */ 205 public void connect(int timeout) throws IOException { 206 if (DBG) log("connect(timeout) EX"); 207 } 208 209 /** 210 * Connect a duplicate socket socket to the same remote host address and port 211 * as the original. 212 * @throws IOException if the socket is already connected or an error occurs 213 * while connecting 214 */ 215 public void connect() throws IOException { 216 if (DBG) log("connect() EX"); 217 } 218 219 /** 220 * Closes the socket. It is not possible to reconnect or rebind to this 221 * socket thereafter which means a new socket instance has to be created. 222 * @throws IOException if an error occurs while closing the socket 223 */ 224 @Override 225 public synchronized void close() throws IOException { 226 if (DBG) log("close() EX"); 227 } 228 229 /** 230 * Request that a new LinkSocket be created using a different radio 231 * (such as WiFi or 3G) than the current LinkSocket. If a different 232 * radio is available a call back will be made via {@code onBetterLinkAvail}. 233 * If unable to find a better radio, application will be notified via 234 * {@code onNewLinkUnavailable} 235 * @see LinkSocketNotifier#onBetterLinkAvailable(LinkSocket, LinkSocket) 236 * @param linkRequestReason reason for requesting a new link. 237 */ 238 public void requestNewLink(LinkRequestReason linkRequestReason) { 239 if (DBG) log("requestNewLink(linkRequestReason) EX"); 240 } 241 242 /** 243 * @deprecated LinkSocket will automatically pick the optimum interface 244 * to bind to 245 * @param localAddr the specific address and port on the local machine 246 * to bind to 247 * @throws IOException always as this method is deprecated for LinkSocket 248 */ 249 @Override 250 @Deprecated 251 public void bind(SocketAddress localAddr) throws UnsupportedOperationException { 252 if (DBG) log("bind(localAddr) EX throws IOException"); 253 throw new UnsupportedOperationException("bind is deprecated for LinkSocket"); 254 } 255 256 /** 257 * Reason codes an application can specify when requesting for a new link. 258 * TODO: need better documentation 259 */ 260 public static final class LinkRequestReason { 261 /** No constructor */ 262 private LinkRequestReason() {} 263 264 /** This link is working properly */ 265 public static final int LINK_PROBLEM_NONE = 0; 266 /** This link has an unknown issue */ 267 public static final int LINK_PROBLEM_UNKNOWN = 1; 268 } 269 270 /** 271 * Debug logging 272 */ 273 protected static void log(String s) { 274 Log.d(TAG, s); 275 } 276 } 277
