core/java/android/net/LinkSocket.java

/*
 * 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);
    }
}