LineageOS/android_packages_modules_Connectivity
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add javadoc and unhide new API

Browse Source 
Change-Id: I12e475bbf4000c7acec4ca27b1d3bf8f870cc2cf
This commit is contained in:
Robert Greenwalt
2014-05-18 23:07:25 -07:00
parent eaa84d5dda
commit f3017f74a0
3 changed files with 164 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
core/java/android/net/ConnectivityManager.java
View File

@@ -21,6 +21,7 @@ import android.annotation.SdkConstant;
import android.annotation.SdkConstant.SdkConstantType; import android.annotation.SdkConstant.SdkConstantType;
import android.app.PendingIntent; import android.app.PendingIntent;
import android.content.Context; import android.content.Context;
import android.content.Intent;
import android.os.Binder; import android.os.Binder;
import android.os.Build.VERSION_CODES; import android.os.Build.VERSION_CODES;
import android.os.Handler; import android.os.Handler;
@@ -57,13 +58,15 @@ import com.android.internal.util.Protocol;
* is lost</li> * is lost</li>
* <li>Provide an API that allows applications to query the coarse-grained or fine-grained * <li>Provide an API that allows applications to query the coarse-grained or fine-grained
* state of the available networks</li> * state of the available networks</li>
* <li>Provide an API that allows applications to request and select networks for their data
* traffic</li>
* </ol> * </ol>
*/ */
public class ConnectivityManager { public class ConnectivityManager {
private static final String TAG = "ConnectivityManager"; private static final String TAG = "ConnectivityManager";
/** /**
* A change in network connectivity has occurred. A connection has either * A change in network connectivity has occurred. A default connection has either
* been established or lost. The NetworkInfo for the affected network is * been established or lost. The NetworkInfo for the affected network is
* sent as an extra; it should be consulted to see what kind of * sent as an extra; it should be consulted to see what kind of
* connectivity event occurred. * connectivity event occurred.
@@ -547,13 +550,12 @@ public class ConnectivityManager {
* @param preference the network type to prefer over all others. It is * @param preference the network type to prefer over all others. It is
* unspecified what happens to the old preferred network in the * unspecified what happens to the old preferred network in the
* overall ordering. * overall ordering.
* @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 void setNetworkPreference(int preference) { public void setNetworkPreference(int preference) {
// 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.
} }
/** /**
@@ -563,14 +565,13 @@ public class ConnectivityManager {
* *
* <p>This method requires the caller to hold the permission * <p>This method requires the caller to hold the permission
* {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * {@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() { public int getNetworkPreference() {
// TODO - deprecate with: return TYPE_NONE;
// @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;
} }
/** /**
@@ -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) { public LinkProperties getLinkProperties(Network network) {
try { try {
return mService.getLinkProperties(network); 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) { public NetworkCapabilities getNetworkCapabilities(Network network) {
try { try {
return mService.getNetworkCapabilities(network); return mService.getNetworkCapabilities(network);
@@ -788,6 +801,8 @@ public class ConnectivityManager {
* The interpretation of this value is specific to each networking * The interpretation of this value is specific to each networking
* implementation+feature combination, except that the value {@code -1} * implementation+feature combination, except that the value {@code -1}
* always indicates failure. * always indicates failure.
*
* @deprecated Deprecated in favor of the cleaner {@link #requestNetwork} api.
*/ */
public int startUsingNetworkFeature(int networkType, String feature) { public int startUsingNetworkFeature(int networkType, String feature) {
try { try {
@@ -810,6 +825,8 @@ public class ConnectivityManager {
* The interpretation of this value is specific to each networking * The interpretation of this value is specific to each networking
* implementation+feature combination, except that the value {@code -1} * implementation+feature combination, except that the value {@code -1}
* always indicates failure. * always indicates failure.
*
* @deprecated Deprecated in favor of the cleaner {@link #requestNetwork} api.
*/ */
public int stopUsingNetworkFeature(int networkType, String feature) { public int stopUsingNetworkFeature(int networkType, String feature) {
try { try {
@@ -829,6 +846,9 @@ public class ConnectivityManager {
* host is to be routed * host is to be routed
* @param hostAddress the IP address of the host to which the route is desired * @param hostAddress the IP address of the host to which the route is desired
* @return {@code true} on success, {@code false} on failure * @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) { public boolean requestRouteToHost(int networkType, int hostAddress) {
InetAddress inetAddress = NetworkUtils.intToInetAddress(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 * @param hostAddress the IP address of the host to which the route is desired
* @return {@code true} on success, {@code false} on failure * @return {@code true} on success, {@code false} on failure
* @hide * @hide
* @deprecated Deprecated in favor of the {@link #requestNetwork} and
* {@link Network#bindProcess} api.
*/ */
public boolean requestRouteToHostAddress(int networkType, InetAddress hostAddress) { public boolean requestRouteToHostAddress(int networkType, InetAddress hostAddress) {
byte[] address = hostAddress.getAddress(); byte[] address = hostAddress.getAddress();
@@ -1332,13 +1354,13 @@ public class ConnectivityManager {
} }
/** /**
* Report a problem network to the framework. This will cause the framework * Report a problem network to the framework. This provides a hint to the system
* to evaluate the situation and try to fix any problems. Note that false * that there might be connectivity problems on this network and may cause
* may be subsequently ignored. * 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 * @param network The {@link Network} the application was attempting to use
* to indicate the current default network. * or {@code null} to indicate the current default network.
* {@hide}
*/ */
public void reportBadNetwork(Network network) { public void reportBadNetwork(Network network) {
try { try {
@@ -1358,6 +1380,7 @@ public class ConnectivityManager {
* *
* <p>This method requires the call to hold the permission * <p>This method requires the call to hold the permission
* android.Manifest.permission#CONNECTIVITY_INTERNAL. * android.Manifest.permission#CONNECTIVITY_INTERNAL.
* @hide
*/ */
public void setGlobalProxy(ProxyInfo p) { public void setGlobalProxy(ProxyInfo p) {
try { try {
@@ -1374,6 +1397,7 @@ public class ConnectivityManager {
* *
* <p>This method requires the call to hold the permission * <p>This method requires the call to hold the permission
* {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
* @hide
*/ */
public ProxyInfo getGlobalProxy() { public ProxyInfo getGlobalProxy() {
try { try {
@@ -1393,6 +1417,7 @@ public class ConnectivityManager {
* <p>This method requires the call to hold the permission * <p>This method requires the call to hold the permission
* {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}.
* {@hide} * {@hide}
* @deprecated Deprecated in favor of {@link #getLinkProperties}
*/ */
public ProxyInfo getProxy() { public ProxyInfo getProxy() {
try { try {
@@ -1645,11 +1670,10 @@ public class ConnectivityManager {
} }
/** /**
* Interface for NetworkRequest callbacks. Used for notifications about network * Base class for NetworkRequest callbacks. Used for notifications about network
* changes. * changes. Should be extended by applications wanting notifications.
* @hide
*/ */
public static class NetworkCallbacks { public static class NetworkCallbackListener {
/** @hide */ /** @hide */
public static final int PRECHECK = 1; public static final int PRECHECK = 1;
/** @hide */ /** @hide */
@@ -1675,51 +1699,73 @@ public class ConnectivityManager {
public void onPreCheck(NetworkRequest networkRequest, Network network) {} 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) {} public void onAvailable(NetworkRequest networkRequest, Network network) {}
/** /**
* Called when the framework is losing the network. Often paired with an * Called when the network is about to be disconnected. Often paired with an
* onAvailable call with the new replacement network for graceful handover. * {@link NetworkCallbackListener#onAvailable} call with the new replacement network
* This may not be called if we have a hard loss (loss without warning). * for graceful handover. This may not be called if we have a hard loss
* This may be followed by either an onLost call or an onAvailable call for this * (loss without warning). This may be followed by either a
* network depending on if we lose or regain it. * {@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) {} public void onLosing(NetworkRequest networkRequest, Network network, int maxSecToLive) {}
/** /**
* Called when the framework has a hard loss of the network or when the * Called when the framework has a hard loss of the network or when the
* graceful failure ends. Note applications should only request this callback * graceful failure ends.
* if the application is willing to track the Available and Lost callbacks *
* together, else the application may think it has no network when it * @param networkRequest The {@link NetworkRequest} used to initiate the request.
* really does (A Avail, B Avail, A Lost.. still have B). * @param network The {@link Network} lost.
*/ */
public void onLost(NetworkRequest networkRequest, Network network) {} public void onLost(NetworkRequest networkRequest, Network network) {}
/** /**
* Called if no network is found in the given timeout time. If no timeout is given, * Called if no network is found in the given timeout time. If no timeout is given,
* this will not be called. * this will not be called.
* @hide
*/ */
public void onUnavailable(NetworkRequest networkRequest) {} public void onUnavailable(NetworkRequest networkRequest) {}
/** /**
* Called when the network the framework connected to for this request * Called when the network the framework connected to for this request
* changes capabilities but still satisfies the stated need. * 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, public void onNetworkCapabilitiesChanged(NetworkRequest networkRequest, Network network,
NetworkCapabilities networkCapabilities) {} NetworkCapabilities networkCapabilities) {}
/** /**
* Called when the network the framework connected to for this request * 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, public void onLinkPropertiesChanged(NetworkRequest networkRequest, Network network,
LinkProperties linkProperties) {} LinkProperties linkProperties) {}
/** /**
* Called when a releaseNetworkRequest call concludes and the registered callbacks will * Called when a {@link #releaseNetworkRequest} call concludes and the registered
* no longer be used. * callbacks will no longer be used.
*
* @param networkRequest The {@link NetworkRequest} used to initiate the request.
*/ */
public void onReleased(NetworkRequest networkRequest) {} public void onReleased(NetworkRequest networkRequest) {}
} }
@@ -1745,12 +1791,12 @@ public class ConnectivityManager {
public static final int CALLBACK_EXIT = BASE + 9; public static final int CALLBACK_EXIT = BASE + 9;
private static class CallbackHandler extends Handler { private static class CallbackHandler extends Handler {
private final HashMap<NetworkRequest, NetworkCallbacks>mCallbackMap; private final HashMap<NetworkRequest, NetworkCallbackListener>mCallbackMap;
private final AtomicInteger mRefCount; private final AtomicInteger mRefCount;
private static final String TAG = "ConnectivityManager.CallbackHandler"; private static final String TAG = "ConnectivityManager.CallbackHandler";
private final ConnectivityManager mCm; private final ConnectivityManager mCm;
CallbackHandler(Looper looper, HashMap<NetworkRequest, NetworkCallbacks>callbackMap, CallbackHandler(Looper looper, HashMap<NetworkRequest, NetworkCallbackListener>callbackMap,
AtomicInteger refCount, ConnectivityManager cm) { AtomicInteger refCount, ConnectivityManager cm) {
super(looper); super(looper);
mCallbackMap = callbackMap; mCallbackMap = callbackMap;
@@ -1764,7 +1810,7 @@ public class ConnectivityManager {
switch (message.what) { switch (message.what) {
case CALLBACK_PRECHECK: { case CALLBACK_PRECHECK: {
NetworkRequest request = getNetworkRequest(message); NetworkRequest request = getNetworkRequest(message);
NetworkCallbacks callbacks = getCallbacks(request); NetworkCallbackListener callbacks = getCallbacks(request);
if (callbacks != null) { if (callbacks != null) {
callbacks.onPreCheck(request, getNetwork(message)); callbacks.onPreCheck(request, getNetwork(message));
} else { } else {
@@ -1774,7 +1820,7 @@ public class ConnectivityManager {
} }
case CALLBACK_AVAILABLE: { case CALLBACK_AVAILABLE: {
NetworkRequest request = getNetworkRequest(message); NetworkRequest request = getNetworkRequest(message);
NetworkCallbacks callbacks = getCallbacks(request); NetworkCallbackListener callbacks = getCallbacks(request);
if (callbacks != null) { if (callbacks != null) {
callbacks.onAvailable(request, getNetwork(message)); callbacks.onAvailable(request, getNetwork(message));
} else { } else {
@@ -1784,7 +1830,7 @@ public class ConnectivityManager {
} }
case CALLBACK_LOSING: { case CALLBACK_LOSING: {
NetworkRequest request = getNetworkRequest(message); NetworkRequest request = getNetworkRequest(message);
NetworkCallbacks callbacks = getCallbacks(request); NetworkCallbackListener callbacks = getCallbacks(request);
if (callbacks != null) { if (callbacks != null) {
callbacks.onLosing(request, getNetwork(message), message.arg1); callbacks.onLosing(request, getNetwork(message), message.arg1);
} else { } else {
@@ -1794,7 +1840,7 @@ public class ConnectivityManager {
} }
case CALLBACK_LOST: { case CALLBACK_LOST: {
NetworkRequest request = getNetworkRequest(message); NetworkRequest request = getNetworkRequest(message);
NetworkCallbacks callbacks = getCallbacks(request); NetworkCallbackListener callbacks = getCallbacks(request);
if (callbacks != null) { if (callbacks != null) {
callbacks.onLost(request, getNetwork(message)); callbacks.onLost(request, getNetwork(message));
} else { } else {
@@ -1804,7 +1850,7 @@ public class ConnectivityManager {
} }
case CALLBACK_UNAVAIL: { case CALLBACK_UNAVAIL: {
NetworkRequest req = (NetworkRequest)message.obj; NetworkRequest req = (NetworkRequest)message.obj;
NetworkCallbacks callbacks = null; NetworkCallbackListener callbacks = null;
synchronized(mCallbackMap) { synchronized(mCallbackMap) {
callbacks = mCallbackMap.get(req); callbacks = mCallbackMap.get(req);
} }
@@ -1817,7 +1863,7 @@ public class ConnectivityManager {
} }
case CALLBACK_CAP_CHANGED: { case CALLBACK_CAP_CHANGED: {
NetworkRequest request = getNetworkRequest(message); NetworkRequest request = getNetworkRequest(message);
NetworkCallbacks callbacks = getCallbacks(request); NetworkCallbackListener callbacks = getCallbacks(request);
if (callbacks != null) { if (callbacks != null) {
Network network = getNetwork(message); Network network = getNetwork(message);
NetworkCapabilities cap = mCm.getNetworkCapabilities(network); NetworkCapabilities cap = mCm.getNetworkCapabilities(network);
@@ -1830,7 +1876,7 @@ public class ConnectivityManager {
} }
case CALLBACK_IP_CHANGED: { case CALLBACK_IP_CHANGED: {
NetworkRequest request = getNetworkRequest(message); NetworkRequest request = getNetworkRequest(message);
NetworkCallbacks callbacks = getCallbacks(request); NetworkCallbackListener callbacks = getCallbacks(request);
if (callbacks != null) { if (callbacks != null) {
Network network = getNetwork(message); Network network = getNetwork(message);
LinkProperties lp = mCm.getLinkProperties(network); LinkProperties lp = mCm.getLinkProperties(network);
@@ -1843,7 +1889,7 @@ public class ConnectivityManager {
} }
case CALLBACK_RELEASED: { case CALLBACK_RELEASED: {
NetworkRequest req = (NetworkRequest)message.obj; NetworkRequest req = (NetworkRequest)message.obj;
NetworkCallbacks callbacks = null; NetworkCallbackListener callbacks = null;
synchronized(mCallbackMap) { synchronized(mCallbackMap) {
callbacks = mCallbackMap.remove(req); callbacks = mCallbackMap.remove(req);
} }
@@ -1870,7 +1916,7 @@ public class ConnectivityManager {
private NetworkRequest getNetworkRequest(Message msg) { private NetworkRequest getNetworkRequest(Message msg) {
return (NetworkRequest)(msg.obj); return (NetworkRequest)(msg.obj);
} }
private NetworkCallbacks getCallbacks(NetworkRequest req) { private NetworkCallbackListener getCallbacks(NetworkRequest req) {
synchronized(mCallbackMap) { synchronized(mCallbackMap) {
return mCallbackMap.get(req); return mCallbackMap.get(req);
} }
@@ -1878,7 +1924,7 @@ public class ConnectivityManager {
private Network getNetwork(Message msg) { private Network getNetwork(Message msg) {
return new Network(msg.arg2); return new Network(msg.arg2);
} }
private NetworkCallbacks removeCallbacks(Message msg) { private NetworkCallbackListener removeCallbacks(Message msg) {
NetworkRequest req = (NetworkRequest)msg.obj; NetworkRequest req = (NetworkRequest)msg.obj;
synchronized(mCallbackMap) { synchronized(mCallbackMap) {
return mCallbackMap.remove(req); return mCallbackMap.remove(req);
@@ -1893,7 +1939,7 @@ public class ConnectivityManager {
HandlerThread callbackThread = new HandlerThread("ConnectivityManager"); HandlerThread callbackThread = new HandlerThread("ConnectivityManager");
callbackThread.start(); callbackThread.start();
sCallbackHandler = new CallbackHandler(callbackThread.getLooper(), sCallbackHandler = new CallbackHandler(callbackThread.getLooper(),
sNetworkCallbacks, sCallbackRefCount, this); sNetworkCallbackListener, sCallbackRefCount, this);
} }
} }
} }
@@ -1907,8 +1953,8 @@ public class ConnectivityManager {
} }
} }
static final HashMap<NetworkRequest, NetworkCallbacks> sNetworkCallbacks = static final HashMap<NetworkRequest, NetworkCallbackListener> sNetworkCallbackListener =
new HashMap<NetworkRequest, NetworkCallbacks>(); new HashMap<NetworkRequest, NetworkCallbackListener>();
static final AtomicInteger sCallbackRefCount = new AtomicInteger(0); static final AtomicInteger sCallbackRefCount = new AtomicInteger(0);
static CallbackHandler sCallbackHandler = null; static CallbackHandler sCallbackHandler = null;
@@ -1916,9 +1962,11 @@ public class ConnectivityManager {
private final static int REQUEST = 2; private final static int REQUEST = 2;
private NetworkRequest somethingForNetwork(NetworkCapabilities need, private NetworkRequest somethingForNetwork(NetworkCapabilities need,
NetworkCallbacks networkCallbacks, int timeoutSec, int action) { NetworkCallbackListener networkCallbackListener, int timeoutSec, int action) {
NetworkRequest networkRequest = null; NetworkRequest networkRequest = null;
if (networkCallbacks == null) throw new IllegalArgumentException("null NetworkCallbacks"); if (networkCallbackListener == null) {
throw new IllegalArgumentException("null NetworkCallbackListener");
}
if (need == null) throw new IllegalArgumentException("null NetworkCapabilities"); if (need == null) throw new IllegalArgumentException("null NetworkCapabilities");
try { try {
addCallbackListener(); addCallbackListener();
@@ -1930,8 +1978,8 @@ public class ConnectivityManager {
timeoutSec, new Binder()); timeoutSec, new Binder());
} }
if (networkRequest != null) { if (networkRequest != null) {
synchronized(sNetworkCallbacks) { synchronized(sNetworkCallbackListener) {
sNetworkCallbacks.put(networkRequest, networkCallbacks); sNetworkCallbackListener.put(networkRequest, networkCallbackListener);
} }
} }
} catch (RemoteException e) {} } catch (RemoteException e) {}
@@ -1943,46 +1991,44 @@ public class ConnectivityManager {
* Request a network to satisfy a set of {@link NetworkCapabilities}. * Request a network to satisfy a set of {@link NetworkCapabilities}.
* *
* This {@link NetworkRequest} will live until released via * This {@link NetworkRequest} will live until released via
* {@link releaseNetworkRequest} or the calling application exits. * {@link #releaseNetworkRequest} or the calling application exits.
* Status of the request can be follwed by listening to the various * Status of the request can be followed by listening to the various
* callbacks described in {@link NetworkCallbacks}. The {@link Network} * callbacks described in {@link NetworkCallbackListener}. The {@link Network}
* can be used by using the {@link bindSocketToNetwork}, * can be used to direct traffic to the network.
* {@link bindApplicationToNetwork} and {@link getAddrInfoOnNetwork} functions.
* *
* @param need {@link NetworkCapabilities} required by this request. * @param need {@link NetworkCapabilities} required by this request.
* @param networkCallbacks The callbacks to be utilized for this request. Note * @param networkCallbackListener The {@link NetworkCallbackListener} to be utilized for this
* the callbacks can be shared by multiple requests and * request. Note the callbacks can be shared by multiple
* the NetworkRequest token utilized to determine to which * requests and the NetworkRequest token utilized to
* request the callback relates. * determine to which request the callback relates.
* @return A {@link NetworkRequest} object identifying the request. * @return A {@link NetworkRequest} object identifying the request.
* @hide
*/ */
public NetworkRequest requestNetwork(NetworkCapabilities need, public NetworkRequest requestNetwork(NetworkCapabilities need,
NetworkCallbacks networkCallbacks) { NetworkCallbackListener networkCallbackListener) {
return somethingForNetwork(need, networkCallbacks, 0, REQUEST); return somethingForNetwork(need, networkCallbackListener, 0, REQUEST);
} }
/** /**
* Request a network to satisfy a set of {@link NetworkCapabilities}, limited * Request a network to satisfy a set of {@link NetworkCapabilities}, limited
* by a timeout. * by a timeout.
* *
* This function behaves identically, but if a suitable network is not found * This function behaves identically to the non-timedout version, but if a suitable
* within the given time (in Seconds) the {@link NetworkCallbacks#unavailable} * network is not found within the given time (in Seconds) the
* callback is called. The request must still be released normally by * {@link NetworkCallbackListener#unavailable} callback is called. The request must
* calling {@link releaseNetworkRequest}. * still be released normally by calling {@link releaseNetworkRequest}.
* @param need {@link NetworkCapabilities} required by this request. * @param need {@link NetworkCapabilities} required by this request.
* @param networkCallbacks The callbacks to be utilized for this request. Note * @param networkCallbackListener The callbacks to be utilized for this request. Note
* the callbacks can be shared by multiple requests and * the callbacks can be shared by multiple requests and
* the NetworkRequest token utilized to determine to which * the NetworkRequest token utilized to determine to which
* request the callback relates. * request the callback relates.
* @param timeoutSec The time in seconds to attempt looking for a suitable network * @param timeoutSec The time in seconds to attempt looking for a suitable network
* before {@link NetworkCallbacks#unavailable} is called. * before {@link NetworkCallbackListener#unavailable} is called.
* @return A {@link NetworkRequest} object identifying the request. * @return A {@link NetworkRequest} object identifying the request.
* @hide * @hide
*/ */
public NetworkRequest requestNetwork(NetworkCapabilities need, public NetworkRequest requestNetwork(NetworkCapabilities need,
NetworkCallbacks networkCallbacks, int timeoutSec) { NetworkCallbackListener networkCallbackListener, int timeoutSec) {
return somethingForNetwork(need, networkCallbacks, timeoutSec, REQUEST); return somethingForNetwork(need, networkCallbackListener, timeoutSec, REQUEST);
} }
/** /**
@@ -1992,37 +2038,53 @@ public class ConnectivityManager {
*/ */
public final static int MAX_NETWORK_REQUEST_TIMEOUT_SEC = 100 * 60; public final static int MAX_NETWORK_REQUEST_TIMEOUT_SEC = 100 * 60;
/**
* The lookup key for a {@link Network} object included with the intent after
* succesfully finding a network for the applications request. Retrieve it with
* {@link android.content.Intent#getParcelableExtra(String)}.
*/
public static final String EXTRA_NETWORK_REQUEST_NETWORK = "networkRequestNetwork";
/**
* The lookup key for a {@link NetworkCapabilities} object included with the intent after
* succesfully finding a network for the applications request. Retrieve it with
* {@link android.content.Intent#getParcelableExtra(String)}.
*/
public static final String EXTRA_NETWORK_REQUEST_NETWORK_CAPABILITIES =
"networkRequestNetworkCapabilities";
/** /**
* Request a network to satisfy a set of {@link NetworkCapabilities}. * Request a network to satisfy a set of {@link NetworkCapabilities}.
* *
* This function behavies identically, but instead of {@link NetworkCallbacks} * This function behavies identically to the callback-equiped version, but instead
* a {@link PendingIntent} is used. This means the request may outlive the * of {@link NetworkCallbackListener} a {@link PendingIntent} is used. This means
* calling application and get called back when a suitable network is found. * the request may outlive the calling application and get called back when a suitable
* network is found.
* <p> * <p>
* The operation is an Intent broadcast that goes to a broadcast receiver that * The operation is an Intent broadcast that goes to a broadcast receiver that
* you registered with {@link Context#registerReceiver} or through the * you registered with {@link Context#registerReceiver} or through the
* &lt;receiver&gt; tag in an AndroidManifest.xml file * &lt;receiver&gt; tag in an AndroidManifest.xml file
* <p> * <p>
* The operation Intent is delivered with two extras, a {@link Network} typed * The operation Intent is delivered with two extras, a {@link Network} typed
* extra called {@link EXTRA_NETWORK_REQUEST_NETWORK} and a {@link NetworkCapabilities} * extra called {@link #EXTRA_NETWORK_REQUEST_NETWORK} and a {@link NetworkCapabilities}
* typed extra called {@link EXTRA_NETWORK_REQUEST_NETWORK_CAPABILTIES} containing * typed extra called {@link #EXTRA_NETWORK_REQUEST_NETWORK_CAPABILITIES} containing
* the original requests parameters. It is important to create a new, * 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 * Intent to reserve the network or it will be released shortly after the Intent
* is processed. * is processed.
* <p> * <p>
* If there is already an request for this Intent registered (with the equality of * 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 * 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}.
* <p> * <p>
* 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 * @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}. * comes from {@link PendingIntent#getBroadcast}.
* @return A {@link NetworkRequest} object identifying the request. * @return A {@link NetworkRequest} object identifying the request.
* @hide
*/ */
public NetworkRequest requestNetwork(NetworkCapabilities need, PendingIntent operation) { public NetworkRequest requestNetwork(NetworkCapabilities need, PendingIntent operation) {
try { try {
@@ -2035,28 +2097,27 @@ public class ConnectivityManager {
* Registers to receive notifications about all networks which satisfy the given * Registers to receive notifications about all networks which satisfy the given
* {@link NetworkCapabilities}. The callbacks will continue to be called until * {@link NetworkCapabilities}. The callbacks will continue to be called until
* either the application exits or the request is released using * either the application exits or the request is released using
* {@link releaseNetworkRequest}. * {@link #releaseNetworkRequest}.
* *
* @param need {@link NetworkCapabilities} required by this request. * @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. * networks change state.
* @return A {@link NetworkRequest} object identifying the request. * @return A {@link NetworkRequest} object identifying the request.
* @hide
*/ */
public NetworkRequest listenForNetwork(NetworkCapabilities need, public NetworkRequest listenForNetwork(NetworkCapabilities need,
NetworkCallbacks networkCallbacks) { NetworkCallbackListener networkCallbackListener) {
return somethingForNetwork(need, networkCallbacks, 0, LISTEN); return somethingForNetwork(need, networkCallbackListener, 0, LISTEN);
} }
/** /**
* Releases a {NetworkRequest} generated either through a {@link requestNetwork} * Releases a {@link NetworkRequest} generated either through a {@link #requestNetwork}
* or a {@link listenForNetwork} call. The {@link NetworkCallbacks} given in the * or a {@link #listenForNetwork} call. The {@link NetworkCallbackListener} given in the
* earlier call may continue receiving calls until the {@link NetworkCallbacks#onReleased} * earlier call may continue receiving calls until the
* function is called, signifiying the end of the request. * {@link NetworkCallbackListener#onReleased} function is called, signifying the end
* of the request.
* *
* @param networkRequest The {@link NetworkRequest} generated by an earlier call to * @param networkRequest The {@link NetworkRequest} generated by an earlier call to
* {@link requestNetwork} or {@link listenForNetwork}. * {@link #requestNetwork} or {@link #listenForNetwork}.
* @hide
*/ */
public void releaseNetworkRequest(NetworkRequest networkRequest) { public void releaseNetworkRequest(NetworkRequest networkRequest) {
if (networkRequest == null) throw new IllegalArgumentException("null NetworkRequest"); if (networkRequest == null) throw new IllegalArgumentException("null NetworkRequest");

3
core/java/android/net/Network.java
View File

@@ -26,11 +26,10 @@ import javax.net.SocketFactory;
/** /**
* Identifies a {@code Network}. This is supplied to applications via * 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}. * {@link ConnectivityManager#requestNetwork} or {@link ConnectivityManager#listenForNetwork}.
* It is used to direct traffic to the given {@code Network}, either on a {@link Socket} basis * 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}. * through a targeted {@link SocketFactory} or process-wide via {@link #bindProcess}.
* @hide
*/ */
public class Network implements Parcelable { public class Network implements Parcelable {

8
core/java/android/net/NetworkRequest.java
View File

@@ -22,18 +22,18 @@ import android.os.Parcelable;
import java.util.concurrent.atomic.AtomicInteger; 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 * This token records the {@link NetworkCapabilities} used to make the request and identifies
* the request. It should be used to release the request via * the request. It should be used to release the request via
* {@link ConnectivityManager.releaseNetworkRequest} when the network is no longer desired. * {@link ConnectivityManager#releaseNetworkRequest} when the network is no longer desired.
* @hide
*/ */
public class NetworkRequest implements Parcelable { public class NetworkRequest implements Parcelable {
/** /**
* The {@link NetworkCapabilities} that define this request. This should not be modified. * The {@link NetworkCapabilities} that define this request. This should not be modified.
* The networkCapabilities of the request are set when * 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. * as a convenient reminder of what was requested.
*/ */
public final NetworkCapabilities networkCapabilities; public final NetworkCapabilities networkCapabilities;