| /* |
| * Copyright (C) 2010 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.net; |
| |
| import android.net.LinkCapabilities; |
| import android.net.LinkProperties; |
| import android.net.LinkSocketNotifier; |
| |
| import android.util.Log; |
| |
| import java.io.IOException; |
| import java.net.Socket; |
| import java.net.SocketAddress; |
| import java.net.SocketTimeoutException; |
| import java.net.UnknownHostException; |
| import java.util.HashSet; |
| import java.util.Set; |
| |
| /** @hide */ |
| public class LinkSocket extends Socket { |
| private final static String TAG = "LinkSocket"; |
| private final static boolean DBG = true; |
| |
| /** |
| * Default constructor |
| */ |
| public LinkSocket() { |
| if (DBG) log("LinkSocket() EX"); |
| } |
| |
| /** |
| * Creates a new unconnected socket. |
| * @param notifier a reference to a class that implements {@code LinkSocketNotifier} |
| */ |
| public LinkSocket(LinkSocketNotifier notifier) { |
| if (DBG) log("LinkSocket(notifier) EX"); |
| } |
| |
| /** |
| * Creates a new unconnected socket usign the given proxy type. |
| * @param notifier a reference to a class that implements {@code LinkSocketNotifier} |
| * @param proxy the specified proxy for this socket |
| * @throws IllegalArgumentException if the argument proxy is null or of an invalid type. |
| * @throws SecurityException if a security manager exists and it denies the permission |
| * to connect to the given proxy. |
| */ |
| public LinkSocket(LinkSocketNotifier notifier, Proxy proxy) { |
| if (DBG) log("LinkSocket(notifier, proxy) EX"); |
| } |
| |
| /** |
| * @return the {@code LinkProperties} for the socket |
| */ |
| public LinkProperties getLinkProperties() { |
| if (DBG) log("LinkProperties() EX"); |
| return new LinkProperties(); |
| } |
| |
| /** |
| * Set the {@code LinkCapabilies} needed for this socket. If the socket is already connected |
| * or is a duplicate socket the request is ignored and {@code false} will |
| * be returned. A needs map can be created via the {@code createNeedsMap} static |
| * method. |
| * @param needs the needs of the socket |
| * @return {@code true} if needs are successfully set, {@code false} otherwise |
| */ |
| public boolean setNeededCapabilities(LinkCapabilities needs) { |
| if (DBG) log("setNeeds() EX"); |
| return false; |
| } |
| |
| /** |
| * @return the LinkCapabilites set by setNeededCapabilities, empty if none has been set |
| */ |
| public LinkCapabilities getNeededCapabilities() { |
| if (DBG) log("getNeeds() EX"); |
| return null; |
| } |
| |
| /** |
| * @return all of the {@code LinkCapabilities} of the link used by this socket |
| */ |
| public LinkCapabilities getCapabilities() { |
| if (DBG) log("getCapabilities() EX"); |
| return null; |
| } |
| |
| /** |
| * Returns this LinkSockets set of capabilities, filtered according to |
| * the given {@code Set}. Capabilities in the Set but not available from |
| * the link will not be reported in the results. Capabilities of the link |
| * but not listed in the Set will also not be reported in the results. |
| * @param capabilities {@code Set} of capabilities requested |
| * @return the filtered {@code LinkCapabilities} of this LinkSocket, may be empty |
| */ |
| public LinkCapabilities getCapabilities(Set<Integer> capabilities) { |
| if (DBG) log("getCapabilities(capabilities) EX"); |
| return new LinkCapabilities(); |
| } |
| |
| /** |
| * Provide the set of capabilities the application is interested in tracking |
| * for this LinkSocket. |
| * @param capabilities a {@code Set} of capabilities to track |
| */ |
| public void setTrackedCapabilities(Set<Integer> capabilities) { |
| if (DBG) log("setTrackedCapabilities(capabilities) EX"); |
| } |
| |
| /** |
| * @return the {@code LinkCapabilities} that are tracked, empty if none has been set. |
| */ |
| public Set<Integer> getTrackedCapabilities() { |
| if (DBG) log("getTrackedCapabilities(capabilities) EX"); |
| return new HashSet<Integer>(); |
| } |
| |
| /** |
| * Connects this socket to the given remote host address and port specified |
| * by dstName and dstPort. |
| * @param dstName the address of the remote host to connect to |
| * @param dstPort the port to connect to on the remote host |
| * @param timeout the timeout value in milliseconds or 0 for infinite timeout |
| * @throws UnknownHostException if the given dstName is invalid |
| * @throws IOException if the socket is already connected or an error occurs |
| * while connecting |
| * @throws SocketTimeoutException if the timeout fires |
| */ |
| public void connect(String dstName, int dstPort, int timeout) |
| throws UnknownHostException, IOException, SocketTimeoutException { |
| if (DBG) log("connect(dstName, dstPort, timeout) EX"); |
| } |
| |
| /** |
| * Connects this socket to the given remote host address and port specified |
| * by dstName and dstPort. |
| * @param dstName the address of the remote host to connect to |
| * @param dstPort the port to connect to on the remote host |
| * @throws UnknownHostException if the given dstName is invalid |
| * @throws IOException if the socket is already connected or an error occurs |
| * while connecting |
| */ |
| public void connect(String dstName, int dstPort) |
| throws UnknownHostException, IOException { |
| if (DBG) log("connect(dstName, dstPort, timeout) EX"); |
| } |
| |
| /** |
| * Connects this socket to the given remote host address and port specified |
| * by the SocketAddress with the specified timeout. |
| * @deprecated Use {@code connect(String dstName, int dstPort, int timeout)} |
| * instead. Using this method may result in reduced functionality. |
| * @param remoteAddr the address and port of the remote host to connect to |
| * @throws IllegalArgumentException if the given SocketAddress is invalid |
| * @throws IOException if the socket is already connected or an error occurs |
| * while connecting |
| * @throws SocketTimeoutException if the timeout expires |
| */ |
| @Override |
| @Deprecated |
| public void connect(SocketAddress remoteAddr, int timeout) |
| throws IOException, SocketTimeoutException { |
| if (DBG) log("connect(remoteAddr, timeout) EX DEPRECATED"); |
| } |
| |
| /** |
| * Connects this socket to the given remote host address and port specified |
| * by the SocketAddress. |
| * TODO add comment on all these that the network selection happens during connect |
| * and may take 30 seconds |
| * @deprecated Use {@code connect(String dstName, int dstPort)} |
| * Using this method may result in reduced functionality. |
| * @param remoteAddr the address and port of the remote host to connect to. |
| * @throws IllegalArgumentException if the SocketAddress is invalid or not supported. |
| * @throws IOException if the socket is already connected or an error occurs |
| * while connecting |
| */ |
| @Override |
| @Deprecated |
| public void connect(SocketAddress remoteAddr) throws IOException { |
| if (DBG) log("connect(remoteAddr) EX DEPRECATED"); |
| } |
| |
| /** |
| * Connect a duplicate socket socket to the same remote host address and port |
| * as the original with a timeout parameter. |
| * @param timeout the timeout value in milliseconds or 0 for infinite timeout |
| * @throws IOException if the socket is already connected or an error occurs |
| * while connecting |
| */ |
| public void connect(int timeout) throws IOException { |
| if (DBG) log("connect(timeout) EX"); |
| } |
| |
| /** |
| * Connect a duplicate socket socket to the same remote host address and port |
| * as the original. |
| * @throws IOException if the socket is already connected or an error occurs |
| * while connecting |
| */ |
| public void connect() throws IOException { |
| if (DBG) log("connect() EX"); |
| } |
| |
| /** |
| * Closes the socket. It is not possible to reconnect or rebind to this |
| * socket thereafter which means a new socket instance has to be created. |
| * @throws IOException if an error occurs while closing the socket |
| */ |
| @Override |
| public synchronized void close() throws IOException { |
| if (DBG) log("close() EX"); |
| } |
| |
| /** |
| * Request that a new LinkSocket be created using a different radio |
| * (such as WiFi or 3G) than the current LinkSocket. If a different |
| * radio is available a call back will be made via {@code onBetterLinkAvail}. |
| * If unable to find a better radio, application will be notified via |
| * {@code onNewLinkUnavailable} |
| * @see LinkSocketNotifier#onBetterLinkAvailable(LinkSocket, LinkSocket) |
| * @param linkRequestReason reason for requesting a new link. |
| */ |
| public void requestNewLink(LinkRequestReason linkRequestReason) { |
| if (DBG) log("requestNewLink(linkRequestReason) EX"); |
| } |
| |
| /** |
| * @deprecated LinkSocket will automatically pick the optimum interface |
| * to bind to |
| * @param localAddr the specific address and port on the local machine |
| * to bind to |
| * @throws IOException always as this method is deprecated for LinkSocket |
| */ |
| @Override |
| @Deprecated |
| public void bind(SocketAddress localAddr) throws UnsupportedOperationException { |
| if (DBG) log("bind(localAddr) EX throws IOException"); |
| throw new UnsupportedOperationException("bind is deprecated for LinkSocket"); |
| } |
| |
| /** |
| * Reason codes an application can specify when requesting for a new link. |
| * TODO: need better documentation |
| */ |
| public static final class LinkRequestReason { |
| /** No constructor */ |
| private LinkRequestReason() {} |
| |
| /** This link is working properly */ |
| public static final int LINK_PROBLEM_NONE = 0; |
| /** This link has an unknown issue */ |
| public static final int LINK_PROBLEM_UNKNOWN = 1; |
| } |
| |
| /** |
| * Debug logging |
| */ |
| protected static void log(String s) { |
| Log.d(TAG, s); |
| } |
| } |
