core/java/android/net/LinkAddress.java

   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.os.Parcel;
  20 import android.os.Parcelable;
  21 import android.util.Pair;
  22
  23 import java.net.Inet4Address;
  24 import java.net.Inet6Address;
  25 import java.net.InetAddress;
  26 import java.net.InterfaceAddress;
  27 import java.net.UnknownHostException;
  28
  29 import static android.system.OsConstants.IFA_F_DADFAILED;
  30 import static android.system.OsConstants.IFA_F_DEPRECATED;
  31 import static android.system.OsConstants.IFA_F_OPTIMISTIC;
  32 import static android.system.OsConstants.IFA_F_TENTATIVE;
  33 import static android.system.OsConstants.RT_SCOPE_HOST;
  34 import static android.system.OsConstants.RT_SCOPE_LINK;
  35 import static android.system.OsConstants.RT_SCOPE_SITE;
  36 import static android.system.OsConstants.RT_SCOPE_UNIVERSE;
  37
  38 /**
  39  * Identifies an IP address on a network link.
  40  *
  41  * A {@code LinkAddress} consists of:
  42  * <ul>
  43  * <li>An IP address and prefix length (e.g., {@code 2001:db8::1/64} or {@code 192.0.2.1/24}).
  44  * The address must be unicast, as multicast addresses cannot be assigned to interfaces.
  45  * <li>Address flags: A bitmask of {@code OsConstants.IFA_F_*} values representing properties
  46  * of the address (e.g., {@code android.system.OsConstants.IFA_F_OPTIMISTIC}).
  47  * <li>Address scope: One of the {@code OsConstants.IFA_F_*} values; defines the scope in which
  48  * the address is unique (e.g.,
  49  * {@code android.system.OsConstants.RT_SCOPE_LINK} or
  50  * {@code android.system.OsConstants.RT_SCOPE_UNIVERSE}).
  51  * </ul>
  52  */
  53 public class LinkAddress implements Parcelable {
  54     /**
  55      * IPv4 or IPv6 address.
  56      */
  57     private InetAddress address;
  58
  59     /**
  60      * Prefix length.
  61      */
  62     private int prefixLength;
  63
  64     /**
  65      * Address flags. A bitmask of IFA_F_* values.
  66      */
  67     private int flags;
  68
  69     /**
  70      * Address scope. One of the RT_SCOPE_* constants.
  71      */
  72     private int scope;
  73
  74     /**
  75      * Utility function to determines the scope of a unicast address. Per RFC 4291 section 2.5 and
  76      * RFC 6724 section 3.2.
  77      * @hide
  78      */
  79     static int scopeForUnicastAddress(InetAddress addr) {
  80         if (addr.isAnyLocalAddress()) {
  81             return RT_SCOPE_HOST;
  82         }
  83
  84         if (addr.isLoopbackAddress() || addr.isLinkLocalAddress()) {
  85             return RT_SCOPE_LINK;
  86         }
  87
  88         // isSiteLocalAddress() returns true for private IPv4 addresses, but RFC 6724 section 3.2
  89         // says that they are assigned global scope.
  90         if (!(addr instanceof Inet4Address) && addr.isSiteLocalAddress()) {
  91             return RT_SCOPE_SITE;
  92         }
  93
  94         return RT_SCOPE_UNIVERSE;
  95     }
  96
  97     /**
  98      * Utility function to check if |address| is a Unique Local IPv6 Unicast Address
  99      * (a.k.a. "ULA"; RFC 4193).
 100      *
 101      * Per RFC 4193 section 8, fc00::/7 identifies these addresses.
 102      */
 103     private boolean isIPv6ULA() {
 104         if (address != null && address instanceof Inet6Address) {
 105             byte[] bytes = address.getAddress();
 106             return ((bytes[0] & (byte)0xfc) == (byte)0xfc);
 107         }
 108         return false;
 109     }
 110
 111     /**
 112      * Utility function for the constructors.
 113      */
 114     private void init(InetAddress address, int prefixLength, int flags, int scope) {
 115         if (address == null ||
 116                 address.isMulticastAddress() ||
 117                 prefixLength < 0 ||
 118                 ((address instanceof Inet4Address) && prefixLength > 32) ||
 119                 (prefixLength > 128)) {
 120             throw new IllegalArgumentException("Bad LinkAddress params " + address +
 121                     "/" + prefixLength);
 122         }
 123         this.address = address;
 124         this.prefixLength = prefixLength;
 125         this.flags = flags;
 126         this.scope = scope;
 127     }
 128
 129     /**
 130      * Constructs a new {@code LinkAddress} from an {@code InetAddress} and prefix length, with
 131      * the specified flags and scope. Flags and scope are not checked for validity.
 132      * @param address The IP address.
 133      * @param prefixLength The prefix length.
 134      * @param flags A bitmask of {@code IFA_F_*} values representing properties of the address.
 135      * @param scope An integer defining the scope in which the address is unique (e.g.,
 136      *              {@link OsConstants#RT_SCOPE_LINK} or {@link OsConstants#RT_SCOPE_SITE}).
 137      * @hide
 138      */
 139     public LinkAddress(InetAddress address, int prefixLength, int flags, int scope) {
 140         init(address, prefixLength, flags, scope);
 141     }
 142
 143     /**
 144      * Constructs a new {@code LinkAddress} from an {@code InetAddress} and a prefix length.
 145      * The flags are set to zero and the scope is determined from the address.
 146      * @param address The IP address.
 147      * @param prefixLength The prefix length.
 148      * @hide
 149      */
 150     public LinkAddress(InetAddress address, int prefixLength) {
 151         this(address, prefixLength, 0, 0);
 152         this.scope = scopeForUnicastAddress(address);
 153     }
 154
 155     /**
 156      * Constructs a new {@code LinkAddress} from an {@code InterfaceAddress}.
 157      * The flags are set to zero and the scope is determined from the address.
 158      * @param interfaceAddress The interface address.
 159      * @hide
 160      */
 161     public LinkAddress(InterfaceAddress interfaceAddress) {
 162         this(interfaceAddress.getAddress(),
 163              interfaceAddress.getNetworkPrefixLength());
 164     }
 165
 166     /**
 167      * Constructs a new {@code LinkAddress} from a string such as "192.0.2.5/24" or
 168      * "2001:db8::1/64". The flags are set to zero and the scope is determined from the address.
 169      * @param string The string to parse.
 170      * @hide
 171      */
 172     public LinkAddress(String address) {
 173         this(address, 0, 0);
 174         this.scope = scopeForUnicastAddress(this.address);
 175     }
 176
 177     /**
 178      * Constructs a new {@code LinkAddress} from a string such as "192.0.2.5/24" or
 179      * "2001:db8::1/64", with the specified flags and scope.
 180      * @param string The string to parse.
 181      * @param flags The address flags.
 182      * @param scope The address scope.
 183      * @hide
 184      */
 185     public LinkAddress(String address, int flags, int scope) {
 186         // This may throw an IllegalArgumentException; catching it is the caller's responsibility.
 187         Pair<InetAddress, Integer> ipAndMask = NetworkUtils.parseIpAndMask(address);
 188         init(ipAndMask.first, ipAndMask.second, flags, scope);
 189     }
 190
 191     /**
 192      * Returns a string representation of this address, such as "192.0.2.1/24" or "2001:db8::1/64".
 193      * The string representation does not contain the flags and scope, just the address and prefix
 194      * length.
 195      */
 196     @Override
 197     public String toString() {
 198         return address.getHostAddress() + "/" + prefixLength;
 199     }
 200
 201     /**
 202      * Compares this {@code LinkAddress} instance against {@code obj}. Two addresses are equal if
 203      * their address, prefix length, flags and scope are equal. Thus, for example, two addresses
 204      * that have the same address and prefix length are not equal if one of them is deprecated and
 205      * the other is not.
 206      *
 207      * @param obj the object to be tested for equality.
 208      * @return {@code true} if both objects are equal, {@code false} otherwise.
 209      */
 210     @Override
 211     public boolean equals(Object obj) {
 212         if (!(obj instanceof LinkAddress)) {
 213             return false;
 214         }
 215         LinkAddress linkAddress = (LinkAddress) obj;
 216         return this.address.equals(linkAddress.address) &&
 217             this.prefixLength == linkAddress.prefixLength &&
 218             this.flags == linkAddress.flags &&
 219             this.scope == linkAddress.scope;
 220     }
 221
 222     /**
 223      * Returns a hashcode for this address.
 224      */
 225     @Override
 226     public int hashCode() {
 227         return address.hashCode() + 11 * prefixLength + 19 * flags + 43 * scope;
 228     }
 229
 230     /**
 231      * Determines whether this {@code LinkAddress} and the provided {@code LinkAddress}
 232      * represent the same address. Two {@code LinkAddresses} represent the same address
 233      * if they have the same IP address and prefix length, even if their properties are
 234      * different.
 235      *
 236      * @param other the {@code LinkAddress} to compare to.
 237      * @return {@code true} if both objects have the same address and prefix length, {@code false}
 238      * otherwise.
 239      * @hide
 240      */
 241     public boolean isSameAddressAs(LinkAddress other) {
 242         return address.equals(other.address) && prefixLength == other.prefixLength;
 243     }
 244
 245     /**
 246      * Returns the {@link InetAddress} of this {@code LinkAddress}.
 247      */
 248     public InetAddress getAddress() {
 249         return address;
 250     }
 251
 252     /**
 253      * Returns the prefix length of this {@code LinkAddress}.
 254      */
 255     public int getPrefixLength() {
 256         return prefixLength;
 257     }
 258
 259     /**
 260      * Returns the prefix length of this {@code LinkAddress}.
 261      * TODO: Delete all callers and remove in favour of getPrefixLength().
 262      * @hide
 263      */
 264     public int getNetworkPrefixLength() {
 265         return getPrefixLength();
 266     }
 267
 268     /**
 269      * Returns the flags of this {@code LinkAddress}.
 270      */
 271     public int getFlags() {
 272         return flags;
 273     }
 274
 275     /**
 276      * Returns the scope of this {@code LinkAddress}.
 277      */
 278     public int getScope() {
 279         return scope;
 280     }
 281
 282     /**
 283      * Returns true if this {@code LinkAddress} is global scope and preferred.
 284      * @hide
 285      */
 286     public boolean isGlobalPreferred() {
 287         /**
 288          * Note that addresses flagged as IFA_F_OPTIMISTIC are
 289          * simultaneously flagged as IFA_F_TENTATIVE (when the tentative
 290          * state has cleared either DAD has succeeded or failed, and both
 291          * flags are cleared regardless).
 292          */
 293         return (scope == RT_SCOPE_UNIVERSE &&
 294                 !isIPv6ULA() &&
 295                 (flags & (IFA_F_DADFAILED | IFA_F_DEPRECATED)) == 0L &&
 296                 ((flags & IFA_F_TENTATIVE) == 0L || (flags & IFA_F_OPTIMISTIC) != 0L));
 297     }
 298
 299     /**
 300      * Implement the Parcelable interface.
 301      */
 302     public int describeContents() {
 303         return 0;
 304     }
 305
 306     /**
 307      * Implement the Parcelable interface.
 308      */
 309     public void writeToParcel(Parcel dest, int flags) {
 310         dest.writeByteArray(address.getAddress());
 311         dest.writeInt(prefixLength);
 312         dest.writeInt(this.flags);
 313         dest.writeInt(scope);
 314     }
 315
 316     /**
 317      * Implement the Parcelable interface.
 318      */
 319     public static final Creator<LinkAddress> CREATOR =
 320         new Creator<LinkAddress>() {
 321             public LinkAddress createFromParcel(Parcel in) {
 322                 InetAddress address = null;
 323                 try {
 324                     address = InetAddress.getByAddress(in.createByteArray());
 325                 } catch (UnknownHostException e) {
 326                     // Nothing we can do here. When we call the constructor, we'll throw an
 327                     // IllegalArgumentException, because a LinkAddress can't have a null
 328                     // InetAddress.
 329                 }
 330                 int prefixLength = in.readInt();
 331                 int flags = in.readInt();
 332                 int scope = in.readInt();
 333                 return new LinkAddress(address, prefixLength, flags, scope);
 334             }
 335
 336             public LinkAddress[] newArray(int size) {
 337                 return new LinkAddress[size];
 338             }
 339         };
 340 }