/* * Copyright (C) 2014 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License */ package android.net; import android.Manifest.permission; import android.annotation.IntDef; import android.annotation.Nullable; import android.annotation.RequiresPermission; import android.annotation.SdkConstant; import android.annotation.SdkConstant.SdkConstantType; import android.annotation.SystemApi; import android.annotation.SystemService; import android.content.Context; import android.os.RemoteException; import android.os.ServiceManager; import android.os.ServiceManager.ServiceNotFoundException; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.util.List; /** * Class that manages communication between network subsystems and a network scorer. * *
A network scorer is any application which: *
This is a protected intent that can only be sent by the system. */ @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) public static final String ACTION_SCORE_NETWORKS = "android.net.scoring.SCORE_NETWORKS"; /** * Extra used with {@link #ACTION_SCORE_NETWORKS} to specify the networks to be scored, as an * array of {@link NetworkKey}s. Can be obtained with * {@link android.content.Intent#getParcelableArrayExtra(String)}}. */ public static final String EXTRA_NETWORKS_TO_SCORE = "networksToScore"; /** * Activity action: launch an activity for configuring a provider for the feature that connects * and secures open wifi networks available before enabling it. Applications that enable this * feature must provide an activity for this action. The framework will launch this activity * which must return RESULT_OK if the feature should be enabled. */ @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) public static final String ACTION_CUSTOM_ENABLE = "android.net.scoring.CUSTOM_ENABLE"; /** * Meta-data specified on a {@link NetworkRecommendationProvider} that provides a user-visible * label of the recommendation service. * @hide */ public static final String RECOMMENDATION_SERVICE_LABEL_META_DATA = "android.net.scoring.recommendation_service_label"; /** * Meta-data specified on a {@link NetworkRecommendationProvider} that specified the package * name of the application that connects and secures open wifi networks automatically. The * specified package must provide an Activity for {@link #ACTION_CUSTOM_ENABLE}. * @hide */ public static final String USE_OPEN_WIFI_PACKAGE_META_DATA = "android.net.wifi.use_open_wifi_package"; /** * Meta-data specified on a {@link NetworkRecommendationProvider} that specifies the * {@link android.app.NotificationChannel} ID used to post open network notifications. * @hide */ public static final String NETWORK_AVAILABLE_NOTIFICATION_CHANNEL_ID_META_DATA = "android.net.wifi.notification_channel_id_network_available"; /** * Broadcast action: the active scorer has been changed. Scorer apps may listen to this to * perform initialization once selected as the active scorer, or clean up unneeded resources * if another scorer has been selected. This is an explicit broadcast only sent to the * previous scorer and new scorer. Note that it is unnecessary to clear existing scores as * this is handled by the system. * *
The new scorer will be specified in {@link #EXTRA_NEW_SCORER}. * *
This is a protected intent that can only be sent by the system.
*/
@SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
public static final String ACTION_SCORER_CHANGED = "android.net.scoring.SCORER_CHANGED";
/**
* Service action: Used to discover and bind to a network recommendation provider.
* Implementations should return {@link NetworkRecommendationProvider#getBinder()} from
* their onBind()
method.
*/
@SdkConstant(SdkConstantType.SERVICE_ACTION)
public static final String ACTION_RECOMMEND_NETWORKS = "android.net.action.RECOMMEND_NETWORKS";
/**
* Extra used with {@link #ACTION_SCORER_CHANGED} to specify the newly selected scorer's package
* name. Will be null if scoring was disabled. Can be obtained with
* {@link android.content.Intent#getStringExtra(String)}.
*/
public static final String EXTRA_NEW_SCORER = "newScorer";
/** @hide */
@IntDef({CACHE_FILTER_NONE, CACHE_FILTER_CURRENT_NETWORK, CACHE_FILTER_SCAN_RESULTS})
@Retention(RetentionPolicy.SOURCE)
public @interface CacheUpdateFilter {}
/**
* Do not filter updates sent to the cache.
* @hide
*/
public static final int CACHE_FILTER_NONE = 0;
/**
* Only send cache updates when the network matches the connected network.
* @hide
*/
public static final int CACHE_FILTER_CURRENT_NETWORK = 1;
/**
* Only send cache updates when the network is part of the current scan result set.
* @hide
*/
public static final int CACHE_FILTER_SCAN_RESULTS = 2;
/** @hide */
@IntDef({RECOMMENDATIONS_ENABLED_FORCED_OFF, RECOMMENDATIONS_ENABLED_OFF,
RECOMMENDATIONS_ENABLED_ON})
@Retention(RetentionPolicy.SOURCE)
public @interface RecommendationsEnabledSetting {}
/**
* Recommendations have been forced off.
*
* This value is never set by any of the NetworkScore classes, it must be set via other means. * This state is also "sticky" and we won't transition out of this state once entered. To move * to a different state this value has to be explicitly set to a different value via * other means. * @hide */ public static final int RECOMMENDATIONS_ENABLED_FORCED_OFF = -1; /** * Recommendations are not enabled. *
* This is a transient state that can be entered when the default recommendation app is enabled * but no longer valid. This state will transition to RECOMMENDATIONS_ENABLED_ON when a valid * recommendation app is enabled. * @hide */ public static final int RECOMMENDATIONS_ENABLED_OFF = 0; /** * Recommendations are enabled. *
* This is a transient state that means a valid recommendation app is active. This state will * transition to RECOMMENDATIONS_ENABLED_OFF if the current and default recommendation apps * become invalid. * @hide */ public static final int RECOMMENDATIONS_ENABLED_ON = 1; private final Context mContext; private final INetworkScoreService mService; /** @hide */ public NetworkScoreManager(Context context) throws ServiceNotFoundException { mContext = context; mService = INetworkScoreService.Stub .asInterface(ServiceManager.getServiceOrThrow(Context.NETWORK_SCORE_SERVICE)); } /** * Obtain the package name of the current active network scorer. * *
At any time, only one scorer application will receive {@link #ACTION_SCORE_NETWORKS}
* broadcasts and be allowed to call {@link #updateScores}. Applications may use this method to
* determine the current scorer and offer the user the ability to select a different scorer via
* the {@link #ACTION_CHANGE_ACTIVE} intent.
* @return the full package name of the current active scorer, or null if there is no active
* scorer.
* @throws SecurityException if the caller doesn't hold either {@link permission#SCORE_NETWORKS}
* or {@link permission#REQUEST_NETWORK_SCORES} permissions.
*/
@RequiresPermission(anyOf = {android.Manifest.permission.SCORE_NETWORKS,
android.Manifest.permission.REQUEST_NETWORK_SCORES})
public String getActiveScorerPackage() {
try {
return mService.getActiveScorerPackage();
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Returns metadata about the active scorer or 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.
*
* @param networks the networks which have been scored by the scorer.
* @return whether the update was successful.
* @throws SecurityException if the caller is not the active scorer.
*/
@RequiresPermission(android.Manifest.permission.SCORE_NETWORKS)
public boolean updateScores(ScoredNetwork[] networks) throws SecurityException {
try {
return mService.updateScores(networks);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Clear network scores.
*
* 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.
*
* @return whether the clear was successful.
* @throws SecurityException if the caller is not the active scorer or if the caller doesn't
* hold the {@link permission#REQUEST_NETWORK_SCORES} permission.
*/
@RequiresPermission(anyOf = {android.Manifest.permission.SCORE_NETWORKS,
android.Manifest.permission.REQUEST_NETWORK_SCORES})
public boolean clearScores() throws SecurityException {
try {
return mService.clearScores();
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Set the active scorer to a new package and clear existing scores.
*
* Should never be called directly without obtaining user consent. This can be done by using
* the {@link #ACTION_CHANGE_ACTIVE} broadcast, or using a custom configuration activity.
*
* @return true if the operation succeeded, or false if the new package is not a valid scorer.
* @throws SecurityException if the caller doesn't hold either {@link permission#SCORE_NETWORKS}
* or {@link permission#REQUEST_NETWORK_SCORES} permissions.
* @hide
*/
@SystemApi
@RequiresPermission(anyOf = {android.Manifest.permission.SCORE_NETWORKS,
android.Manifest.permission.REQUEST_NETWORK_SCORES})
public boolean setActiveScorer(String packageName) throws SecurityException {
try {
return mService.setActiveScorer(packageName);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Turn off network scoring.
*
* May only be called by the current scorer app, or the system.
*
* @throws SecurityException if the caller is not the active scorer or if the caller doesn't
* hold the {@link permission#REQUEST_NETWORK_SCORES} permission.
*/
@RequiresPermission(anyOf = {android.Manifest.permission.SCORE_NETWORKS,
android.Manifest.permission.REQUEST_NETWORK_SCORES})
public void disableScoring() throws SecurityException {
try {
mService.disableScoring();
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Request scoring for networks.
*
* @return true if the broadcast was sent, or false if there is no active scorer.
* @throws SecurityException if the caller does not hold the
* {@link permission#REQUEST_NETWORK_SCORES} permission.
* @hide
*/
@RequiresPermission(android.Manifest.permission.REQUEST_NETWORK_SCORES)
public boolean requestScores(NetworkKey[] networks) throws SecurityException {
try {
return mService.requestScores(networks);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Register a network score cache.
*
* @param networkType the type of network this cache can handle. See {@link NetworkKey#type}.
* @param scoreCache implementation of {@link INetworkScoreCache} to store the scores.
* @throws SecurityException if the caller does not hold the
* {@link permission#REQUEST_NETWORK_SCORES} permission.
* @throws IllegalArgumentException if a score cache is already registered for this type.
* @deprecated equivalent to registering for cache updates with CACHE_FILTER_NONE.
* @hide
*/
@RequiresPermission(android.Manifest.permission.REQUEST_NETWORK_SCORES)
@Deprecated // migrate to registerNetworkScoreCache(int, INetworkScoreCache, int)
public void registerNetworkScoreCache(int networkType, INetworkScoreCache scoreCache) {
registerNetworkScoreCache(networkType, scoreCache, CACHE_FILTER_NONE);
}
/**
* Register a network score cache.
*
* @param networkType the type of network this cache can handle. See {@link NetworkKey#type}
* @param scoreCache implementation of {@link INetworkScoreCache} to store the scores
* @param filterType the {@link CacheUpdateFilter} to apply
* @throws SecurityException if the caller does not hold the
* {@link permission#REQUEST_NETWORK_SCORES} permission.
* @throws IllegalArgumentException if a score cache is already registered for this type.
* @hide
*/
@RequiresPermission(android.Manifest.permission.REQUEST_NETWORK_SCORES)
public void registerNetworkScoreCache(int networkType, INetworkScoreCache scoreCache,
@CacheUpdateFilter int filterType) {
try {
mService.registerNetworkScoreCache(networkType, scoreCache, filterType);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Unregister a network score cache.
*
* @param networkType the type of network this cache can handle. See {@link NetworkKey#type}.
* @param scoreCache implementation of {@link INetworkScoreCache} to store the scores.
* @throws SecurityException if the caller does not hold the
* {@link permission#REQUEST_NETWORK_SCORES} permission.
* @throws IllegalArgumentException if a score cache is already registered for this type.
* @hide
*/
@RequiresPermission(android.Manifest.permission.REQUEST_NETWORK_SCORES)
public void unregisterNetworkScoreCache(int networkType, INetworkScoreCache scoreCache) {
try {
mService.unregisterNetworkScoreCache(networkType, scoreCache);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Determine whether the application with the given UID is the enabled scorer.
*
* @param callingUid the UID to check
* @return true if the provided UID is the active scorer, false otherwise.
* @throws SecurityException if the caller does not hold the
* {@link permission#REQUEST_NETWORK_SCORES} permission.
* @hide
*/
@RequiresPermission(android.Manifest.permission.REQUEST_NETWORK_SCORES)
public boolean isCallerActiveScorer(int callingUid) {
try {
return mService.isCallerActiveScorer(callingUid);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
}
null
if there is no active scorer.
*
* @throws SecurityException if the caller does not hold the
* {@link permission#REQUEST_NETWORK_SCORES} permission.
* @hide
*/
@Nullable
@RequiresPermission(android.Manifest.permission.REQUEST_NETWORK_SCORES)
public NetworkScorerAppData getActiveScorer() {
try {
return mService.getActiveScorer();
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Returns the list of available scorer apps. The list will be empty if there are
* no valid scorers.
*
* @throws SecurityException if the caller does not hold the
* {@link permission#REQUEST_NETWORK_SCORES} permission.
* @hide
*/
@RequiresPermission(android.Manifest.permission.REQUEST_NETWORK_SCORES)
public List