Merge "Address ConnectivityManager API comments." into oc-dev

am: 2121eeec48

Change-Id: I7024b4fe23ab12760fb452a59929df886912b104

core/java/android/net/ConnectivityManager.java

@@ -2981,50 +2981,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.
-     *
-     * <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.
@@ -3047,14 +3003,14 @@ public class ConnectivityManager {
      * {@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,
+    public void requestNetwork(NetworkRequest request, NetworkCallback networkCallback,
-            NetworkCallback networkCallback) {
+            int timeoutMs) {
         if (timeoutMs <= 0) {
             throw new IllegalArgumentException("Non-positive timeoutMs: " + timeoutMs);
         }
@@ -3084,14 +3040,14 @@ public class ConnectivityManager {
      * {@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,
+    public void requestNetwork(NetworkRequest request, NetworkCallback networkCallback,
-            NetworkCallback networkCallback, Handler handler) {
+            Handler handler, int timeoutMs) {
         if (timeoutMs <= 0) {
             throw new IllegalArgumentException("Non-positive timeoutMs");
         }
@@ -3427,8 +3383,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
+     * unresponsive. The amount of data should be limited (less than one megabyte for every call to
-     * operation should be infrequent to ensure that data usage is limited.
+     * 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.