Improve ConnectivityManager docs
Also fix some permission problems.
bug:5738328
Change-Id: Ib32c223f425b1fc03b8cce528456bcb50b540fdf
diff --git a/core/java/android/net/ConnectivityManager.java b/core/java/android/net/ConnectivityManager.java
index 1f44e49..3a04c27 100644
--- a/core/java/android/net/ConnectivityManager.java
+++ b/core/java/android/net/ConnectivityManager.java
@@ -62,7 +62,7 @@
* 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 @@
/**
* 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
- * idle if there is no data transimition for a period of time.
+ * The network becomes active when data transmission is started, or
+ * idle if there is no data transmission for a period of time.
* {@hide}
*/
@SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
@@ -205,8 +205,12 @@
"android.net.conn.INET_CONDITION_ACTION";
/**
- * Broadcast Action: A tetherable connection has come or gone
- * TODO - finish the doc
+ * Broadcast Action: A tetherable connection has come or gone.
+ * 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 @@
/**
* @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 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
- * will use this connection by default.
+ * The Mobile data connection. When active, all data traffic
+ * 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
- * will use this connection by default.
+ * The WIFI data connection. When active, all data traffic
+ * 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
- * same as {@link #TYPE_MOBILE} but it may be different. This is used
- * by applications needing to talk to the carrier's Multimedia Messaging
- * Service servers. It may coexist with default data connections.
+ * An MMS-specific Mobile data connection. This network type may use the
+ * same network interface as {@link #TYPE_MOBILE} or it may use a different
+ * one. This is used by applications needing to talk to the carrier's
+ * Multimedia Messaging Service servers.
*/
public static final int TYPE_MOBILE_MMS = 2;
/**
- * A SUPL-specific Mobile data connection. This connection may be the
- * same as {@link #TYPE_MOBILE} but it may be different. This is used
- * by applications needing to talk to the carrier's Secure User Plane
- * Location servers for help locating the device. It may coexist with
- * default data connections.
+ * A SUPL-specific Mobile data connection. This network type may use the
+ * same network interface as {@link #TYPE_MOBILE} or it may use a different
+ * one. This is used by applications needing to talk to the carrier's
+ * Secure User Plane Location servers for help locating the device.
*/
public static final int TYPE_MOBILE_SUPL = 3;
/**
- * A DUN-specific Mobile data connection. This connection may be the
- * same as {@link #TYPE_MOBILE} but it may be different. This is used
- * by applicaitons performing a Dial Up Networking bridge so that
- * the carrier is aware of DUN traffic. It may coexist with default data
- * connections.
+ * A DUN-specific Mobile data connection. This network type may use the
+ * same network interface as {@link #TYPE_MOBILE} or it may use a different
+ * one. This is sometimes by the system when setting up an upstream connection
+ * for tethering so that the carrier is aware of DUN traffic.
*/
public static final int TYPE_MOBILE_DUN = 4;
/**
- * A High Priority Mobile data connection. This connection is typically
- * the same as {@link #TYPE_MOBILE} but the routing setup is different.
- * Only requesting processes will have access to the Mobile DNS servers
- * and only IP's explicitly requested via {@link #requestRouteToHost}
- * will route over this interface if a default route exists.
+ * A High Priority Mobile data connection. This network type uses the
+ * same network interface as {@link #TYPE_MOBILE} but the routing setup
+ * is different. Only requesting processes will have access to the
+ * Mobile DNS servers and only IP's explicitly requested via {@link #requestRouteToHost}
+ * 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
- * will use this connection by default.
+ * The WiMAX data connection. When active, all data traffic
+ * 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
- * will use this connection by default.
+ * The Bluetooth data connection. When active, all data traffic
+ * 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 static final int TYPE_DUMMY = 8;
/**
- * The Default Ethernet data connection. When active, all data traffic
- * will use this connection by default.
+ * The Ethernet data connection. When active, all data traffic
+ * 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 @@
*
* @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 @@
/**
* 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 @@
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 @@
}
}
- /** {@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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 @@
}
/**
- * Returns details about the currently active data network. When connected,
- * this network is the default route for outgoing connections. You should
- * always check {@link NetworkInfo#isConnected()} before initiating network
- * traffic. This may return {@code null} when no networks are available.
- * <p>This method requires the caller to hold the permission
+ * Returns details about the currently active default data network. When
+ * connected, this network is the default route for outgoing connections.
+ * You should always check {@link NetworkInfo#isConnected()} before initiating
+ * network traffic. This may return {@code null} when there is no default
+ * 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 @@
}
}
- /** {@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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 @@
}
}
- /** {@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 @@
}
}
- /** {@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 @@
}
}
- /** {@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 @@
}
}
- /** {@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 @@
* 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 @@
* 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 @@
/**
* Sets the persisted value for enabling/disabling Mobile data.
*
- * @param enabled Whether the mobile data connection should be
- * used or not.
+ * @param enabled Whether the user wants the mobile data connection used
+ * or not.
* @hide
*/
public void setMobileDataEnabled(boolean enabled) {
@@ -698,6 +842,13 @@
}
/**
+ * 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 @@
}
/**
+ * 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 @@
}
/**
+ * 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 @@
}
/**
- * @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 @@
}
/**
- * @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 @@
}
/**
+ * 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 @@
}
/**
+ * 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 @@
}
/**
+ * 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 @@
}
/**
+ * 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 @@
}
/**
+ * 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 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 @@
}
/**
- * Ensure the device stays awake until we connect with the next network
- * @param forWhome The name of the network going down for logging purposes
+ * Try to ensure the device stays awake until we connect with the next network.
+ * 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 @@
}
/**
+ * 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 @@
}
/**
- * @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 @@
}
/**
- * @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 @@
}
/**
- * @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 @@
}
/**
+ * 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 @@
* 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
- * should still return true for mobile data, but a wifi only tablet
- * would return false.
- * @param networkType The nework type we'd like to check
- * @return true if supported, else false
+ * hardware supports it. For example a GSM phone without a SIM
+ * should still return {@code true} for mobile data, but a wifi only
+ * tablet would return {@code 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 @@
/**
* 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,
- * and warn the user or delay the operation until another network is
- * available.
+ * that connection due to monetary costs, data limitations or
+ * battery/performance issues. You should check this before doing large
+ * 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 @@
}
}
- /** {@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 @@
}
/**
+ * 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) {
diff --git a/services/java/com/android/server/ConnectivityService.java b/services/java/com/android/server/ConnectivityService.java
index 6d817a1..7abd530 100644
--- a/services/java/com/android/server/ConnectivityService.java
+++ b/services/java/com/android/server/ConnectivityService.java
@@ -1823,6 +1823,7 @@
}
public void sendConnectedBroadcast(NetworkInfo info) {
+ enforceConnectivityInternalPermission();
sendGeneralBroadcast(info, CONNECTIVITY_ACTION_IMMEDIATE);
sendGeneralBroadcast(info, CONNECTIVITY_ACTION);
}
@@ -2107,6 +2108,7 @@
/** @hide */
public void captivePortalCheckComplete(NetworkInfo info) {
+ enforceConnectivityInternalPermission();
mNetTrackers[info.getType()].captivePortalCheckComplete();
}
@@ -2365,7 +2367,7 @@
* 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 int setUsbTethering(boolean enable) {
- enforceTetherAccessPermission();
+ enforceTetherChangePermission();
if (isTetheringSupported()) {
return mTethering.setUsbTethering(enable);
} else {
@@ -2997,6 +2999,7 @@
}
public ProxyProperties getProxy() {
+ enforceAccessPermission();
synchronized (mDefaultProxyLock) {
return mDefaultProxyDisabled ? null : mDefaultProxy;
}
@@ -3048,6 +3051,7 @@
}
public ProxyProperties getGlobalProxy() {
+ enforceAccessPermission();
synchronized (mGlobalProxyLock) {
return mGlobalProxy;
}