FileDocCategorySizeDatePackage
RouteInfo.javaAPI DocAndroid 5.1 API16398Thu Mar 12 22:22:10 GMT 2015android.net

RouteInfo

public final class RouteInfo extends Object implements android.os.Parcelable
Represents a network route.

This is used both to describe static network configuration and live network configuration information. A route contains three pieces of information:

  • a destination {@link IpPrefix} specifying the network destinations covered by this route. If this is {@code null} it indicates a default route of the address family (IPv4 or IPv6) implied by the gateway IP address.
  • a gateway {@link InetAddress} indicating the next hop to use. If this is {@code null} it indicates a directly-connected route.
  • an interface (which may be unspecified).
Either the destination or the gateway may be {@code null}, but not both. If the destination and gateway are both specified, they must be of the same address family (IPv4 or IPv6).

Fields Summary
private final IpPrefix
mDestination
The IP destination address for this route.
private final InetAddress
mGateway
The gateway address for this route.
private final String
mInterface
The interface for this route.
public static final int
RTN_UNICAST
Unicast route. @hide
public static final int
RTN_UNREACHABLE
Unreachable route. @hide
public static final int
RTN_THROW
Throw route. @hide
private final int
mType
The type of this route; one of the RTN_xxx constants above.
private final boolean
mIsHost
private final boolean
mHasGateway
public static final Creator
CREATOR
Implement the Parcelable interface.
Constructors Summary
public RouteInfo(IpPrefix destination, InetAddress gateway, String iface, int type)
Constructs a RouteInfo object. If destination is null, then gateway must be specified and the constructed route is either the IPv4 default route 0.0.0.0 if the gateway is an instance of {@link Inet4Address}, or the IPv6 default route ::/0 if gateway is an instance of {@link Inet6Address}.

destination and gateway may not both be null.

param
destination the destination prefix
param
gateway the IP address to route packets through
param
iface the interface name to send packets on
hide


                                                                                         
             
        switch (type) {
            case RTN_UNICAST:
            case RTN_UNREACHABLE:
            case RTN_THROW:
                // TODO: It would be nice to ensure that route types that don't have nexthops or
                // interfaces, such as unreachable or throw, can't be created if an interface or
                // a gateway is specified. This is a bit too complicated to do at the moment
                // because:
                //
                // - LinkProperties sets the interface on routes added to it, and modifies the
                //   interfaces of all the routes when its interface name changes.
                // - Even when the gateway is null, we store a non-null gateway here.
                //
                // For now, we just rely on the code that sets routes to do things properly.
                break;
            default:
                throw new IllegalArgumentException("Unknown route type " + type);
        }

        if (destination == null) {
            if (gateway != null) {
                if (gateway instanceof Inet4Address) {
                    destination = new IpPrefix(Inet4Address.ANY, 0);
                } else {
                    destination = new IpPrefix(Inet6Address.ANY, 0);
                }
            } else {
                // no destination, no gateway. invalid.
                throw new IllegalArgumentException("Invalid arguments passed in: " + gateway + "," +
                                                   destination);
            }
        }
        // TODO: set mGateway to null if there is no gateway. This is more correct, saves space, and
        // matches the documented behaviour. Before we can do this we need to fix all callers (e.g.,
        // ConnectivityService) to stop doing things like r.getGateway().equals(), ... .
        if (gateway == null) {
            if (destination.getAddress() instanceof Inet4Address) {
                gateway = Inet4Address.ANY;
            } else {
                gateway = Inet6Address.ANY;
            }
        }
        mHasGateway = (!gateway.isAnyLocalAddress());

        if ((destination.getAddress() instanceof Inet4Address &&
                 (gateway instanceof Inet4Address == false)) ||
                (destination.getAddress() instanceof Inet6Address &&
                 (gateway instanceof Inet6Address == false))) {
            throw new IllegalArgumentException("address family mismatch in RouteInfo constructor");
        }
        mDestination = destination;  // IpPrefix objects are immutable.
        mGateway = gateway;          // InetAddress objects are immutable.
        mInterface = iface;          // Strings are immutable.
        mType = type;
        mIsHost = isHost();
    
public RouteInfo(IpPrefix destination, InetAddress gateway, String iface)

hide

        this(destination, gateway, iface, RTN_UNICAST);
    
public RouteInfo(LinkAddress destination, InetAddress gateway, String iface)

hide

        this(destination == null ? null :
                new IpPrefix(destination.getAddress(), destination.getPrefixLength()),
                gateway, iface);
    
public RouteInfo(IpPrefix destination, InetAddress gateway)
Constructs a {@code RouteInfo} object. If destination is null, then gateway must be specified and the constructed route is either the IPv4 default route 0.0.0.0 if the gateway is an instance of {@link Inet4Address}, or the IPv6 default route ::/0 if gateway is an instance of {@link Inet6Address}.

Destination and gateway may not both be null.

param
destination the destination address and prefix in an {@link IpPrefix}
param
gateway the {@link InetAddress} to route packets through
hide

        this(destination, gateway, null);
    
public RouteInfo(LinkAddress destination, InetAddress gateway)

hide
TODO: Remove this.

        this(destination, gateway, null);
    
public RouteInfo(InetAddress gateway)
Constructs a default {@code RouteInfo} object.

param
gateway the {@link InetAddress} to route packets through
hide

        this((IpPrefix) null, gateway, null);
    
public RouteInfo(IpPrefix destination)
Constructs a {@code RouteInfo} object representing a direct connected subnet.

param
destination the {@link IpPrefix} describing the address and prefix length of the subnet.
hide

        this(destination, null, null);
    
public RouteInfo(LinkAddress destination)

hide

        this(destination, null, null);
    
public RouteInfo(IpPrefix destination, int type)

hide

        this(destination, null, null, type);
    
Methods Summary
public intdescribeContents()
Implement the Parcelable interface

        return 0;
    
public booleanequals(java.lang.Object obj)
Compares this RouteInfo object against the specified object and indicates if they are equal.

return
{@code true} if the objects are equal, {@code false} otherwise.

        if (this == obj) return true;

        if (!(obj instanceof RouteInfo)) return false;

        RouteInfo target = (RouteInfo) obj;

        return Objects.equals(mDestination, target.getDestination()) &&
                Objects.equals(mGateway, target.getGateway()) &&
                Objects.equals(mInterface, target.getInterface()) &&
                mType == target.getType();
    
public IpPrefixgetDestination()
Retrieves the destination address and prefix length in the form of an {@link IpPrefix}.

return
{@link IpPrefix} specifying the destination. This is never {@code null}.

        return mDestination;
    
public LinkAddressgetDestinationLinkAddress()
TODO: Convert callers to use IpPrefix and then remove.

hide

        return new LinkAddress(mDestination.getAddress(), mDestination.getPrefixLength());
    
public java.net.InetAddressgetGateway()
Retrieves the gateway or next hop {@link InetAddress} for this route.

return
{@link InetAddress} specifying the gateway or next hop. This may be {@code null} for a directly-connected route."

        return mGateway;
    
public java.lang.StringgetInterface()
Retrieves the interface used for this route if specified, else {@code null}.

return
The name of the interface used for this route.

        return mInterface;
    
public intgetType()
Retrieves the type of this route.

return
The type of this route; one of the {@code RTN_xxx} constants defined in this class.
hide

        return mType;
    
public booleanhasGateway()
Indicates if this route has a next hop ({@code true}) or is directly-connected ({@code false}).

return
{@code true} if a gateway is specified
hide

        return mHasGateway;
    
public inthashCode()
Returns a hashcode for this RouteInfo object.

        return (mDestination.hashCode() * 41)
                + (mGateway == null ? 0 :mGateway.hashCode() * 47)
                + (mInterface == null ? 0 :mInterface.hashCode() * 67)
                + (mType * 71);
    
public booleanisDefaultRoute()
Indicates if this route is a default route (ie, has no destination specified).

return
{@code true} if the destination has a prefix length of 0.

        return mType == RTN_UNICAST && mDestination.getPrefixLength() == 0;
    
private booleanisHost()

        return (mDestination.getAddress() instanceof Inet4Address &&
                mDestination.getPrefixLength() == 32) ||
               (mDestination.getAddress() instanceof Inet6Address &&
                mDestination.getPrefixLength() == 128);
    
public booleanisHostRoute()
Indicates if this route is a host route (ie, matches only a single host address).

return
{@code true} if the destination has a prefix length of 32 or 128 for IPv4 or IPv6, respectively.
hide

        return mIsHost;
    
public booleanisIPv4Default()
Indicates if this route is an IPv4 default route.

hide

        return isDefaultRoute() && mDestination.getAddress() instanceof Inet4Address;
    
public booleanisIPv6Default()
Indicates if this route is an IPv6 default route.

hide

        return isDefaultRoute() && mDestination.getAddress() instanceof Inet6Address;
    
public static android.net.RouteInfomakeHostRoute(java.net.InetAddress host, java.lang.String iface)

hide

        return makeHostRoute(host, null, iface);
    
public static android.net.RouteInfomakeHostRoute(java.net.InetAddress host, java.net.InetAddress gateway, java.lang.String iface)

hide

        if (host == null) return null;

        if (host instanceof Inet4Address) {
            return new RouteInfo(new IpPrefix(host, 32), gateway, iface);
        } else {
            return new RouteInfo(new IpPrefix(host, 128), gateway, iface);
        }
    
public booleanmatches(java.net.InetAddress destination)
Determines whether the destination and prefix of this route includes the specified address.

param
destination A {@link InetAddress} to test to see if it would match this route.
return
{@code true} if the destination and prefix length cover the given address.

        if (destination == null) return false;

        // match the route destination and destination with prefix length
        InetAddress dstNet = NetworkUtils.getNetworkPart(destination,
                mDestination.getPrefixLength());

        return mDestination.getAddress().equals(dstNet);
    
public static android.net.RouteInfoselectBestRoute(java.util.Collection routes, java.net.InetAddress dest)
Find the route from a Collection of routes that best matches a given address. May return null if no routes are applicable.

param
routes a Collection of RouteInfos to chose from
param
dest the InetAddress your trying to get to
return
the RouteInfo from the Collection that best fits the given address
hide

        if ((routes == null) || (dest == null)) return null;

        RouteInfo bestRoute = null;
        // pick a longest prefix match under same address type
        for (RouteInfo route : routes) {
            if (NetworkUtils.addressTypeMatches(route.mDestination.getAddress(), dest)) {
                if ((bestRoute != null) &&
                        (bestRoute.mDestination.getPrefixLength() >=
                        route.mDestination.getPrefixLength())) {
                    continue;
                }
                if (route.matches(dest)) bestRoute = route;
            }
        }
        return bestRoute;
    
public java.lang.StringtoString()
Returns a human-readable description of this object.

        String val = "";
        if (mDestination != null) val = mDestination.toString();
        if (mType == RTN_UNREACHABLE) {
            val += " unreachable";
        } else if (mType == RTN_THROW) {
            val += " throw";
        } else {
            val += " ->";
            if (mGateway != null) val += " " + mGateway.getHostAddress();
            if (mInterface != null) val += " " + mInterface;
            if (mType != RTN_UNICAST) {
                val += " unknown type " + mType;
            }
        }
        return val;
    
public voidwriteToParcel(android.os.Parcel dest, int flags)
Implement the Parcelable interface

        dest.writeParcelable(mDestination, flags);
        byte[] gatewayBytes = (mGateway == null) ? null : mGateway.getAddress();
        dest.writeByteArray(gatewayBytes);
        dest.writeString(mInterface);
        dest.writeInt(mType);