1 /*
2  * Copyright (C) 2015 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.content.om;
18 
19 import android.content.om.OverlayInfo;
20 
21 /**
22  * Api for getting information about overlay packages.
23  *
24  * {@hide}
25  */
26 interface IOverlayManager {
27     /**
28      * Returns information about all installed overlay packages for the
29      * specified user. If there are no installed overlay packages for this user,
30      * an empty map is returned (i.e. null is never returned). The returned map is a
31      * mapping of target package names to lists of overlays. Each list for a
32      * given target package is sorted in priority order, with the overlay with
33      * the highest priority at the end of the list.
34      *
35      * @param userId The user to get the OverlayInfos for.
36      * @return A Map<String, List<OverlayInfo>> with target package names
37      *         mapped to lists of overlays; if no overlays exist for the
38      *         requested user, an empty map is returned.
39      */
getAllOverlays(in int userId)40     Map getAllOverlays(in int userId);
41 
42     /**
43      * Returns information about all overlays for the given target package for
44      * the specified user. The returned list is ordered according to the
45      * overlay priority with the highest priority at the end of the list.
46      *
47      * @param targetPackageName The name of the target package.
48      * @param userId The user to get the OverlayInfos for.
49      * @return A list of OverlayInfo objects; if no overlays exist for the
50      *         requested package, an empty list is returned.
51      */
getOverlayInfosForTarget(in String targetPackageName, in int userId)52     List getOverlayInfosForTarget(in String targetPackageName, in int userId);
53 
54     /**
55      * Returns information about the overlay with the given package name for the
56      * specified user.
57      *
58      * @param packageName The name of the overlay package.
59      * @param userId The user to get the OverlayInfo for.
60      * @return The OverlayInfo for the overlay package; or null if no such
61      *         overlay package exists.
62      */
getOverlayInfo(in String packageName, in int userId)63     OverlayInfo getOverlayInfo(in String packageName, in int userId);
64 
65     /**
66      * Request that an overlay package be enabled or disabled when possible to
67      * do so.
68      *
69      * It is always possible to disable an overlay, but due to technical and
70      * security reasons it may not always be possible to enable an overlay. An
71      * example of the latter is when the related target package is not
72      * installed. If the technical obstacle is later overcome, the overlay is
73      * automatically enabled at that point in time.
74      *
75      * An enabled overlay is a part of target package's resources, i.e. it will
76      * be part of any lookups performed via {@link android.content.res.Resources}
77      * and {@link android.content.res.AssetManager}. A disabled overlay will no
78      * longer affect the resources of the target package. If the target is
79      * currently running, its outdated resources will be replaced by new ones.
80      * This happens the same way as when an application enters or exits split
81      * window mode.
82      *
83      * @param packageName The name of the overlay package.
84      * @param enable true to enable the overlay, false to disable it.
85      * @param userId The user for which to change the overlay.
86      * @return true if the system successfully registered the request, false otherwise.
87      */
setEnabled(in String packageName, in boolean enable, in int userId)88     boolean setEnabled(in String packageName, in boolean enable, in int userId);
89 
90     /**
91      * Request that an overlay package is enabled and any other overlay packages with the same
92      * target package are disabled.
93      *
94      * See {@link #setEnabled} for the details on overlay packages.
95      *
96      * @param packageName the name of the overlay package to enable.
97      * @param enabled must be true, otherwise the operation fails.
98      * @param userId The user for which to change the overlay.
99      * @return true if the system successfully registered the request, false otherwise.
100      */
setEnabledExclusive(in String packageName, in boolean enable, in int userId)101     boolean setEnabledExclusive(in String packageName, in boolean enable, in int userId);
102 
103     /**
104      * Request that an overlay package is enabled and any other overlay packages with the same
105      * target package and category are disabled.
106      *
107      * See {@link #setEnabled} for the details on overlay packages.
108      *
109      * @param packageName the name of the overlay package to enable.
110      * @param userId The user for which to change the overlay.
111      * @return true if the system successfully registered the request, false otherwise.
112      */
setEnabledExclusiveInCategory(in String packageName, in int userId)113     boolean setEnabledExclusiveInCategory(in String packageName, in int userId);
114 
115     /**
116      * Change the priority of the given overlay to be just higher than the
117      * overlay with package name newParentPackageName. Both overlay packages
118      * must have the same target and user.
119      *
120      * @see getOverlayInfosForTarget
121      *
122      * @param packageName The name of the overlay package whose priority should
123      *        be adjusted.
124      * @param newParentPackageName The name of the overlay package the newly
125      *        adjusted overlay package should just outrank.
126      * @param userId The user for which to change the overlay.
127      */
setPriority(in String packageName, in String newParentPackageName, in int userId)128     boolean setPriority(in String packageName, in String newParentPackageName, in int userId);
129 
130     /**
131      * Change the priority of the given overlay to the highest priority relative to
132      * the other overlays with the same target and user.
133      *
134      * @see getOverlayInfosForTarget
135      *
136      * @param packageName The name of the overlay package whose priority should
137      *        be adjusted.
138      * @param userId The user for which to change the overlay.
139      */
setHighestPriority(in String packageName, in int userId)140     boolean setHighestPriority(in String packageName, in int userId);
141 
142     /**
143      * Change the priority of the overlay to the lowest priority relative to
144      * the other overlays for the same target and user.
145      *
146      * @see getOverlayInfosForTarget
147      *
148      * @param packageName The name of the overlay package whose priority should
149      *        be adjusted.
150      * @param userId The user for which to change the overlay.
151      */
setLowestPriority(in String packageName, in int userId)152     boolean setLowestPriority(in String packageName, in int userId);
153 }
154