Improve ConnectivityManager docs

Also fix some permission problems.
bug:5738328

Change-Id: Ib32c223f425b1fc03b8cce528456bcb50b540fdf

core/java/android/net/ConnectivityManager.java

@@ -62,7 +62,7 @@ public class ConnectivityManager {
      * NetworkInfo for the new network is also passed as an extra. This lets
      * any receivers of the broadcast know that they should not necessarily
      * tell the user that no data traffic will be possible. Instead, the
-     * reciever should expect another broadcast soon, indicating either that
+     * receiver should expect another broadcast soon, indicating either that
      * the failover attempt succeeded (and so there is still overall data
      * connectivity), or that the failover attempt failed, meaning that all
      * connectivity has been lost.
@@ -151,8 +151,8 @@ public class ConnectivityManager {
     /**
      * Broadcast action to indicate the change of data activity status
      * (idle or active) on a network in a recent period.
-     * The network becomes active when data transimission is started, or
+     * The network becomes active when data transmission is started, or
-     * idle if there is no data transimition for a period of time.
+     * idle if there is no data transmission for a period of time.
      * {@hide}
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
@@ -205,8 +205,12 @@ public class ConnectivityManager {
             "android.net.conn.INET_CONDITION_ACTION";
 
     /**
-     * Broadcast Action: A tetherable connection has come or gone
+     * Broadcast Action: A tetherable connection has come or gone.
-     * TODO - finish the doc
+     * Uses {@code ConnectivityManager.EXTRA_AVAILABLE_TETHER},
+     * {@code ConnectivityManager.EXTRA_ACTIVE_TETHER} and
+     * {@code ConnectivityManager.EXTRA_ERRORED_TETHER} to indicate
+     * the current state of tethering.  Each include a list of
+     * interface names in that state (may be empty).
      * @hide
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
@@ -215,19 +219,23 @@ public class ConnectivityManager {
 
     /**
      * @hide
-     * gives a String[]
+     * gives a String[] listing all the interfaces configured for
+     * tethering and currently available for tethering.
      */
     public static final String EXTRA_AVAILABLE_TETHER = "availableArray";
 
     /**
      * @hide
-     * gives a String[]
+     * gives a String[] listing all the interfaces currently tethered
+     * (ie, has dhcp support and packets potentially forwarded/NATed)
      */
     public static final String EXTRA_ACTIVE_TETHER = "activeArray";
 
     /**
      * @hide
-     * gives a String[]
+     * gives a String[] listing all the interfaces we tried to tether and
+     * failed.  Use {@link #getLastTetherError} to find the error code
+     * for any interfaces listed here.
      */
     public static final String EXTRA_ERRORED_TETHER = "erroredArray";
 
@@ -248,61 +256,63 @@ public class ConnectivityManager {
     public static final String EXTRA_IS_CAPTIVE_PORTAL = "captivePortal";
 
     /**
-     * The absence of APN..
+     * The absence of a connection type.
      * @hide
      */
     public static final int TYPE_NONE        = -1;
 
     /**
-     * The Default Mobile data connection.  When active, all data traffic
+     * The Mobile data connection.  When active, all data traffic
-     * will use this connection by default.
+     * will use this network type's interface by default
+     * (it has a default route)
      */
     public static final int TYPE_MOBILE      = 0;
     /**
-     * The Default WIFI data connection.  When active, all data traffic
+     * The WIFI data connection.  When active, all data traffic
-     * will use this connection by default.
+     * will use this network type's interface by default
+     * (it has a default route).
      */
     public static final int TYPE_WIFI        = 1;
     /**
-     * An MMS-specific Mobile data connection.  This connection may be the
+     * An MMS-specific Mobile data connection.  This network type may use the
-     * same as {@link #TYPE_MOBILE} but it may be different.  This is used
+     * same network interface as {@link #TYPE_MOBILE} or it may use a different
-     * by applications needing to talk to the carrier's Multimedia Messaging
+     * one.  This is used by applications needing to talk to the carrier's
-     * Service servers.  It may coexist with default data connections.
+     * Multimedia Messaging Service servers.
      */
     public static final int TYPE_MOBILE_MMS  = 2;
     /**
-     * A SUPL-specific Mobile data connection.  This connection may be the
+     * A SUPL-specific Mobile data connection.  This network type may use the
-     * same as {@link #TYPE_MOBILE} but it may be different.  This is used
+     * same network interface as {@link #TYPE_MOBILE} or it may use a different
-     * by applications needing to talk to the carrier's Secure User Plane
+     * one.  This is used by applications needing to talk to the carrier's
-     * Location servers for help locating the device.  It may coexist with
+     * Secure User Plane Location servers for help locating the device.
-     * default data connections.
      */
     public static final int TYPE_MOBILE_SUPL = 3;
     /**
-     * A DUN-specific Mobile data connection.  This connection may be the
+     * A DUN-specific Mobile data connection.  This network type may use the
-     * same as {@link #TYPE_MOBILE} but it may be different.  This is used
+     * same network interface as {@link #TYPE_MOBILE} or it may use a different
-     * by applicaitons performing a Dial Up Networking bridge so that
+     * one.  This is sometimes by the system when setting up an upstream connection
-     * the carrier is aware of DUN traffic.  It may coexist with default data
+     * for tethering so that the carrier is aware of DUN traffic.
-     * connections.
      */
     public static final int TYPE_MOBILE_DUN  = 4;
     /**
-     * A High Priority Mobile data connection.  This connection is typically
+     * A High Priority Mobile data connection.  This network type uses the
-     * the same as {@link #TYPE_MOBILE} but the routing setup is different.
+     * same network interface as {@link #TYPE_MOBILE} but the routing setup
-     * Only requesting processes will have access to the Mobile DNS servers
+     * is different.  Only requesting processes will have access to the
-     * and only IP's explicitly requested via {@link #requestRouteToHost}
+     * Mobile DNS servers and only IP's explicitly requested via {@link #requestRouteToHost}
-     * will route over this interface if a default route exists.
+     * will route over this interface if no default route exists.
      */
     public static final int TYPE_MOBILE_HIPRI = 5;
     /**
-     * The Default WiMAX data connection.  When active, all data traffic
+     * The WiMAX data connection.  When active, all data traffic
-     * will use this connection by default.
+     * will use this network type's interface by default
+     * (it has a default route).
      */
     public static final int TYPE_WIMAX       = 6;
 
     /**
-     * The Default Bluetooth data connection. When active, all data traffic
+     * The Bluetooth data connection.  When active, all data traffic
-     * will use this connection by default.
+     * will use this network type's interface by default
+     * (it has a default route).
      */
     public static final int TYPE_BLUETOOTH   = 7;
 
@@ -312,25 +322,26 @@ public class ConnectivityManager {
     public static final int TYPE_DUMMY       = 8;
 
     /**
-     * The Default Ethernet data connection.  When active, all data traffic
+     * The Ethernet data connection.  When active, all data traffic
-     * will use this connection by default.
+     * will use this network type's interface by default
+     * (it has a default route).
      */
     public static final int TYPE_ETHERNET    = 9;
 
     /**
-     * Over the air Adminstration.
+     * Over the air Administration.
      * {@hide}
      */
     public static final int TYPE_MOBILE_FOTA = 10;
 
     /**
-     * IP Multimedia Subsystem
+     * IP Multimedia Subsystem.
      * {@hide}
      */
     public static final int TYPE_MOBILE_IMS  = 11;
 
     /**
-     * Carrier Branded Services
+     * Carrier Branded Services.
      * {@hide}
      */
     public static final int TYPE_MOBILE_CBS  = 12;
@@ -354,7 +365,7 @@ public class ConnectivityManager {
      *
      * @deprecated Since we support so many more networks now, the single
      *             network default network preference can't really express
-     *             the heirarchy.  Instead, the default is defined by the
+     *             the hierarchy.  Instead, the default is defined by the
      *             networkAttributes in config.xml.  You can determine
      *             the current value by calling {@link #getNetworkPreference()}
      *             from an App.
@@ -364,7 +375,11 @@ public class ConnectivityManager {
 
     /**
      * Default value for {@link Settings.Global#CONNECTIVITY_CHANGE_DELAY} in
-     * milliseconds.
+     * milliseconds.  This was introduced because IPv6 routes seem to take a
+     * moment to settle - trying network activity before the routes are adjusted
+     * can lead to packets using the wrong interface or having the wrong IP address.
+     * This delay is a bit crude, but in the future hopefully we will have kernel
+     * notifications letting us know when it's safe to use the new network.
      *
      * @hide
      */
@@ -372,11 +387,23 @@ public class ConnectivityManager {
 
     private final IConnectivityManager mService;
 
+    /**
+     * Tests if a given integer represents a valid network type.
+     * @param networkType the type to be tested
+     * @return a boolean.  {@code true} if the type is valid, else {@code false}
+     */
     public static boolean isNetworkTypeValid(int networkType) {
         return networkType >= 0 && networkType <= MAX_NETWORK_TYPE;
     }
 
-    /** {@hide} */
+    /**
+     * Returns a non-localized string representing a given network type.
+     * ONLY used for debugging output.
+     * @param type the type needing naming
+     * @return a String for the given type, or a string version of the type ("87")
+     * if no name is known.
+     * {@hide}
+     */
     public static String getNetworkTypeName(int type) {
         switch (type) {
             case TYPE_MOBILE:
@@ -412,7 +439,13 @@ public class ConnectivityManager {
         }
     }
 
-    /** {@hide} */
+    /**
+     * Checks if a given type uses the cellular data connection.
+     * This should be replaced in the future by a network property.
+     * @param networkType the type to check
+     * @return a boolean - {@code true} if uses cellular network, else {@code false}
+     * {@hide}
+     */
     public static boolean isNetworkTypeMobile(int networkType) {
         switch (networkType) {
             case TYPE_MOBILE:
@@ -429,6 +462,17 @@ public class ConnectivityManager {
         }
     }
 
+    /**
+     * Specifies the preferred network type.  When the device has more
+     * than one type available the preferred network type will be used.
+     * Note that this made sense when we only had 2 network types,
+     * but with more and more default networks we need an array to list
+     * their ordering.  This will be deprecated soon.
+     *
+     * @param preference the network type to prefer over all others.  It is
+     *         unspecified what happens to the old preferred network in the
+     *         overall ordering.
+     */
     public void setNetworkPreference(int preference) {
         try {
             mService.setNetworkPreference(preference);
@@ -436,6 +480,17 @@ public class ConnectivityManager {
         }
     }
 
+    /**
+     * Retrieves the current preferred network type.
+     * Note that this made sense when we only had 2 network types,
+     * but with more and more default networks we need an array to list
+     * their ordering.  This will be deprecated soon.
+     *
+     * @return an integer representing the preferred network type
+     *
+     * <p>This method requires the caller to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
+     */
     public int getNetworkPreference() {
         try {
             return mService.getNetworkPreference();
@@ -445,11 +500,16 @@ public class ConnectivityManager {
     }
 
     /**
-     * Returns details about the currently active data network. When connected,
+     * Returns details about the currently active default data network. When
-     * this network is the default route for outgoing connections. You should
+     * connected, this network is the default route for outgoing connections.
-     * always check {@link NetworkInfo#isConnected()} before initiating network
+     * You should always check {@link NetworkInfo#isConnected()} before initiating
-     * traffic. This may return {@code null} when no networks are available.
+     * network traffic. This may return {@code null} when there is no default
-     * <p>This method requires the caller to hold the permission
+     * network.
+     *
+     * @return a {@link NetworkInfo} object for the current default network
+     *        or {@code null} if no network default network is currently active
+     *
+     * <p>This method requires the call to hold the permission
      * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      */
     public NetworkInfo getActiveNetworkInfo() {
@@ -460,7 +520,19 @@ public class ConnectivityManager {
         }
     }
 
-    /** {@hide} */
+    /**
+     * Returns details about the currently active default data network
+     * for a given uid.  This is for internal use only to avoid spying
+     * other apps.
+     *
+     * @return a {@link NetworkInfo} object for the current default network
+     *        for the given uid or {@code null} if no default network is
+     *        available for the specified uid.
+     *
+     * <p>This method requires the caller to hold the permission
+     * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}
+     * {@hide}
+     */
     public NetworkInfo getActiveNetworkInfoForUid(int uid) {
         try {
             return mService.getActiveNetworkInfoForUid(uid);
@@ -469,6 +541,19 @@ public class ConnectivityManager {
         }
     }
 
+    /**
+     * Returns connection status information about a particular
+     * network type.
+     *
+     * @param networkType integer specifying which networkType in
+     *        which you're interested.
+     * @return a {@link NetworkInfo} object for the requested
+     *        network type or {@code null} if the type is not
+     *        supported by the device.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
+     */
     public NetworkInfo getNetworkInfo(int networkType) {
         try {
             return mService.getNetworkInfo(networkType);
@@ -477,6 +562,16 @@ public class ConnectivityManager {
         }
     }
 
+    /**
+     * Returns connection status information about all network
+     * types supported by the device.
+     *
+     * @return an array of {@link NetworkInfo} objects.  Check each
+     * {@link NetworkInfo#getType} for which type each applies.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
+     */
     public NetworkInfo[] getAllNetworkInfo() {
         try {
             return mService.getAllNetworkInfo();
@@ -485,7 +580,17 @@ public class ConnectivityManager {
         }
     }
 
-    /** {@hide} */
+    /**
+     * Returns the IP information for the current default network.
+     *
+     * @return a {@link LinkProperties} object describing the IP info
+     *        for the current default network, or {@code null} if there
+     *        is no current default network.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
+     * {@hide}
+     */
     public LinkProperties getActiveLinkProperties() {
         try {
             return mService.getActiveLinkProperties();
@@ -494,7 +599,18 @@ public class ConnectivityManager {
         }
     }
 
-    /** {@hide} */
+    /**
+     * Returns the IP information for a given network type.
+     *
+     * @param networkType the network type of interest.
+     * @return a {@link LinkProperties} object describing the IP info
+     *        for the given networkType, or {@code null} if there is
+     *        no current default network.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
+     * {@hide}
+     */
     public LinkProperties getLinkProperties(int networkType) {
         try {
             return mService.getLinkProperties(networkType);
@@ -503,7 +619,18 @@ public class ConnectivityManager {
         }
     }
 
-    /** {@hide} */
+    /**
+     * Tells each network type to set its radio power state as directed.
+     *
+     * @param turnOn a boolean, {@code true} to turn the radios on,
+     *        {@code false} to turn them off.
+     * @return a boolean, {@code true} indicating success.  All network types
+     *        will be tried, even if some fail.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}.
+     * {@hide}
+     */
     public boolean setRadios(boolean turnOn) {
         try {
             return mService.setRadios(turnOn);
@@ -512,7 +639,18 @@ public class ConnectivityManager {
         }
     }
 
-    /** {@hide} */
+    /**
+     * Tells a given networkType to set its radio power state as directed.
+     *
+     * @param networkType the int networkType of interest.
+     * @param turnOn a boolean, {@code true} to turn the radio on,
+     *        {@code} false to turn it off.
+     * @return a boolean, {@code true} indicating success.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}.
+     * {@hide}
+     */
     public boolean setRadio(int networkType, boolean turnOn) {
         try {
             return mService.setRadio(networkType, turnOn);
@@ -647,6 +785,9 @@ public class ConnectivityManager {
      * network is active. Quota status can change rapidly, so these values
      * shouldn't be cached.
      *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
+     *
      * @hide
      */
     public NetworkQuotaInfo getActiveNetworkQuotaInfo() {
@@ -661,6 +802,9 @@ public class ConnectivityManager {
      * Gets the value of the setting for enabling Mobile data.
      *
      * @return Whether mobile data is enabled.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * @hide
      */
     public boolean getMobileDataEnabled() {
@@ -674,8 +818,8 @@ public class ConnectivityManager {
     /**
      * Sets the persisted value for enabling/disabling Mobile data.
      *
-     * @param enabled Whether the mobile data connection should be
+     * @param enabled Whether the user wants the mobile data connection used
-     *            used or not.
+     *            or not.
      * @hide
      */
     public void setMobileDataEnabled(boolean enabled) {
@@ -698,6 +842,13 @@ public class ConnectivityManager {
     }
 
     /**
+     * Get the set of tetherable, available interfaces.  This list is limited by
+     * device configuration and current interface existence.
+     *
+     * @return an array of 0 or more Strings of tetherable interface names.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public String[] getTetherableIfaces() {
@@ -709,6 +860,12 @@ public class ConnectivityManager {
     }
 
     /**
+     * Get the set of tethered interfaces.
+     *
+     * @return an array of 0 or more String of currently tethered interface names.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public String[] getTetheredIfaces() {
@@ -720,6 +877,18 @@ public class ConnectivityManager {
     }
 
     /**
+     * Get the set of interface names which attempted to tether but
+     * failed.  Re-attempting to tether may cause them to reset to the Tethered
+     * state.  Alternatively, causing the interface to be destroyed and recreated
+     * may cause them to reset to the available state.
+     * {@link ConnectivityManager#getLastTetherError} can be used to get more
+     * information on the cause of the errors.
+     *
+     * @return an array of 0 or more String indicating the interface names
+     *        which failed to tether.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public String[] getTetheringErroredIfaces() {
@@ -731,7 +900,19 @@ public class ConnectivityManager {
     }
 
     /**
-     * @return error A TETHER_ERROR value indicating success or failure type
+     * Attempt to tether the named interface.  This will setup a dhcp server
+     * on the interface, forward and NAT IP packets and forward DNS requests
+     * to the best active upstream network interface.  Note that if no upstream
+     * IP network interface is available, dhcp will still run and traffic will be
+     * allowed between the tethered devices and this device, though upstream net
+     * access will of course fail until an upstream network interface becomes
+     * active.
+     *
+     * @param iface the interface name to tether.
+     * @return error a {@code TETHER_ERROR} value indicating success or failure type
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}.
      * {@hide}
      */
     public int tether(String iface) {
@@ -743,7 +924,13 @@ public class ConnectivityManager {
     }
 
     /**
-     * @return error A TETHER_ERROR value indicating success or failure type
+     * Stop tethering the named interface.
+     *
+     * @param iface the interface name to untether.
+     * @return error a {@code TETHER_ERROR} value indicating success or failure type
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}.
      * {@hide}
      */
     public int untether(String iface) {
@@ -755,6 +942,14 @@ public class ConnectivityManager {
     }
 
     /**
+     * Check if the device allows for tethering.  It may be disabled via
+     * {@code ro.tether.denied} system property, {@link Settings#TETHER_SUPPORTED} or
+     * due to device configuration.
+     *
+     * @return a boolean - {@code true} indicating Tethering is supported.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public boolean isTetheringSupported() {
@@ -766,6 +961,15 @@ public class ConnectivityManager {
     }
 
     /**
+     * Get the list of regular expressions that define any tetherable
+     * USB network interfaces.  If USB tethering is not supported by the
+     * device, this list should be empty.
+     *
+     * @return an array of 0 or more regular expression Strings defining
+     *        what interfaces are considered tetherable usb interfaces.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public String[] getTetherableUsbRegexs() {
@@ -777,6 +981,15 @@ public class ConnectivityManager {
     }
 
     /**
+     * Get the list of regular expressions that define any tetherable
+     * Wifi network interfaces.  If Wifi tethering is not supported by the
+     * device, this list should be empty.
+     *
+     * @return an array of 0 or more regular expression Strings defining
+     *        what interfaces are considered tetherable wifi interfaces.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public String[] getTetherableWifiRegexs() {
@@ -788,6 +1001,15 @@ public class ConnectivityManager {
     }
 
     /**
+     * Get the list of regular expressions that define any tetherable
+     * Bluetooth network interfaces.  If Bluetooth tethering is not supported by the
+     * device, this list should be empty.
+     *
+     * @return an array of 0 or more regular expression Strings defining
+     *        what interfaces are considered tetherable bluetooth interfaces.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public String[] getTetherableBluetoothRegexs() {
@@ -799,6 +1021,17 @@ public class ConnectivityManager {
     }
 
     /**
+     * Attempt to both alter the mode of USB and Tethering of USB.  A
+     * utility method to deal with some of the complexity of USB - will
+     * attempt to switch to Rndis and subsequently tether the resulting
+     * interface on {@code true} or turn off tethering and switch off
+     * Rndis on {@code false}.
+     *
+     * @param enable a boolean - {@code true} to enable tethering
+     * @return error a {@code TETHER_ERROR} value indicating success or failure type
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}.
      * {@hide}
      */
     public int setUsbTethering(boolean enable) {
@@ -833,9 +1066,15 @@ public class ConnectivityManager {
     public static final int TETHER_ERROR_IFACE_CFG_ERROR      = 10;
 
     /**
-     * @param iface The name of the interface we're interested in
+     * Get a more detailed error code after a Tethering or Untethering
+     * request asynchronously failed.
+     *
+     * @param iface The name of the interface of interest
      * @return error The error code of the last error tethering or untethering the named
      *               interface
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public int getLastTetherError(String iface) {
@@ -847,9 +1086,16 @@ public class ConnectivityManager {
     }
 
     /**
-     * Ensure the device stays awake until we connect with the next network
+     * Try to ensure the device stays awake until we connect with the next network.
-     * @param forWhome The name of the network going down for logging purposes
+     * Actually just holds a wakelock for a number of seconds while we try to connect
+     * to any default networks.  This will expire if the timeout passes or if we connect
+     * to a default after this is called.  For internal use only.
+     *
+     * @param forWhom the name of the network going down for logging purposes
      * @return {@code true} on success, {@code false} on failure
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}.
      * {@hide}
      */
     public boolean requestNetworkTransitionWakelock(String forWhom) {
@@ -862,8 +1108,14 @@ public class ConnectivityManager {
     }
 
     /**
+     * Report network connectivity status.  This is currently used only
+     * to alter status bar UI.
+     *
      * @param networkType The type of network you want to report on
      * @param percentage The quality of the connection 0 is bad, 100 is good
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#STATUS_BAR}.
      * {@hide}
      */
     public void reportInetCondition(int networkType, int percentage) {
@@ -874,7 +1126,16 @@ public class ConnectivityManager {
     }
 
     /**
-     * @param proxyProperties The definition for the new global http proxy
+     * Set a network-independent global http proxy.  This is not normally what you want
+     * for typical HTTP proxies - they are general network dependent.  However if you're
+     * doing something unusual like general internal filtering this may be useful.  On
+     * a private network where the proxy is not accessible, you may break HTTP using this.
+     *
+     * @param proxyProperties The a {@link ProxyProperites} object defining the new global
+     *        HTTP proxy.  A {@code null} value will clear the global HTTP proxy.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}.
      * {@hide}
      */
     public void setGlobalProxy(ProxyProperties p) {
@@ -885,7 +1146,13 @@ public class ConnectivityManager {
     }
 
     /**
-     * @return proxyProperties for the current global proxy
+     * Retrieve any network-independent global HTTP proxy.
+     *
+     * @return {@link ProxyProperties} for the current global HTTP proxy or {@code null}
+     *        if no global HTTP proxy is set.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public ProxyProperties getGlobalProxy() {
@@ -897,7 +1164,14 @@ public class ConnectivityManager {
     }
 
     /**
-     * @return proxyProperties for the current proxy (global if set, network specific if not)
+     * Get the HTTP proxy settings for the current default network.  Note that
+     * if a global proxy is set, it will override any per-network setting.
+     *
+     * @return the {@link ProxyProperties} for the current HTTP proxy, or {@code null} if no
+     *        HTTP proxy is active.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * {@hide}
      */
     public ProxyProperties getProxy() {
@@ -909,8 +1183,15 @@ public class ConnectivityManager {
     }
 
     /**
+     * Sets a secondary requirement bit for the given networkType.
+     * This requirement bit is generally under the control of the carrier
+     * or its agents and is not directly controlled by the user.
+     *
      * @param networkType The network who's dependence has changed
-     * @param met Boolean - true if network use is ok, false if not
+     * @param met Boolean - true if network use is OK, false if not
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}.
      * {@hide}
      */
     public void setDataDependency(int networkType, boolean met) {
@@ -924,11 +1205,15 @@ public class ConnectivityManager {
      * Returns true if the hardware supports the given network type
      * else it returns false.  This doesn't indicate we have coverage
      * or are authorized onto a network, just whether or not the
-     * hardware supports it.  For example a gsm phone without a sim
+     * hardware supports it.  For example a GSM phone without a SIM
-     * should still return true for mobile data, but a wifi only tablet
+     * should still return {@code true} for mobile data, but a wifi only
-     * would return false.
+     * tablet would return {@code false}.
-     * @param networkType The nework type we'd like to check
+     *
-     * @return true if supported, else false
+     * @param networkType The network type we'd like to check
+     * @return {@code true} if supported, else {@code false}
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      * @hide
      */
     public boolean isNetworkSupported(int networkType) {
@@ -941,9 +1226,16 @@ public class ConnectivityManager {
     /**
      * Returns if the currently active data network is metered. A network is
      * classified as metered when the user is sensitive to heavy data usage on
-     * that connection. You should check this before doing large data transfers,
+     * that connection due to monetary costs, data limitations or
-     * and warn the user or delay the operation until another network is
+     * battery/performance issues. You should check this before doing large
-     * available.
+     * data transfers, and warn the user or delay the operation until another
+     * network is available.
+     *
+     * @return {@code true} if large transfers should be avoided, otherwise
+     *        {@code false}.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
      */
     public boolean isActiveNetworkMetered() {
         try {
@@ -953,7 +1245,15 @@ public class ConnectivityManager {
         }
     }
 
-    /** {@hide} */
+    /**
+     * If the LockdownVpn mechanism is enabled, updates the vpn
+     * with a reload of its profile.
+     *
+     * @return a boolean with {@code} indicating success
+     *
+     * <p>This method can only be called by the system UID
+     * {@hide}
+     */
     public boolean updateLockdownVpn() {
         try {
             return mService.updateLockdownVpn();
@@ -963,6 +1263,14 @@ public class ConnectivityManager {
     }
 
     /**
+     * Signal that the captive portal check on the indicated network
+     * is complete and we can turn the network on for general use.
+     *
+     * @param info the {@link NetworkInfo} object for the networkType
+     *        in question.
+     *
+     * <p>This method requires the call to hold the permission
+     * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}.
      * {@hide}
      */
     public void captivePortalCheckComplete(NetworkInfo info) {

services/java/com/android/server/ConnectivityService.java

@@ -1823,6 +1823,7 @@ public class ConnectivityService extends IConnectivityManager.Stub {
     }
 
     public void sendConnectedBroadcast(NetworkInfo info) {
+        enforceConnectivityInternalPermission();
         sendGeneralBroadcast(info, CONNECTIVITY_ACTION_IMMEDIATE);
         sendGeneralBroadcast(info, CONNECTIVITY_ACTION);
     }
@@ -2107,6 +2108,7 @@ public class ConnectivityService extends IConnectivityManager.Stub {
 
     /** @hide */
     public void captivePortalCheckComplete(NetworkInfo info) {
+        enforceConnectivityInternalPermission();
         mNetTrackers[info.getType()].captivePortalCheckComplete();
     }
 
@@ -2365,7 +2367,7 @@ public class ConnectivityService extends IConnectivityManager.Stub {
      * net.tcp.buffersize.[default|wifi|umts|edge|gprs] and set them for system
      * wide use
      */
-   public void updateNetworkSettings(NetworkStateTracker nt) {
+   private void updateNetworkSettings(NetworkStateTracker nt) {
         String key = nt.getTcpBufferSizesPropName();
         String bufferSizes = key == null ? null : SystemProperties.get(key);
 
@@ -2844,7 +2846,7 @@ public class ConnectivityService extends IConnectivityManager.Stub {
     }
 
     public int setUsbTethering(boolean enable) {
-        enforceTetherAccessPermission();
+        enforceTetherChangePermission();
         if (isTetheringSupported()) {
             return mTethering.setUsbTethering(enable);
         } else {
@@ -2997,6 +2999,7 @@ public class ConnectivityService extends IConnectivityManager.Stub {
     }
 
     public ProxyProperties getProxy() {
+        enforceAccessPermission();
         synchronized (mDefaultProxyLock) {
             return mDefaultProxyDisabled ? null : mDefaultProxy;
         }
@@ -3048,6 +3051,7 @@ public class ConnectivityService extends IConnectivityManager.Stub {
     }
 
     public ProxyProperties getGlobalProxy() {
+        enforceAccessPermission();
         synchronized (mGlobalProxyLock) {
             return mGlobalProxy;
         }