This method requires the caller to hold the permission * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. + * @deprecated Functionality has been removed as it no longer makes sense, + * with many more than two networks - we'd need an array to express + * preference. Instead we use dynamic network properties of + * the networks to describe their precedence. */ public int getNetworkPreference() { - // TODO - deprecate with: - // @deprecated Functionality has been removed as it no longer makes sense, - // with many more than two networks - we'd need an array to express - // preference. Instead we use dynamic network properties of - // the networks to describe their precedence. - return -1; + return TYPE_NONE; } /** @@ -716,7 +717,13 @@ public class ConnectivityManager { } } - /** {@hide} */ + /** + * Get the {@link LinkProperties} for the given {@link Network}. This + * will return {@code null} if the network is unknown. + * + * @param network The {@link Network} object identifying the network in question. + * @return The {@link LinkProperties} for the network, or {@code null}. + **/ public LinkProperties getLinkProperties(Network network) { try { return mService.getLinkProperties(network); @@ -725,7 +732,13 @@ public class ConnectivityManager { } } - /** {@hide} */ + /** + * Get the {@link NetworkCapabilities} for the given {@link Network}. This + * will return {@code null} if the network is unknown. + * + * @param network The {@link Network} object identifying the network in question. + * @return The {@link NetworkCapabilities} for the network, or {@code null}. + */ public NetworkCapabilities getNetworkCapabilities(Network network) { try { return mService.getNetworkCapabilities(network); @@ -788,6 +801,8 @@ public class ConnectivityManager { * The interpretation of this value is specific to each networking * implementation+feature combination, except that the value {@code -1} * always indicates failure. + * + * @deprecated Deprecated in favor of the cleaner {@link #requestNetwork} api. */ public int startUsingNetworkFeature(int networkType, String feature) { try { @@ -810,6 +825,8 @@ public class ConnectivityManager { * The interpretation of this value is specific to each networking * implementation+feature combination, except that the value {@code -1} * always indicates failure. + * + * @deprecated Deprecated in favor of the cleaner {@link #requestNetwork} api. */ public int stopUsingNetworkFeature(int networkType, String feature) { try { @@ -829,6 +846,9 @@ public class ConnectivityManager { * host is to be routed * @param hostAddress the IP address of the host to which the route is desired * @return {@code true} on success, {@code false} on failure + * + * @deprecated Deprecated in favor of the {@link #requestNetwork}, + * {@link Network#bindProcess} and {@link Network#socketFactory} api. */ public boolean requestRouteToHost(int networkType, int hostAddress) { InetAddress inetAddress = NetworkUtils.intToInetAddress(hostAddress); @@ -851,6 +871,8 @@ public class ConnectivityManager { * @param hostAddress the IP address of the host to which the route is desired * @return {@code true} on success, {@code false} on failure * @hide + * @deprecated Deprecated in favor of the {@link #requestNetwork} and + * {@link Network#bindProcess} api. */ public boolean requestRouteToHostAddress(int networkType, InetAddress hostAddress) { byte[] address = hostAddress.getAddress(); @@ -1332,13 +1354,13 @@ public class ConnectivityManager { } /** - * Report a problem network to the framework. This will cause the framework - * to evaluate the situation and try to fix any problems. Note that false - * may be subsequently ignored. + * Report a problem network to the framework. This provides a hint to the system + * that there might be connectivity problems on this network and may cause + * the framework to re-evaluate network connectivity and/or switch to another + * network. * - * @param network The Network the application was attempting to use or null - * to indicate the current default network. - * {@hide} + * @param network The {@link Network} the application was attempting to use + * or {@code null} to indicate the current default network. */ public void reportBadNetwork(Network network) { try { @@ -1358,6 +1380,7 @@ public class ConnectivityManager { * *
This method requires the call to hold the permission * android.Manifest.permission#CONNECTIVITY_INTERNAL. + * @hide */ public void setGlobalProxy(ProxyInfo p) { try { @@ -1374,6 +1397,7 @@ public class ConnectivityManager { * *
This method requires the call to hold the permission * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. + * @hide */ public ProxyInfo getGlobalProxy() { try { @@ -1393,6 +1417,7 @@ public class ConnectivityManager { *
This method requires the call to hold the permission
* {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
* {@hide}
+ * @deprecated Deprecated in favor of {@link #getLinkProperties}
*/
public ProxyInfo getProxy() {
try {
@@ -1645,11 +1670,10 @@ public class ConnectivityManager {
}
/**
- * Interface for NetworkRequest callbacks. Used for notifications about network
- * changes.
- * @hide
+ * Base class for NetworkRequest callbacks. Used for notifications about network
+ * changes. Should be extended by applications wanting notifications.
*/
- public static class NetworkCallbacks {
+ public static class NetworkCallbackListener {
/** @hide */
public static final int PRECHECK = 1;
/** @hide */
@@ -1675,51 +1699,73 @@ public class ConnectivityManager {
public void onPreCheck(NetworkRequest networkRequest, Network network) {}
/**
- * Called when the framework connects and has validated the new network.
+ * Called when the framework connects and has declared new network ready for use.
+ *
+ * @param networkRequest The {@link NetworkRequest} used to initiate the request.
+ * @param network The {@link Network} of the satisfying network.
*/
public void onAvailable(NetworkRequest networkRequest, Network network) {}
/**
- * Called when the framework is losing the network. Often paired with an
- * onAvailable call with the new replacement network for graceful handover.
- * This may not be called if we have a hard loss (loss without warning).
- * This may be followed by either an onLost call or an onAvailable call for this
- * network depending on if we lose or regain it.
+ * Called when the network is about to be disconnected. Often paired with an
+ * {@link NetworkCallbackListener#onAvailable} call with the new replacement network
+ * for graceful handover. This may not be called if we have a hard loss
+ * (loss without warning). This may be followed by either a
+ * {@link NetworkCallbackListener#onLost} call or a
+ * {@link NetworkCallbackListener#onAvailable} call for this network depending
+ * on whether we lose or regain it.
+ *
+ * @param networkRequest The {@link NetworkRequest} used to initiate the request.
+ * @param network The {@link Network} of the failing network.
+ * @param maxSecToLive The time in seconds the framework will attempt to keep the
+ * network connected. Note that the network may suffers a
+ * hard loss at any time.
*/
public void onLosing(NetworkRequest networkRequest, Network network, int maxSecToLive) {}
/**
* Called when the framework has a hard loss of the network or when the
- * graceful failure ends. Note applications should only request this callback
- * if the application is willing to track the Available and Lost callbacks
- * together, else the application may think it has no network when it
- * really does (A Avail, B Avail, A Lost.. still have B).
+ * graceful failure ends.
+ *
+ * @param networkRequest The {@link NetworkRequest} used to initiate the request.
+ * @param network The {@link Network} lost.
*/
public void onLost(NetworkRequest networkRequest, Network network) {}
/**
* Called if no network is found in the given timeout time. If no timeout is given,
* this will not be called.
+ * @hide
*/
public void onUnavailable(NetworkRequest networkRequest) {}
/**
* Called when the network the framework connected to for this request
* changes capabilities but still satisfies the stated need.
+ *
+ * @param networkRequest The {@link NetworkRequest} used to initiate the request.
+ * @param network The {@link Network} whose capabilities have changed.
+ * @param networkCapabilities The new {@link NetworkCapabilities} for this network.
*/
public void onNetworkCapabilitiesChanged(NetworkRequest networkRequest, Network network,
NetworkCapabilities networkCapabilities) {}
/**
* Called when the network the framework connected to for this request
- * changes LinkProperties.
+ * changes {@link LinkProperties}.
+ *
+ * @param networkRequest The {@link NetworkRequest} used to initiate the request.
+ * @param network The {@link Network} whose link properties have changed.
+ * @param linkProperties The new {@link LinkProperties} for this network.
*/
public void onLinkPropertiesChanged(NetworkRequest networkRequest, Network network,
LinkProperties linkProperties) {}
/**
- * Called when a releaseNetworkRequest call concludes and the registered callbacks will
- * no longer be used.
+ * Called when a {@link #releaseNetworkRequest} call concludes and the registered
+ * callbacks will no longer be used.
+ *
+ * @param networkRequest The {@link NetworkRequest} used to initiate the request.
*/
public void onReleased(NetworkRequest networkRequest) {}
}
@@ -1745,12 +1791,12 @@ public class ConnectivityManager {
public static final int CALLBACK_EXIT = BASE + 9;
private static class CallbackHandler extends Handler {
- private final HashMap
* The operation is an Intent broadcast that goes to a broadcast receiver that
* you registered with {@link Context#registerReceiver} or through the
* <receiver> tag in an AndroidManifest.xml file
*
* The operation Intent is delivered with two extras, a {@link Network} typed
- * extra called {@link EXTRA_NETWORK_REQUEST_NETWORK} and a {@link NetworkCapabilities}
- * typed extra called {@link EXTRA_NETWORK_REQUEST_NETWORK_CAPABILTIES} containing
+ * extra called {@link #EXTRA_NETWORK_REQUEST_NETWORK} and a {@link NetworkCapabilities}
+ * typed extra called {@link #EXTRA_NETWORK_REQUEST_NETWORK_CAPABILITIES} containing
* the original requests parameters. It is important to create a new,
- * {@link NetworkCallbacks} based request before completing the processing of the
+ * {@link NetworkCallbackListener} based request before completing the processing of the
* Intent to reserve the network or it will be released shortly after the Intent
* is processed.
*
* If there is already an request for this Intent registered (with the equality of
* two Intents defined by {@link Intent#filterEquals}), then it will be removed and
- * replace by this one, effectively releasing the previous {@link NetworkRequest}.
+ * replaced by this one, effectively releasing the previous {@link NetworkRequest}.
*
- * The request may be released normally by calling {@link releaseNetworkRequest}.
+ * The request may be released normally by calling {@link #releaseNetworkRequest}.
*
- * @param need {@link NetworkCapabilties} required by this request.
+ * @param need {@link NetworkCapabilities} required by this request.
* @param operation Action to perform when the network is available (corresponds
- * to the {@link NetworkCallbacks#onAvailable} call. Typically
+ * to the {@link NetworkCallbackListener#onAvailable} call. Typically
* comes from {@link PendingIntent#getBroadcast}.
* @return A {@link NetworkRequest} object identifying the request.
- * @hide
*/
public NetworkRequest requestNetwork(NetworkCapabilities need, PendingIntent operation) {
try {
@@ -2035,28 +2097,27 @@ public class ConnectivityManager {
* Registers to receive notifications about all networks which satisfy the given
* {@link NetworkCapabilities}. The callbacks will continue to be called until
* either the application exits or the request is released using
- * {@link releaseNetworkRequest}.
+ * {@link #releaseNetworkRequest}.
*
* @param need {@link NetworkCapabilities} required by this request.
- * @param networkCallbacks The {@link NetworkCallbacks} to be called as suitable
+ * @param networkCallbackListener The {@link NetworkCallbackListener} to be called as suitable
* networks change state.
* @return A {@link NetworkRequest} object identifying the request.
- * @hide
*/
public NetworkRequest listenForNetwork(NetworkCapabilities need,
- NetworkCallbacks networkCallbacks) {
- return somethingForNetwork(need, networkCallbacks, 0, LISTEN);
+ NetworkCallbackListener networkCallbackListener) {
+ return somethingForNetwork(need, networkCallbackListener, 0, LISTEN);
}
/**
- * Releases a {NetworkRequest} generated either through a {@link requestNetwork}
- * or a {@link listenForNetwork} call. The {@link NetworkCallbacks} given in the
- * earlier call may continue receiving calls until the {@link NetworkCallbacks#onReleased}
- * function is called, signifiying the end of the request.
+ * Releases a {@link NetworkRequest} generated either through a {@link #requestNetwork}
+ * or a {@link #listenForNetwork} call. The {@link NetworkCallbackListener} given in the
+ * earlier call may continue receiving calls until the
+ * {@link NetworkCallbackListener#onReleased} function is called, signifying the end
+ * of the request.
*
* @param networkRequest The {@link NetworkRequest} generated by an earlier call to
- * {@link requestNetwork} or {@link listenForNetwork}.
- * @hide
+ * {@link #requestNetwork} or {@link #listenForNetwork}.
*/
public void releaseNetworkRequest(NetworkRequest networkRequest) {
if (networkRequest == null) throw new IllegalArgumentException("null NetworkRequest");
diff --git a/core/java/android/net/Network.java b/core/java/android/net/Network.java
index a99da789f3ce6..e0d69e372c831 100644
--- a/core/java/android/net/Network.java
+++ b/core/java/android/net/Network.java
@@ -26,11 +26,10 @@ import javax.net.SocketFactory;
/**
* Identifies a {@code Network}. This is supplied to applications via
- * {@link ConnectivityManager#NetworkCallbacks} in response to
+ * {@link ConnectivityManager.NetworkCallbackListener} in response to
* {@link ConnectivityManager#requestNetwork} or {@link ConnectivityManager#listenForNetwork}.
* It is used to direct traffic to the given {@code Network}, either on a {@link Socket} basis
* through a targeted {@link SocketFactory} or process-wide via {@link #bindProcess}.
- * @hide
*/
public class Network implements Parcelable {
diff --git a/core/java/android/net/NetworkRequest.java b/core/java/android/net/NetworkRequest.java
index 80074a5e7a5de..480cb057b075b 100644
--- a/core/java/android/net/NetworkRequest.java
+++ b/core/java/android/net/NetworkRequest.java
@@ -22,18 +22,18 @@ import android.os.Parcelable;
import java.util.concurrent.atomic.AtomicInteger;
/**
- * Defines a request for a network, made by calling {@link ConnectivityManager.requestNetwork}.
+ * Defines a request for a network, made by calling {@link ConnectivityManager#requestNetwork}
+ * or {@link ConnectivityManager#listenForNetwork}.
*
* This token records the {@link NetworkCapabilities} used to make the request and identifies
* the request. It should be used to release the request via
- * {@link ConnectivityManager.releaseNetworkRequest} when the network is no longer desired.
- * @hide
+ * {@link ConnectivityManager#releaseNetworkRequest} when the network is no longer desired.
*/
public class NetworkRequest implements Parcelable {
/**
* The {@link NetworkCapabilities} that define this request. This should not be modified.
* The networkCapabilities of the request are set when
- * {@link ConnectivityManager.requestNetwork} is called and the value is presented here
+ * {@link ConnectivityManager#requestNetwork} is called and the value is presented here
* as a convenient reminder of what was requested.
*/
public final NetworkCapabilities networkCapabilities;