blob: 1a9a637811ac8c993444a9055e675a2d6878b63c [file] [log] [blame]
Jeff Davidsonb51e0a62014-04-09 12:38:15 -07001/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License
15 */
16
17package android.net;
18
19import android.annotation.SdkConstant;
20import android.annotation.SdkConstant.SdkConstantType;
21import android.content.Context;
Jeff Davidson14f1ec02014-04-29 11:58:26 -070022import android.content.Intent;
Jeff Davidsonc7415532014-06-23 18:15:34 -070023import android.net.NetworkScorerAppManager.NetworkScorerAppData;
Jeff Davidson6a4b2202014-04-16 17:29:40 -070024import android.os.IBinder;
25import android.os.RemoteException;
26import android.os.ServiceManager;
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070027
28/**
29 * Class that manages communication between network subsystems and a network scorer.
30 *
31 * <p>You can get an instance of this class by calling
32 * {@link android.content.Context#getSystemService(String)}:
33 *
34 * <pre>NetworkScoreManager manager =
35 * (NetworkScoreManager) getSystemService(Context.NETWORK_SCORE_SERVICE)</pre>
36 *
37 * <p>A network scorer is any application which:
38 * <ul>
39 * <li>Declares the {@link android.Manifest.permission#SCORE_NETWORKS} permission.
40 * <li>Includes a receiver for {@link #ACTION_SCORE_NETWORKS} guarded by the
41 * {@link android.Manifest.permission#BROADCAST_SCORE_NETWORKS} permission which scores networks
Jeff Davidsonc7415532014-06-23 18:15:34 -070042 * and (eventually) calls {@link #updateScores} with the results. If this receiver specifies an
43 * android:label attribute, this label will be used when referring to the application throughout
44 * system settings; otherwise, the application label will be used.
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070045 * </ul>
46 *
Jeff Davidsonee2a1212014-04-17 12:19:23 -070047 * <p>The system keeps track of an active scorer application; at any time, only this application
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070048 * will receive {@link #ACTION_SCORE_NETWORKS} broadcasts and will be permitted to call
Jeff Davidsonee2a1212014-04-17 12:19:23 -070049 * {@link #updateScores}. Applications may determine the current active scorer with
50 * {@link #getActiveScorerPackage()} and request to change the active scorer by sending an
51 * {@link #ACTION_CHANGE_ACTIVE} broadcast with another scorer.
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070052 *
53 * @hide
54 */
55public class NetworkScoreManager {
56 /**
Jeff Davidsonee2a1212014-04-17 12:19:23 -070057 * Activity action: ask the user to change the active network scorer. This will show a dialog
58 * that asks the user whether they want to replace the current active scorer with the one
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070059 * specified in {@link #EXTRA_PACKAGE_NAME}. The activity will finish with RESULT_OK if the
Jeff Davidsonee2a1212014-04-17 12:19:23 -070060 * active scorer was changed or RESULT_CANCELED if it failed for any reason.
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070061 */
62 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
Jeff Davidsonee2a1212014-04-17 12:19:23 -070063 public static final String ACTION_CHANGE_ACTIVE = "android.net.scoring.CHANGE_ACTIVE";
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070064
65 /**
Jeff Davidsonee2a1212014-04-17 12:19:23 -070066 * Extra used with {@link #ACTION_CHANGE_ACTIVE} to specify the new scorer package. Set with
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070067 * {@link android.content.Intent#putExtra(String, String)}.
68 */
69 public static final String EXTRA_PACKAGE_NAME = "packageName";
70
71 /**
72 * Broadcast action: new network scores are being requested. This intent will only be delivered
Jeff Davidsonee2a1212014-04-17 12:19:23 -070073 * to the current active scorer app. That app is responsible for scoring the networks and
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070074 * calling {@link #updateScores} when complete. The networks to score are specified in
75 * {@link #EXTRA_NETWORKS_TO_SCORE}, and will generally consist of all networks which have been
76 * configured by the user as well as any open networks.
77 *
78 * <p class="note">This is a protected intent that can only be sent by the system.
79 */
80 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
81 public static final String ACTION_SCORE_NETWORKS = "android.net.scoring.SCORE_NETWORKS";
82
83 /**
84 * Extra used with {@link #ACTION_SCORE_NETWORKS} to specify the networks to be scored, as an
85 * array of {@link NetworkKey}s. Can be obtained with
86 * {@link android.content.Intent#getParcelableArrayExtra(String)}}.
87 */
88 public static final String EXTRA_NETWORKS_TO_SCORE = "networksToScore";
89
90 private final Context mContext;
Jeff Davidson6a4b2202014-04-16 17:29:40 -070091 private final INetworkScoreService mService;
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070092
93 /** @hide */
94 public NetworkScoreManager(Context context) {
95 mContext = context;
Jeff Davidson6a4b2202014-04-16 17:29:40 -070096 IBinder iBinder = ServiceManager.getService(Context.NETWORK_SCORE_SERVICE);
97 mService = INetworkScoreService.Stub.asInterface(iBinder);
Jeff Davidsonb51e0a62014-04-09 12:38:15 -070098 }
99
100 /**
Jeff Davidson6a4b2202014-04-16 17:29:40 -0700101 * Obtain the package name of the current active network scorer.
Jeff Davidsonb51e0a62014-04-09 12:38:15 -0700102 *
Jeff Davidson6a4b2202014-04-16 17:29:40 -0700103 * <p>At any time, only one scorer application will receive {@link #ACTION_SCORE_NETWORKS}
Jeff Davidsonb51e0a62014-04-09 12:38:15 -0700104 * broadcasts and be allowed to call {@link #updateScores}. Applications may use this method to
105 * determine the current scorer and offer the user the ability to select a different scorer via
Jeff Davidsonee2a1212014-04-17 12:19:23 -0700106 * the {@link #ACTION_CHANGE_ACTIVE} intent.
Jeff Davidson6a4b2202014-04-16 17:29:40 -0700107 * @return the full package name of the current active scorer, or null if there is no active
Jeff Davidson14f1ec02014-04-29 11:58:26 -0700108 * scorer.
Jeff Davidsonb51e0a62014-04-09 12:38:15 -0700109 */
Jeff Davidson6a4b2202014-04-16 17:29:40 -0700110 public String getActiveScorerPackage() {
Jeff Davidsonc7415532014-06-23 18:15:34 -0700111 NetworkScorerAppData app = NetworkScorerAppManager.getActiveScorer(mContext);
112 if (app == null) {
113 return null;
114 }
115 return app.mPackageName;
Jeff Davidsonb51e0a62014-04-09 12:38:15 -0700116 }
117
118 /**
119 * Update network scores.
120 *
Jeff Davidson6a4b2202014-04-16 17:29:40 -0700121 * <p>This may be called at any time to re-score active networks. Scores will generally be
122 * updated quickly, but if this method is called too frequently, the scores may be held and
123 * applied at a later time.
Jeff Davidsonb51e0a62014-04-09 12:38:15 -0700124 *
125 * @param networks the networks which have been scored by the scorer.
Jeff Davidson6a4b2202014-04-16 17:29:40 -0700126 * @return whether the update was successful.
127 * @throws SecurityException if the caller is not the active scorer.
Jeff Davidsonb51e0a62014-04-09 12:38:15 -0700128 */
Jeff Davidson6a4b2202014-04-16 17:29:40 -0700129 public boolean updateScores(ScoredNetwork[] networks) throws SecurityException {
130 try {
131 return mService.updateScores(networks);
132 } catch (RemoteException e) {
133 return false;
134 }
135 }
136
137 /**
138 * Clear network scores.
139 *
140 * <p>Should be called when all scores need to be invalidated, i.e. because the scoring
141 * algorithm has changed and old scores can no longer be compared to future scores.
142 *
143 * <p>Note that scores will be cleared automatically when the active scorer changes, as scores
144 * from one scorer cannot be compared to those from another scorer.
145 *
146 * @return whether the clear was successful.
147 * @throws SecurityException if the caller is not the active scorer or privileged.
148 */
149 public boolean clearScores() throws SecurityException {
150 try {
151 return mService.clearScores();
152 } catch (RemoteException e) {
153 return false;
154 }
155 }
156
157 /**
158 * Set the active scorer to a new package and clear existing scores.
159 *
160 * @return true if the operation succeeded, or false if the new package is not a valid scorer.
161 * @throws SecurityException if the caller does not hold the
Jeff Davidson14f1ec02014-04-29 11:58:26 -0700162 * {@link android.Manifest.permission#BROADCAST_SCORE_NETWORKS} permission indicating
163 * that it can manage scorer applications.
Jeff Davidson6a4b2202014-04-16 17:29:40 -0700164 * @hide
165 */
166 public boolean setActiveScorer(String packageName) throws SecurityException {
167 try {
168 return mService.setActiveScorer(packageName);
169 } catch (RemoteException e) {
170 return false;
171 }
Jeff Davidsonb51e0a62014-04-09 12:38:15 -0700172 }
Jeff Davidson14f1ec02014-04-29 11:58:26 -0700173
174 /**
175 * Request scoring for networks.
176 *
177 * <p>Note that this is just a helper method to assemble the broadcast, and will run in the
178 * calling process.
179 *
180 * @return true if the broadcast was sent, or false if there is no active scorer.
181 * @throws SecurityException if the caller does not hold the
182 * {@link android.Manifest.permission#BROADCAST_SCORE_NETWORKS} permission.
183 * @hide
184 */
185 public boolean requestScores(NetworkKey[] networks) throws SecurityException {
186 String activeScorer = getActiveScorerPackage();
187 if (activeScorer == null) {
188 return false;
189 }
190 Intent intent = new Intent(ACTION_SCORE_NETWORKS);
191 intent.setPackage(activeScorer);
192 intent.putExtra(EXTRA_NETWORKS_TO_SCORE, networks);
193 mContext.sendBroadcast(intent);
194 return true;
195 }
196
197 /**
198 * Register a network score cache.
199 *
200 * @param networkType the type of network this cache can handle. See {@link NetworkKey#type}.
201 * @param scoreCache implementation of {@link INetworkScoreCache} to store the scores.
202 * @throws SecurityException if the caller does not hold the
203 * {@link android.Manifest.permission#BROADCAST_SCORE_NETWORKS} permission.
204 * @throws IllegalArgumentException if a score cache is already registered for this type.
205 * @hide
206 */
207 public void registerNetworkScoreCache(int networkType, INetworkScoreCache scoreCache) {
208 try {
209 mService.registerNetworkScoreCache(networkType, scoreCache);
210 } catch (RemoteException e) {
211 }
212 }
Jeff Davidsonb51e0a62014-04-09 12:38:15 -0700213}