public class NetworkScoreManager extends Object
You can get an instance of this class by calling
Context.getSystemService(String)
:
NetworkScoreManager manager = (NetworkScoreManager) getSystemService(Context.NETWORK_SCORE_SERVICE)
A network scorer is any application which:
android.Manifest.permission#SCORE_NETWORKS
permission.
ACTION_SCORE_NETWORKS
guarded by the
android.Manifest.permission#BROADCAST_NETWORK_PRIVILEGED
permission which scores
networks and (eventually) calls updateScores(android.net.ScoredNetwork[])
with the results. If this receiver
specifies an android:label attribute, this label will be used when referring to the
application throughout system settings; otherwise, the application label will be used.
The system keeps track of an active scorer application; at any time, only this application
will receive ACTION_SCORE_NETWORKS
broadcasts and will be permitted to call
updateScores(android.net.ScoredNetwork[])
. Applications may determine the current active scorer with
getActiveScorerPackage()
and request to change the active scorer by sending an
ACTION_CHANGE_ACTIVE
broadcast with another scorer.
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_CHANGE_ACTIVE
Activity action: ask the user to change the active network scorer.
|
static String |
ACTION_CUSTOM_ENABLE
Activity action: launch a custom activity for configuring a scorer before enabling it.
|
static String |
ACTION_SCORE_NETWORKS
Broadcast action: new network scores are being requested.
|
static String |
ACTION_SCORER_CHANGED
Broadcast action: the active scorer has been changed.
|
static String |
EXTRA_NETWORKS_TO_SCORE
Extra used with
ACTION_SCORE_NETWORKS to specify the networks to be scored, as an
array of NetworkKey s. |
static String |
EXTRA_NEW_SCORER
Extra used with
ACTION_SCORER_CHANGED to specify the newly selected scorer's package
name. |
static String |
EXTRA_PACKAGE_NAME
Extra used with
ACTION_CHANGE_ACTIVE to specify the new scorer package. |
Constructor and Description |
---|
NetworkScoreManager(Context context) |
Modifier and Type | Method and Description |
---|---|
boolean |
clearScores()
Clear network scores.
|
void |
disableScoring()
Turn off network scoring.
|
String |
getActiveScorerPackage()
Obtain the package name of the current active network scorer.
|
void |
registerNetworkScoreCache(int networkType,
INetworkScoreCache scoreCache)
Register a network score cache.
|
boolean |
requestScores(NetworkKey[] networks)
Request scoring for networks.
|
boolean |
setActiveScorer(String packageName)
Set the active scorer to a new package and clear existing scores.
|
boolean |
updateScores(ScoredNetwork[] networks)
Update network scores.
|
public static final String ACTION_CHANGE_ACTIVE
EXTRA_PACKAGE_NAME
. The activity will finish with RESULT_OK if the
active scorer was changed or RESULT_CANCELED if it failed for any reason.public static final String EXTRA_PACKAGE_NAME
ACTION_CHANGE_ACTIVE
to specify the new scorer package. Set with
Intent.putExtra(String, String)
.public static final String ACTION_SCORE_NETWORKS
updateScores(android.net.ScoredNetwork[])
when complete. The networks to score are specified in
EXTRA_NETWORKS_TO_SCORE
, and will generally consist of all networks which have been
configured by the user as well as any open networks.
This is a protected intent that can only be sent by the system.
public static final String EXTRA_NETWORKS_TO_SCORE
ACTION_SCORE_NETWORKS
to specify the networks to be scored, as an
array of NetworkKey
s. Can be obtained with
Intent.getParcelableArrayExtra(String)
}.public static final String ACTION_CUSTOM_ENABLE
If no activity is included in a scorer which implements this action, the system dialog for selecting a scorer will be shown instead.
public static final String ACTION_SCORER_CHANGED
The new scorer will be specified in EXTRA_NEW_SCORER
.
This is a protected intent that can only be sent by the system.
public static final String EXTRA_NEW_SCORER
ACTION_SCORER_CHANGED
to specify the newly selected scorer's package
name. Will be null if scoring was disabled. Can be obtained with
Intent.getStringExtra(String)
.public NetworkScoreManager(Context context)
public String getActiveScorerPackage()
At any time, only one scorer application will receive ACTION_SCORE_NETWORKS
broadcasts and be allowed to call updateScores(android.net.ScoredNetwork[])
. Applications may use this method to
determine the current scorer and offer the user the ability to select a different scorer via
the ACTION_CHANGE_ACTIVE
intent.
public boolean updateScores(ScoredNetwork[] networks) throws SecurityException
This may be called at any time to re-score active networks. Scores will generally be updated quickly, but if this method is called too frequently, the scores may be held and applied at a later time.
networks
- the networks which have been scored by the scorer.SecurityException
- if the caller is not the active scorer.public boolean clearScores() throws SecurityException
Should be called when all scores need to be invalidated, i.e. because the scoring algorithm has changed and old scores can no longer be compared to future scores.
Note that scores will be cleared automatically when the active scorer changes, as scores from one scorer cannot be compared to those from another scorer.
SecurityException
- if the caller is not the active scorer or privileged.public boolean setActiveScorer(String packageName) throws SecurityException
Should never be called directly without obtaining user consent. This can be done by using
the ACTION_CHANGE_ACTIVE
broadcast, or using a custom configuration activity.
SecurityException
- if the caller does not hold the
android.Manifest.permission#SCORE_NETWORKS
permission.public void disableScoring() throws SecurityException
May only be called by the current scorer app, or the system.
SecurityException
- if the caller is neither the active scorer nor the system.public boolean requestScores(NetworkKey[] networks) throws SecurityException
Note that this is just a helper method to assemble the broadcast, and will run in the calling process.
SecurityException
- if the caller does not hold the
android.Manifest.permission#BROADCAST_NETWORK_PRIVILEGED
permission.public void registerNetworkScoreCache(int networkType, INetworkScoreCache scoreCache)
networkType
- the type of network this cache can handle. See NetworkKey.type
.scoreCache
- implementation of INetworkScoreCache
to store the scores.SecurityException
- if the caller does not hold the
android.Manifest.permission#BROADCAST_NETWORK_PRIVILEGED
permission.IllegalArgumentException
- if a score cache is already registered for this type.