From 5ac64c51f5f622ae370c23840598568b0f67327d Mon Sep 17 00:00:00 2001 From: Hugo Benichi Date: Mon, 15 May 2017 15:15:33 +0900 Subject: [PATCH] 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) --- .../java/android/net/ConnectivityManager.java | 70 ++++--------------- 1 file changed, 13 insertions(+), 57 deletions(-) diff --git a/core/java/android/net/ConnectivityManager.java b/core/java/android/net/ConnectivityManager.java index 234bef7483..1876471aa3 100644 --- a/core/java/android/net/ConnectivityManager.java +++ b/core/java/android/net/ConnectivityManager.java @@ -2647,7 +2647,7 @@ public class ConnectivityManager { /** * 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 @@ public class ConnectivityManager { * 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 @@ public class ConnectivityManager { * 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. @@ -3011,50 +3011,6 @@ public class ConnectivityManager { requestNetwork(request, networkCallback, 0, legacyType, cbHandler); } - /** - * 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. - * - *

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. - * - *

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}.

- * - * @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 @@ public class ConnectivityManager { * {@link android.provider.Settings.System#canWrite}.

* * @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 @@ public class ConnectivityManager { * {@link android.provider.Settings.System#canWrite}.

* * @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 @@ public class ConnectivityManager { /** * 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.