File Doc Category Size Date Package
NetworkFactory.java API Doc Android 5.1 API 10737 Thu Mar 12 22:22:10 GMT 2015 android.net

NetworkFactory

java.lang.Object
- android.os.Handler

public class NetworkFactory extends android.os.Handler

A NetworkFactory is an entity that creates NetworkAgent objects. The bearers register with ConnectivityService using {@link #register} and their factory will start receiving scored NetworkRequests. NetworkRequests can be filtered 3 ways: by NetworkCapabilities, by score and more complexly by overridden function. All of these can be dynamic - changing NetworkCapabilities or score forces re-evaluation of all current requests. If any requests pass the filter some overrideable functions will be called. If the bearer only cares about very simple start/stopNetwork callbacks, those functions can be overridden. If the bearer needs more interaction, it can override addNetworkRequest and removeNetworkRequest which will give it each request that passes their current filters.

hide

Fields Summary
private static final boolean
DBG
private static final boolean
VDBG
private static final int
BASE
public static final int
CMD_REQUEST_NETWORK
Pass a network request to the bearer. If the bearer believes it can satisfy the request it should connect to the network and create a NetworkAgent. Once the NetworkAgent is fully functional it will register itself with ConnectivityService using registerNetworkAgent. If the bearer cannot immediately satisfy the request (no network, user disabled the radio, lower-scored network) it should remember any NetworkRequests it may be able to satisfy in the future. It may disregard any that it will never be able to service, for example those requiring a different bearer. msg.obj = NetworkRequest msg.arg1 = score - the score of the any network currently satisfying this request. If this bearer knows in advance it cannot exceed this score it should not try to connect, holding the request for the future. Note that subsequent events may give a different (lower or higher) score for this request, transmitted to each NetworkFactory through additional CMD_REQUEST_NETWORK msgs with the same NetworkRequest but an updated score. Also, network conditions may change for this bearer allowing for a better score in the future.
public static final int
CMD_CANCEL_REQUEST
Cancel a network request msg.obj = NetworkRequest
private static final int
CMD_SET_SCORE
Internally used to set our best-guess score. msg.arg1 = new score
private static final int
CMD_SET_FILTER
Internally used to set our current filter for coarse bandwidth changes with technology changes. msg.obj = new filter
private final android.content.Context
mContext
private final String
LOG_TAG
private final android.util.SparseArray
mNetworkRequests
private int
mScore
private NetworkCapabilities
mCapabilityFilter
private int
mRefCount
private android.os.Messenger
mMessenger
Constructors Summary
public NetworkFactory(android.os.Looper looper, android.content.Context context, String logTag, NetworkCapabilities filter)
super(looper); LOG_TAG = logTag; mContext = context; mCapabilityFilter = filter;
Methods Summary
public boolean acceptRequest(NetworkRequest request, int score)
Overridable function to provide complex filtering. Called for every request every time a new NetworkRequest is seen and whenever the filterScore or filterNetworkCapabilities change. acceptRequest can be overriden to provide complex filter behavior for the incoming requests For output, this class will call {@link #needNetworkFor} and {@link #releaseNetworkFor} for every request that passes the filters. If you don't need to see every request, you can leave the base implementations of those two functions and instead override {@link #startNetwork} and {@link #stopNetwork}. If you want to see every score fluctuation on every request, set your score filter to a very high number and watch {@link #needNetworkFor}.
return
{@code true} to accept the request.
return true;
public void addNetworkRequest(NetworkRequest networkRequest, int score)
sendMessage(obtainMessage(CMD_REQUEST_NETWORK, new NetworkRequestInfo(networkRequest, score)));
private void evalRequest(android.net.NetworkFactory$NetworkRequestInfo n)
if (VDBG) log("evalRequest"); if (n.requested == false && n.score < mScore && n.request.networkCapabilities.satisfiedByNetworkCapabilities( mCapabilityFilter) && acceptRequest(n.request, n.score)) { if (VDBG) log(" needNetworkFor"); needNetworkFor(n.request, n.score); n.requested = true; } else if (n.requested == true && (n.score > mScore || n.request.networkCapabilities.satisfiedByNetworkCapabilities( mCapabilityFilter) == false || acceptRequest(n.request, n.score) == false)) { if (VDBG) log(" releaseNetworkFor"); releaseNetworkFor(n.request); n.requested = false; } else { if (VDBG) log(" done"); }
private void evalRequests()
for (int i = 0; i < mNetworkRequests.size(); i++) { NetworkRequestInfo n = mNetworkRequests.valueAt(i); evalRequest(n); }
private void handleAddRequest(NetworkRequest request, int score)
NetworkRequestInfo n = mNetworkRequests.get(request.requestId); if (n == null) { if (DBG) log("got request " + request + " with score " + score); n = new NetworkRequestInfo(request, score); mNetworkRequests.put(n.request.requestId, n); } else { if (VDBG) log("new score " + score + " for exisiting request " + request); n.score = score; } if (VDBG) log(" my score=" + mScore + ", my filter=" + mCapabilityFilter); evalRequest(n);
public void handleMessage(android.os.Message msg)
switch (msg.what) { case CMD_REQUEST_NETWORK: { handleAddRequest((NetworkRequest)msg.obj, msg.arg1); break; } case CMD_CANCEL_REQUEST: { handleRemoveRequest((NetworkRequest) msg.obj); break; } case CMD_SET_SCORE: { handleSetScore(msg.arg1); break; } case CMD_SET_FILTER: { handleSetFilter((NetworkCapabilities) msg.obj); break; } }
private void handleRemoveRequest(NetworkRequest request)
NetworkRequestInfo n = mNetworkRequests.get(request.requestId); if (n != null && n.requested) { mNetworkRequests.remove(request.requestId); releaseNetworkFor(n.request); }
private void handleSetFilter(NetworkCapabilities netCap)
mCapabilityFilter = netCap; evalRequests();
private void handleSetScore(int score)
mScore = score; evalRequests();
protected void log(java.lang.String s)
Log.d(LOG_TAG, s);
protected void needNetworkFor(NetworkRequest networkRequest, int score)
if (++mRefCount == 1) startNetwork();
public void register()
if (DBG) log("Registering NetworkFactory"); if (mMessenger == null) { mMessenger = new Messenger(this); ConnectivityManager.from(mContext).registerNetworkFactory(mMessenger, LOG_TAG); }
protected void releaseNetworkFor(NetworkRequest networkRequest)
if (--mRefCount == 0) stopNetwork();
public void removeNetworkRequest(NetworkRequest networkRequest)
sendMessage(obtainMessage(CMD_CANCEL_REQUEST, networkRequest));
public void setCapabilityFilter(NetworkCapabilities netCap)
sendMessage(obtainMessage(CMD_SET_FILTER, new NetworkCapabilities(netCap)));
public void setScoreFilter(int score)
sendMessage(obtainMessage(CMD_SET_SCORE, score, 0));
protected void startNetwork()

protected void stopNetwork()

public java.lang.String toString()
StringBuilder sb = new StringBuilder("{").append(LOG_TAG).append(" - ScoreFilter="). append(mScore).append(", Filter=").append(mCapabilityFilter).append(", requests="). append(mNetworkRequests.size()).append("}"); return sb.toString();
public void unregister()
if (DBG) log("Unregistering NetworkFactory"); if (mMessenger != null) { ConnectivityManager.from(mContext).unregisterNetworkFactory(mMessenger); mMessenger = null; }