Address ConnectivityManager API comments.
This patch is a cherry pick of the two following commits:
- 139a48c83cc98cdae2672be062d10b7aec5aea88 which addresses several
issues in the public api of ConnectivityManager.
- 4c11db0fdde58e8fe8b679b3c572dd2cc6a56d89 which fixes the documentation
of several methods in ConnectivityManager public api.
Because the first commit change the public api that is referenced in
the documentation fixed by the second commit, it is not possible to one
without the other. In both cases trying to cherry pick only one of them
results in a build error.
The first commit was submitted successfully on an internal branch before
the checks done in the built got stricter.
Bug: 36370941
Test: marlin builds and boots
Change-Id: I86dcf056e6b165e527c3ee88dbabc2764ac09a08
Merged-In: I693ee5270bf186c88c7c5056293519f7237504ff
(cherry picked from commit 139a48c83cc98cdae2672be062d10b7aec5aea88)
diff --git a/core/java/android/net/ConnectivityManager.java b/core/java/android/net/ConnectivityManager.java
index 234bef7..1876471 100644
--- a/core/java/android/net/ConnectivityManager.java
+++ b/core/java/android/net/ConnectivityManager.java
@@ -2647,7 +2647,7 @@
/**
* Called if no network is found in the timeout time specified in
- * {@link #requestNetwork(NetworkRequest, int, NetworkCallback)} call. This callback is not
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback, int)} call. This callback is not
* called for the version of {@link #requestNetwork(NetworkRequest, NetworkCallback)}
* without timeout. When this callback is invoked the associated
* {@link NetworkRequest} will have already been removed and released, as if
@@ -2944,7 +2944,7 @@
* This {@link NetworkRequest} will live until released via
* {@link #unregisterNetworkCallback(NetworkCallback)} or the calling application exits. A
* version of the method which takes a timeout is
- * {@link #requestNetwork(NetworkRequest, int, NetworkCallback)}.
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback, int)}.
* Status of the request can be followed by listening to the various
* callbacks described in {@link NetworkCallback}. The {@link Network}
* can be used to direct traffic to the network.
@@ -2979,7 +2979,7 @@
* This {@link NetworkRequest} will live until released via
* {@link #unregisterNetworkCallback(NetworkCallback)} or the calling application exits. A
* version of the method which takes a timeout is
- * {@link #requestNetwork(NetworkRequest, int, NetworkCallback)}.
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback, int)}.
* Status of the request can be followed by listening to the various
* callbacks described in {@link NetworkCallback}. The {@link Network}
* can be used to direct traffic to the network.
@@ -3012,50 +3012,6 @@
}
/**
- * Note: this is a deprecated version of
- * {@link #requestNetwork(NetworkRequest, int, NetworkCallback)} - please transition code to use
- * the unhidden version of the function.
- * TODO: replace all callers with the new version of the API
- *
- * Request a network to satisfy a set of {@link android.net.NetworkCapabilities}, limited
- * by a timeout.
- *
- * This function behaves identically to the non-timed-out version
- * {@link #requestNetwork(NetworkRequest, NetworkCallback)}, but if a suitable network
- * is not found within the given time (in milliseconds) the
- * {@link NetworkCallback#onUnavailable()} callback is called. The request can still be
- * released normally by calling {@link #unregisterNetworkCallback(NetworkCallback)} but does
- * not have to be released if timed-out (it is automatically released). Unregistering a
- * request that timed out is not an error.
- *
- * <p>Do not use this method to poll for the existence of specific networks (e.g. with a small
- * timeout) - the {@link #registerNetworkCallback(NetworkRequest, NetworkCallback)} is provided
- * for that purpose. Calling this method will attempt to bring up the requested network.
- *
- * <p>This method requires the caller to hold either the
- * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission
- * or the ability to modify system settings as determined by
- * {@link android.provider.Settings.System#canWrite}.</p>
- *
- * @param request {@link NetworkRequest} describing this request.
- * @param networkCallback The callbacks to be utilized for this request. Note
- * the callbacks must not be shared - they uniquely specify
- * this request.
- * @param timeoutMs The time in milliseconds to attempt looking for a suitable network
- * before {@link NetworkCallback#onUnavailable()} is called. The timeout must
- * be a positive value (i.e. >0).
- * @hide
- */
- public void requestNetwork(NetworkRequest request, NetworkCallback networkCallback,
- int timeoutMs) {
- if (timeoutMs <= 0) {
- throw new IllegalArgumentException("Non-positive timeoutMs: " + timeoutMs);
- }
- int legacyType = inferLegacyTypeForNetworkCapabilities(request.networkCapabilities);
- requestNetwork(request, networkCallback, timeoutMs, legacyType, getDefaultHandler());
- }
-
- /**
* Request a network to satisfy a set of {@link android.net.NetworkCapabilities}, limited
* by a timeout.
*
@@ -3077,14 +3033,14 @@
* {@link android.provider.Settings.System#canWrite}.</p>
*
* @param request {@link NetworkRequest} describing this request.
+ * @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note
+ * the callback must not be shared - it uniquely specifies this request.
* @param timeoutMs The time in milliseconds to attempt looking for a suitable network
* before {@link NetworkCallback#onUnavailable()} is called. The timeout must
* be a positive value (i.e. >0).
- * @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note
- * the callback must not be shared - it uniquely specifies this request.
*/
- public void requestNetwork(NetworkRequest request, int timeoutMs,
- NetworkCallback networkCallback) {
+ public void requestNetwork(NetworkRequest request, NetworkCallback networkCallback,
+ int timeoutMs) {
if (timeoutMs <= 0) {
throw new IllegalArgumentException("Non-positive timeoutMs: " + timeoutMs);
}
@@ -3114,14 +3070,14 @@
* {@link android.provider.Settings.System#canWrite}.</p>
*
* @param request {@link NetworkRequest} describing this request.
- * @param timeoutMs The time in milliseconds to attempt looking for a suitable network
- * before {@link NetworkCallback#onUnavailable} is called.
* @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note
* the callback must not be shared - it uniquely specifies this request.
* @param handler {@link Handler} to specify the thread upon which the callback will be invoked.
+ * @param timeoutMs The time in milliseconds to attempt looking for a suitable network
+ * before {@link NetworkCallback#onUnavailable} is called.
*/
- public void requestNetwork(NetworkRequest request, int timeoutMs,
- NetworkCallback networkCallback, Handler handler) {
+ public void requestNetwork(NetworkRequest request, NetworkCallback networkCallback,
+ Handler handler, int timeoutMs) {
if (timeoutMs <= 0) {
throw new IllegalArgumentException("Non-positive timeoutMs");
}
@@ -3470,8 +3426,8 @@
/**
* It is acceptable to briefly use multipath data to provide seamless connectivity for
* time-sensitive user-facing operations when the system default network is temporarily
- * unresponsive. The amount of data should be limited (less than one megabyte), and the
- * operation should be infrequent to ensure that data usage is limited.
+ * unresponsive. The amount of data should be limited (less than one megabyte for every call to
+ * this method), and the operation should be infrequent to ensure that data usage is limited.
*
* An example of such an operation might be a time-sensitive foreground activity, such as a
* voice command, that the user is performing while walking out of range of a Wi-Fi network.