1 /**
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 
17 package android.net;
18 
19 import android.net.INetworkScoreCache;
20 import android.net.NetworkKey;
21 import android.net.NetworkScorerAppData;
22 import android.net.ScoredNetwork;
23 
24 /**
25  * A service for updating network scores from a network scorer application.
26  * @hide
27  */
28 interface INetworkScoreService
29 {
30     /**
31      * Update scores.
32      * @return whether the update was successful.
33      * @throws SecurityException if the caller is not the current active scorer.
34      */
updateScores(in ScoredNetwork[] networks)35     boolean updateScores(in ScoredNetwork[] networks);
36 
37     /**
38      * Clear all scores.
39      * @return whether the clear was successful.
40      * @throws SecurityException if the caller is neither the current active scorer nor the system.
41      */
clearScores()42     boolean clearScores();
43 
44     /**
45      * Set the active scorer and clear existing scores.
46      * @param packageName the package name of the new scorer to use.
47      * @return true if the operation succeeded, or false if the new package is not a valid scorer.
48      * @throws SecurityException if the caller is not the system or a network scorer.
49      */
setActiveScorer(in String packageName)50     boolean setActiveScorer(in String packageName);
51 
52     /**
53      * Disable the current active scorer and clear existing scores.
54      * @throws SecurityException if the caller is not the current scorer or the system.
55      */
disableScoring()56     void disableScoring();
57 
58     /**
59      * Register a cache to receive scoring updates.
60      *
61      * @param networkType the type of network this cache can handle. See {@link NetworkKey#type}
62      * @param scoreCache implementation of {@link INetworkScoreCache} to store the scores
63      * @param filterType the {@link CacheUpdateFilter} to apply
64      * @throws SecurityException if the caller is not the system
65      * @throws IllegalArgumentException if a score cache is already registed for this type
66      * @hide
67      */
registerNetworkScoreCache(int networkType, INetworkScoreCache scoreCache, int filterType)68     void registerNetworkScoreCache(int networkType, INetworkScoreCache scoreCache, int filterType);
69 
70     /**
71      * Unregister a cache to receive scoring updates.
72      *
73      * @param networkType the type of network this cache can handle. See {@link NetworkKey#type}.
74      * @param scoreCache implementation of {@link INetworkScoreCache} to store the scores.
75      * @throws SecurityException if the caller is not the system.
76      * @hide
77      */
unregisterNetworkScoreCache(int networkType, INetworkScoreCache scoreCache)78     void unregisterNetworkScoreCache(int networkType, INetworkScoreCache scoreCache);
79 
80     /**
81      * Request scoring for networks.
82      *
83      * Implementations should delegate to the registered network recommendation provider or
84      * fulfill the request locally if possible.
85      *
86      * @param networks an array of {@link NetworkKey}s to score
87      * @return true if the request was delegated or fulfilled locally, false otherwise
88      * @throws SecurityException if the caller is not the system
89      * @hide
90      */
requestScores(in NetworkKey[] networks)91     boolean requestScores(in NetworkKey[] networks);
92 
93     /**
94      * Determine whether the application with the given UID is the enabled scorer.
95      *
96      * @param callingUid the UID to check
97      * @return true if the provided UID is the active scorer, false otherwise.
98      * @hide
99      */
isCallerActiveScorer(int callingUid)100     boolean isCallerActiveScorer(int callingUid);
101 
102     /**
103      * Obtain the package name of the current active network scorer.
104      *
105      * @return the full package name of the current active scorer, or null if there is no active
106      *         scorer.
107      */
getActiveScorerPackage()108     String getActiveScorerPackage();
109 
110     /**
111      * Returns metadata about the active scorer or <code>null</code> if there is no active scorer.
112      */
getActiveScorer()113     NetworkScorerAppData getActiveScorer();
114 
115     /**
116      * Returns the list of available scorer apps. The list will be empty if there are
117      * no valid scorers.
118      */
getAllValidScorers()119     List<NetworkScorerAppData> getAllValidScorers();
120 }
121