/*
|
* 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.
|
*
|
* <p>A network scorer is any application which:
|
* <ul>
|
* <li>Is granted the {@link permission#SCORE_NETWORKS} permission.
|
* <li>Is granted the {@link permission#ACCESS_COARSE_LOCATION} permission.
|
* <li>Include a Service for the {@link #ACTION_RECOMMEND_NETWORKS} action
|
* protected by the {@link permission#BIND_NETWORK_RECOMMENDATION_SERVICE}
|
* permission.
|
* </ul>
|
*
|
* @hide
|
*/
|
@SystemApi
|
@SystemService(Context.NETWORK_SCORE_SERVICE)
|
public class NetworkScoreManager {
|
/**
|
* Activity action: ask the user to change the active network scorer. This will show a dialog
|
* that asks the user whether they want to replace the current active scorer with the one
|
* specified in {@link #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.
|
*/
|
@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
|
public static final String ACTION_CHANGE_ACTIVE = "android.net.scoring.CHANGE_ACTIVE";
|
|
/**
|
* Extra used with {@link #ACTION_CHANGE_ACTIVE} to specify the new scorer package. Set with
|
* {@link android.content.Intent#putExtra(String, String)}.
|
*/
|
public static final String EXTRA_PACKAGE_NAME = "packageName";
|
|
/**
|
* Broadcast action: new network scores are being requested. This intent will only be delivered
|
* to the current active scorer app. That app is responsible for scoring the networks and
|
* calling {@link #updateScores} when complete. The networks to score are specified in
|
* {@link #EXTRA_NETWORKS_TO_SCORE}, and will generally consist of all networks which have been
|
* configured by the user as well as any open networks.
|
*
|
* <p class="note">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.
|
*
|
* <p>The new scorer will be specified in {@link #EXTRA_NEW_SCORER}.
|
*
|
* <p class="note">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 <code>onBind()</code> 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.
|
* <p>
|
* 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.
|
* <p>
|
* 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.
|
* <p>
|
* 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.
|
*
|
* <p>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 <code>null</code> 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<NetworkScorerAppData> getAllValidScorers() {
|
try {
|
return mService.getAllValidScorers();
|
} catch (RemoteException e) {
|
throw e.rethrowFromSystemServer();
|
}
|
}
|
|
/**
|
* Update network scores.
|
*
|
* <p>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.
|
*
|
* <p>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.
|
*
|
* <p>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.
|
*
|
* <p>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.
|
*
|
* <p>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();
|
}
|
}
|
}
|
