From 4f05d5529625fd2f0ad13ff9974c338d2f847934 Mon Sep 17 00:00:00 2001 From: Robert Greenwalt Date: Sun, 18 May 2014 22:01:38 -0700 Subject: [PATCH] Add docs for Linkproperties and unhide it. Preperation for ConnectivityManager API reveal. Change-Id: Id2addf424213e796c6077def0b7f30cac9a0f75f --- api/current.txt | 32 +++++ core/java/android/net/LinkProperties.java | 167 +++++++++++++++++----- 2 files changed, 162 insertions(+), 37 deletions(-) diff --git a/api/current.txt b/api/current.txt index 20e82d136f15..fd28b528baf6 100644 --- a/api/current.txt +++ b/api/current.txt @@ -15885,6 +15885,38 @@ package android.net { method public void writeToParcel(android.os.Parcel, int); } + public class LinkProperties implements android.os.Parcelable { + ctor public LinkProperties(); + ctor public LinkProperties(android.net.LinkProperties); + method public void addDns(java.net.InetAddress); + method public boolean addLinkAddress(android.net.LinkAddress); + method public void addRoute(android.net.RouteInfo); + method public void clear(); + method public int describeContents(); + method public java.util.Collection getAllInterfaceNames(); + method public java.util.Collection getDnses(); + method public java.lang.String getDomains(); + method public android.net.ProxyInfo getHttpProxy(); + method public java.lang.String getInterfaceName(); + method public java.util.Collection getLinkAddresses(); + method public java.util.Collection getRoutes(); + method public boolean hasIPv4Address(); + method public boolean hasIPv6Address(); + method public boolean removeLinkAddress(android.net.LinkAddress); + method public void setDomains(java.lang.String); + method public void setHttpProxy(android.net.ProxyInfo); + method public void setInterfaceName(java.lang.String); + method public void setLinkAddresses(java.util.Collection); + method public void writeToParcel(android.os.Parcel, int); + field public static final android.os.Parcelable.Creator CREATOR; + } + + public static class LinkProperties.CompareResult { + ctor public LinkProperties.CompareResult(); + field public java.util.Collection added; + field public java.util.Collection removed; + } + public class LocalServerSocket { ctor public LocalServerSocket(java.lang.String) throws java.io.IOException; ctor public LocalServerSocket(java.io.FileDescriptor) throws java.io.IOException; diff --git a/core/java/android/net/LinkProperties.java b/core/java/android/net/LinkProperties.java index 489b8a51f1e8..3c366799f655 100644 --- a/core/java/android/net/LinkProperties.java +++ b/core/java/android/net/LinkProperties.java @@ -36,27 +36,12 @@ * * A link represents a connection to a network. * It may have multiple addresses and multiple gateways, - * multiple dns servers but only one http proxy. + * multiple dns servers but only one http proxy and one + * network interface. * - * Because it's a single network, the dns's - * are interchangeable and don't need associating with - * particular addresses. The gateways similarly don't - * need associating with particular addresses. + * Note that this is just a holder of data. Modifying it + * does not affect live networks. * - * A dual stack interface works fine in this model: - * each address has it's own prefix length to describe - * the local network. The dns servers all return - * both v4 addresses and v6 addresses regardless of the - * address family of the server itself (rfc4213) and we - * don't care which is used. The gateways will be - * selected based on the destination address and the - * source address has no relavence. - * - * Links can also be stacked on top of each other. - * This can be used, for example, to represent a tunnel - * interface that runs on top of a physical interface. - * - * @hide */ public class LinkProperties implements Parcelable { // The interface described by the network link. @@ -73,6 +58,7 @@ public class LinkProperties implements Parcelable { private Hashtable mStackedLinks = new Hashtable(); + // @hide public static class CompareResult { public Collection removed = new ArrayList(); public Collection added = new ArrayList(); @@ -91,7 +77,6 @@ public String toString() { public LinkProperties() { } - // copy constructor instead of clone public LinkProperties(LinkProperties source) { if (source != null) { mIfaceName = source.getInterfaceName(); @@ -108,6 +93,12 @@ public LinkProperties(LinkProperties source) { } } + /** + * Sets the interface name for this link. All {@link RouteInfo} already set for this + * will have their interface changed to match this new value. + * + * @param iface The name of the network interface used for this link. + */ public void setInterfaceName(String iface) { mIfaceName = iface; ArrayList newRoutes = new ArrayList(mRoutes.size()); @@ -117,10 +108,16 @@ public void setInterfaceName(String iface) { mRoutes = newRoutes; } + /** + * Gets the interface name for this link. May be {@code null} if not set. + * + * @return The interface name set for this link or {@code null}. + */ public String getInterfaceName() { return mIfaceName; } + // @hide public Collection getAllInterfaceNames() { Collection interfaceNames = new ArrayList(mStackedLinks.size() + 1); if (mIfaceName != null) interfaceNames.add(new String(mIfaceName)); @@ -131,7 +128,14 @@ public Collection getAllInterfaceNames() { } /** - * Returns all the addresses on this link. + * Returns all the addresses on this link. We often think of a link having a single address, + * however, particularly with Ipv6 several addresses are typical. Note that the + * {@code LinkProperties} actually contains {@link LinkAddress} objects which also include + * prefix lengths for each address. This is a simplified utility alternative to + * {@link LinkProperties#getLinkAddresses}. + * + * @return An umodifiable {@link Collection} of {@link InetAddress} for this link. + * @hide */ public Collection getAddresses() { Collection addresses = new ArrayList(); @@ -143,6 +147,7 @@ public Collection getAddresses() { /** * Returns all the addresses on this link and all the links stacked above it. + * @hide */ public Collection getAllAddresses() { Collection addresses = new ArrayList(); @@ -165,7 +170,8 @@ private int findLinkAddressIndex(LinkAddress address) { } /** - * Adds a link address if it does not exist, or updates it if it does. + * Adds a {@link LinkAddress} to this {@code LinkProperties} if a {@link LinkAddress} of the + * same address/prefix does not already exist. If it does exist it is replaced. * @param address The {@code LinkAddress} to add. * @return true if {@code address} was added or updated, false otherwise. */ @@ -189,9 +195,10 @@ public boolean addLinkAddress(LinkAddress address) { } /** - * Removes a link address. Specifically, removes the link address, if any, for which - * {@code isSameAddressAs(toRemove)} returns true. - * @param address A {@code LinkAddress} specifying the address to remove. + * Removes a {@link LinkAddress} from this {@code LinkProperties}. Specifically, matches + * and {@link LinkAddress} with the same address and prefix. + * + * @param toRemove A {@link LinkAddress} specifying the address to remove. * @return true if the address was removed, false if it did not exist. */ public boolean removeLinkAddress(LinkAddress toRemove) { @@ -204,7 +211,10 @@ public boolean removeLinkAddress(LinkAddress toRemove) { } /** - * Returns all the addresses on this link. + * Returns all the {@link LinkAddress} on this link. Typically a link will have + * one IPv4 address and one or more IPv6 addresses. + * + * @return An unmodifiable {@link Collection} of {@link LinkAddress} for this link. */ public Collection getLinkAddresses() { return Collections.unmodifiableCollection(mLinkAddresses); @@ -212,6 +222,7 @@ public Collection getLinkAddresses() { /** * Returns all the addresses on this link and all the links stacked above it. + * @hide */ public Collection getAllLinkAddresses() { Collection addresses = new ArrayList(); @@ -223,7 +234,11 @@ public Collection getAllLinkAddresses() { } /** - * Replaces the LinkAddresses on this link with the given collection of addresses. + * Replaces the {@link LinkAddress} in this {@code LinkProperties} with + * the given {@link Collection} of {@link LinkAddress}. + * + * @param addresses The {@link Collection} of {@link LinkAddress} to set in this + * object. */ public void setLinkAddresses(Collection addresses) { mLinkAddresses.clear(); @@ -232,26 +247,64 @@ public void setLinkAddresses(Collection addresses) { } } + /** + * Adds the given {@link InetAddress} to the list of DNS servers. + * + * @param dns The {@link InetAddress} to add to the list of DNS servers. + */ public void addDns(InetAddress dns) { if (dns != null) mDnses.add(dns); } + /** + * Returns all the {@link LinkAddress} for DNS servers on this link. + * + * @return An umodifiable {@link Collection} of {@link InetAddress} for DNS servers on + * this link. + */ public Collection getDnses() { return Collections.unmodifiableCollection(mDnses); } - public String getDomains() { - return mDomains; - } - + /** + * Sets the DNS domain search path used on this link. + * + * @param domains A {@link String} listing in priority order the comma separated + * domains to search when resolving host names on this link. + */ public void setDomains(String domains) { mDomains = domains; } + /** + * Get the DNS domains search path set for this link. + * + * @return A {@link String} containing the comma separated domains to search when resolving + * host names on this link. + */ + public String getDomains() { + return mDomains; + } + + /** + * Sets the Maximum Transmission Unit size to use on this link. This should not be used + * unless the system default (1500) is incorrect. Values less than 68 or greater than + * 10000 will be ignored. + * + * @param mtu The MTU to use for this link. + * @hide + */ public void setMtu(int mtu) { mMtu = mtu; } + /** + * Gets any non-default MTU size set for this link. Note that if the default is being used + * this will return 0. + * + * @return The mtu value set for this link. + * @hide + */ public int getMtu() { return mMtu; } @@ -263,6 +316,14 @@ private RouteInfo routeWithInterface(RouteInfo route) { mIfaceName); } + /** + * Adds a {@link RouteInfo} to this {@code LinkProperties}. If the {@link RouteInfo} + * had an interface name set and that differs from the interface set for this + * {@code LinkProperties} an {@link IllegalArgumentException} will be thrown. The + * proper course is to add either un-named or properly named {@link RouteInfo}. + * + * @param route A {@link RouteInfo} to add to this object. + */ public void addRoute(RouteInfo route) { if (route != null) { String routeIface = route.getInterface(); @@ -276,7 +337,9 @@ public void addRoute(RouteInfo route) { } /** - * Returns all the routes on this link. + * Returns all the {@link RouteInfo} set on this link. + * + * @return An unmodifiable {@link Collection} of {@link RouteInfo} for this link. */ public Collection getRoutes() { return Collections.unmodifiableCollection(mRoutes); @@ -284,6 +347,7 @@ public Collection getRoutes() { /** * Returns all the routes on this link and all the links stacked above it. + * @hide */ public Collection getAllRoutes() { Collection routes = new ArrayList(); @@ -294,9 +358,22 @@ public Collection getAllRoutes() { return routes; } + /** + * Sets the recommended {@link ProxyInfo} to use on this link, or {@code null} for none. + * Note that Http Proxies are only a hint - the system recommends their use, but it does + * not enforce it and applications may ignore them. + * + * @param proxy A {@link ProxyInfo} defining the Http Proxy to use on this link. + */ public void setHttpProxy(ProxyInfo proxy) { mHttpProxy = proxy; } + + /** + * Gets the recommended {@link ProxyInfo} (or {@code null}) set on this link. + * + * @return The {@link ProxyInfo} set on this link + */ public ProxyInfo getHttpProxy() { return mHttpProxy; } @@ -310,6 +387,7 @@ public ProxyInfo getHttpProxy() { * * @param link The link to add. * @return true if the link was stacked, false otherwise. + * @hide */ public boolean addStackedLink(LinkProperties link) { if (link != null && link.getInterfaceName() != null) { @@ -327,6 +405,7 @@ public boolean addStackedLink(LinkProperties link) { * * @param link The link to remove. * @return true if the link was removed, false otherwise. + * @hide */ public boolean removeStackedLink(LinkProperties link) { if (link != null && link.getInterfaceName() != null) { @@ -338,6 +417,7 @@ public boolean removeStackedLink(LinkProperties link) { /** * Returns all the links stacked on top of this link. + * @hide */ public Collection getStackedLinks() { Collection stacked = new ArrayList(); @@ -347,6 +427,9 @@ public Collection getStackedLinks() { return Collections.unmodifiableCollection(stacked); } + /** + * Clears this object to its initial state. + */ public void clear() { mIfaceName = null; mLinkAddresses.clear(); @@ -432,6 +515,7 @@ public boolean hasIPv6Address() { * * @param target LinkProperties to compare. * @return {@code true} if both are identical, {@code false} otherwise. + * @hide */ public boolean isIdenticalInterfaceName(LinkProperties target) { return TextUtils.equals(getInterfaceName(), target.getInterfaceName()); @@ -442,6 +526,7 @@ public boolean isIdenticalInterfaceName(LinkProperties target) { * * @param target LinkProperties to compare. * @return {@code true} if both are identical, {@code false} otherwise. + * @hide */ public boolean isIdenticalAddresses(LinkProperties target) { Collection targetAddresses = target.getAddresses(); @@ -455,6 +540,7 @@ public boolean isIdenticalAddresses(LinkProperties target) { * * @param target LinkProperties to compare. * @return {@code true} if both are identical, {@code false} otherwise. + * @hide */ public boolean isIdenticalDnses(LinkProperties target) { Collection targetDnses = target.getDnses(); @@ -473,6 +559,7 @@ public boolean isIdenticalDnses(LinkProperties target) { * * @param target LinkProperties to compare. * @return {@code true} if both are identical, {@code false} otherwise. + * @hide */ public boolean isIdenticalRoutes(LinkProperties target) { Collection targetRoutes = target.getRoutes(); @@ -485,6 +572,7 @@ public boolean isIdenticalRoutes(LinkProperties target) { * * @param target LinkProperties to compare. * @return {@code true} if both are identical, {@code false} otherwise. + * @hide */ public boolean isIdenticalHttpProxy(LinkProperties target) { return getHttpProxy() == null ? target.getHttpProxy() == null : @@ -496,6 +584,7 @@ public boolean isIdenticalHttpProxy(LinkProperties target) { * * @param target LinkProperties to compare. * @return {@code true} if both are identical, {@code false} otherwise. + * @hide */ public boolean isIdenticalStackedLinks(LinkProperties target) { if (!mStackedLinks.keySet().equals(target.mStackedLinks.keySet())) { @@ -516,6 +605,7 @@ public boolean isIdenticalStackedLinks(LinkProperties target) { * * @param target LinkProperties to compare. * @return {@code true} if both are identical, {@code false} otherwise. + * @hide */ public boolean isIdenticalMtu(LinkProperties target) { return getMtu() == target.getMtu(); @@ -533,10 +623,6 @@ public boolean isIdenticalMtu(LinkProperties target) { * 1. Duplicated elements. eg, (A, B, B) and (A, A, B) are equal. * 2. Worst case performance is O(n^2). * - * This method does not check that stacked interfaces are equal, because - * stacked interfaces are not so much a property of the link as a - * description of connections between links. - * * @param obj the object to be tested for equality. * @return {@code true} if both objects are equal, {@code false} otherwise. */ @@ -546,7 +632,11 @@ public boolean equals(Object obj) { if (!(obj instanceof LinkProperties)) return false; LinkProperties target = (LinkProperties) obj; - + /** + * This method does not check that stacked interfaces are equal, because + * stacked interfaces are not so much a property of the link as a + * description of connections between links. + */ return isIdenticalInterfaceName(target) && isIdenticalAddresses(target) && isIdenticalDnses(target) && @@ -562,6 +652,7 @@ public boolean equals(Object obj) { * * @param target a LinkProperties with the new list of addresses * @return the differences between the addresses. + * @hide */ public CompareResult compareAddresses(LinkProperties target) { /* @@ -590,6 +681,7 @@ public CompareResult compareAddresses(LinkProperties target) { * * @param target a LinkProperties with the new list of dns addresses * @return the differences between the DNS addresses. + * @hide */ public CompareResult compareDnses(LinkProperties target) { /* @@ -619,6 +711,7 @@ public CompareResult compareDnses(LinkProperties target) { * * @param target a LinkProperties with the new list of routes * @return the differences between the routes. + * @hide */ public CompareResult compareAllRoutes(LinkProperties target) { /*