1 /*
2  * Copyright (C) 2018 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 package com.android.server.infra;
17 
18 import android.annotation.NonNull;
19 import android.annotation.Nullable;
20 import android.annotation.UserIdInt;
21 
22 import com.android.internal.infra.AbstractRemoteService;
23 
24 import java.io.PrintWriter;
25 import java.util.List;
26 
27 /**
28  * A helper class used to resolve the name of the app-provided service a
29  * {@link AbstractRemoteService} binds to.
30  *
31  * @hide
32  */
33 public interface ServiceNameResolver {
34     /**
35      * Listener for name changes.
36      */
37     interface NameResolverListener {
38 
39         /**
40          * The name change callback.
41          */
onNameResolved(@serIdInt int userId, @Nullable String serviceName, boolean isTemporary)42         void onNameResolved(@UserIdInt int userId, @Nullable String serviceName,
43                 boolean isTemporary);
44     }
45 
46     /**
47      * Sets a callback that is called after the service is
48      * {@link #setTemporaryService(int, String, int) set} or
49      * {@link #resetTemporaryService(int) reset}.
50      *
51      * <p>Typically called after the object is constructed.
52      */
setOnTemporaryServiceNameChangedCallback( @uppressWarnings"unused") @onNull NameResolverListener callback)53     default void setOnTemporaryServiceNameChangedCallback(
54             @SuppressWarnings("unused") @NonNull NameResolverListener callback) {
55         // ignored by default
56     }
57 
58     /**
59      * Gets the default name of the service for the given user.
60      *
61      * <p>Typically implemented by reading a Settings property or framework resource.
62      */
63     @Nullable
getDefaultServiceName(@serIdInt int userId)64     String getDefaultServiceName(@UserIdInt int userId);
65 
66     /**
67      * Gets the default list of names of the services for the given user.
68      *
69      * <p>Typically implemented by reading a Settings property or framework resource.
70      */
71     @Nullable
getDefaultServiceNameList(@serIdInt int userId)72     default String[] getDefaultServiceNameList(@UserIdInt int userId) {
73         if (isConfiguredInMultipleMode()) {
74             throw new UnsupportedOperationException("getting default service list not supported");
75         } else {
76             return new String[] { getDefaultServiceName(userId) };
77         }
78     }
79 
80     /**
81      * Set the given list of services to the secure setting
82      */
setServiceNameList(List<String> services, int userId)83     default void setServiceNameList(List<String> services, int userId) {
84     }
85 
86     /**
87      * Returns whether the resolver is configured to connect to multiple backend services.
88      * The default return type is false.
89      *
90      * <p>Typically implemented by reading a Settings property or framework resource.
91      */
isConfiguredInMultipleMode()92     default boolean isConfiguredInMultipleMode() {
93         return false;
94     }
95 
96     /**
97      * Gets the current name of the service for the given user
98      *
99      * @return either the temporary name (set by
100      * {@link #setTemporaryService(int, String, int)}, or the
101      * {@link #getDefaultServiceName(int) default name}.
102      */
103     @Nullable
getServiceName(@serIdInt int userId)104     default String getServiceName(@UserIdInt int userId) {
105         return getDefaultServiceName(userId);
106     }
107 
108     /**
109      * Gets the current name of the service for the given user
110      *
111      * @return either the temporary name (set by
112      * {@link #setTemporaryService(int, String, int)}, or the
113      * {@link #getDefaultServiceName(int) default name}.
114      */
115     @Nullable
getServiceNameList(@serIdInt int userId)116     default String[] getServiceNameList(@UserIdInt int userId) {
117         return getDefaultServiceNameList(userId);
118     }
119 
120     /**
121      * Checks whether the current service is temporary for the given user.
122      */
isTemporary(@uppressWarnings"unused") @serIdInt int userId)123     default boolean isTemporary(@SuppressWarnings("unused") @UserIdInt int userId) {
124         return false;
125     }
126 
127     /**
128      * Temporarily sets the service implementation for the given user.
129      *
130      * @param userId        user handle
131      * @param componentName name of the new component
132      * @param durationMs    how long the change will be valid (the service will be automatically
133      *                      reset
134      *                      to the default component after this timeout expires).
135      * @throws UnsupportedOperationException if not implemented.
136      */
setTemporaryService(@serIdInt int userId, @NonNull String componentName, int durationMs)137     default void setTemporaryService(@UserIdInt int userId, @NonNull String componentName,
138             int durationMs) {
139         throw new UnsupportedOperationException("temporary user not supported");
140     }
141 
142     /**
143      * Temporarily sets the service implementation for the given user.
144      *
145      * @param userId         user handle
146      * @param componentNames list of the names of the new component
147      * @param durationMs     how long the change will be valid (the service will be automatically
148      *                       reset
149      *                       to the default component after this timeout expires).
150      * @throws UnsupportedOperationException if not implemented.
151      */
setTemporaryServices(@serIdInt int userId, @NonNull String[] componentNames, int durationMs)152     default void setTemporaryServices(@UserIdInt int userId, @NonNull String[] componentNames,
153             int durationMs) {
154         throw new UnsupportedOperationException("temporary user not supported");
155     }
156 
157     /**
158      * Resets the temporary service implementation to the default component for the given user.
159      *
160      * @param userId user handle
161      * @throws UnsupportedOperationException if not implemented.
162      */
resetTemporaryService(@serIdInt int userId)163     default void resetTemporaryService(@UserIdInt int userId) {
164         throw new UnsupportedOperationException("temporary user not supported");
165     }
166 
167     /**
168      * Sets whether the default service should be used when the temporary service is not set.
169      *
170      * <p>Typically used during CTS tests to make sure only the default service doesn't interfere
171      * with the test results.
172      *
173      * @param userId  user handle
174      * @param enabled whether the default service should be used when the temporary service is not
175      *                set. If the service enabled state is already that value, the command is
176      *                ignored and this
177      *                method return {@code false}.
178      * @return whether the enabled state changed.
179      * @throws UnsupportedOperationException if not implemented.
180      */
setDefaultServiceEnabled(@serIdInt int userId, boolean enabled)181     default boolean setDefaultServiceEnabled(@UserIdInt int userId, boolean enabled) {
182         throw new UnsupportedOperationException("changing default service not supported");
183     }
184 
185     /**
186      * Checks whether the default service should be used when the temporary service is not set.
187      *
188      * <p>Typically used during CTS tests to make sure only the default service doesn't interfere
189      * with the test results.
190      *
191      * @param userId user handle
192      * @throws UnsupportedOperationException if not implemented.
193      */
isDefaultServiceEnabled(@serIdInt int userId)194     default boolean isDefaultServiceEnabled(@UserIdInt int userId) {
195         throw new UnsupportedOperationException("checking default service not supported");
196     }
197 
198     /**
199      * Dumps the generic info in just one line (without calling {@code println}.
200      */
201     // TODO(b/117779333): support proto
dumpShort(@onNull PrintWriter pw)202     void dumpShort(@NonNull PrintWriter pw);
203 
204     /**
205      * Dumps the user-specific info in just one line (without calling {@code println}.
206      */
207     // TODO(b/117779333): support proto
dumpShort(@onNull PrintWriter pw, @UserIdInt int userId)208     void dumpShort(@NonNull PrintWriter pw, @UserIdInt int userId);
209 }
210