From 0eec03f75c4a7b5b261f2174a148863f9fd8174f Mon Sep 17 00:00:00 2001 From: Hugo Benichi Date: Mon, 15 May 2017 15:15:33 +0900 Subject: Address ConnectivityManager API comments. This patch is a cherry pick of the two following commits: - 15fd4395e13b4662a262ee67a5f75f5c521c62ef which addresses several issues in the public api of ConnectivityManager. - e2d48ff57c5529b32a9cd7bfdcf21d29df539f73 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 15fd4395e13b4662a262ee67a5f75f5c521c62ef) --- api/current.txt | 4 +- api/system-current.txt | 4 +- api/test-current.txt | 4 +- core/java/android/net/ConnectivityManager.java | 68 +++++--------------------- 4 files changed, 18 insertions(+), 62 deletions(-) diff --git a/api/current.txt b/api/current.txt index 55dda042e19c..4275e9db05ce 100644 --- a/api/current.txt +++ b/api/current.txt @@ -23784,8 +23784,8 @@ package android.net { method public boolean requestBandwidthUpdate(android.net.Network); method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback); method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, android.os.Handler); - method public void requestNetwork(android.net.NetworkRequest, int, android.net.ConnectivityManager.NetworkCallback); - method public void requestNetwork(android.net.NetworkRequest, int, android.net.ConnectivityManager.NetworkCallback, android.os.Handler); + method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, int); + method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, android.os.Handler, int); method public void requestNetwork(android.net.NetworkRequest, android.app.PendingIntent); method public deprecated boolean requestRouteToHost(int, int); method public deprecated void setNetworkPreference(int); diff --git a/api/system-current.txt b/api/system-current.txt index 5e9c7e39bfda..f33d50644883 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -25572,8 +25572,8 @@ package android.net { method public boolean requestBandwidthUpdate(android.net.Network); method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback); method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, android.os.Handler); - method public void requestNetwork(android.net.NetworkRequest, int, android.net.ConnectivityManager.NetworkCallback); - method public void requestNetwork(android.net.NetworkRequest, int, android.net.ConnectivityManager.NetworkCallback, android.os.Handler); + method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, int); + method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, android.os.Handler, int); method public void requestNetwork(android.net.NetworkRequest, android.app.PendingIntent); method public deprecated boolean requestRouteToHost(int, int); method public deprecated void setNetworkPreference(int); diff --git a/api/test-current.txt b/api/test-current.txt index 5487a9770fd1..bd96efb25d73 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -23858,8 +23858,8 @@ package android.net { method public boolean requestBandwidthUpdate(android.net.Network); method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback); method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, android.os.Handler); - method public void requestNetwork(android.net.NetworkRequest, int, android.net.ConnectivityManager.NetworkCallback); - method public void requestNetwork(android.net.NetworkRequest, int, android.net.ConnectivityManager.NetworkCallback, android.os.Handler); + method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, int); + method public void requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, android.os.Handler, int); method public void requestNetwork(android.net.NetworkRequest, android.app.PendingIntent); method public deprecated boolean requestRouteToHost(int, int); method public deprecated void setNetworkPreference(int); diff --git a/core/java/android/net/ConnectivityManager.java b/core/java/android/net/ConnectivityManager.java index 234bef7483aa..1876471aa344 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. @@ -3012,11 +3012,6 @@ public class ConnectivityManager { } /** - * 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. * @@ -3029,7 +3024,7 @@ public class ConnectivityManager { * 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 + * timeout) - {@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 @@ -3038,13 +3033,11 @@ public class ConnectivityManager { * {@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 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). - * @hide */ public void requestNetwork(NetworkRequest request, NetworkCallback networkCallback, int timeoutMs) { @@ -3055,43 +3048,6 @@ public class ConnectivityManager { requestNetwork(request, networkCallback, timeoutMs, legacyType, getDefaultHandler()); } - /** - * 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) - {@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 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) { - 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 @@ -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. -- cgit v1.2.3-59-g8ed1b