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
17package android.content.om;
18
19import android.content.om.OverlayInfo;
20
21/**
22 * Api for getting information about overlay packages.
23 *
24 * {@hide}
25 */
26interface 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     */
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     */
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     */
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
87     *         otherwise.
88     */
89    boolean setEnabled(in String packageName, in boolean enable, in int userId);
90
91    /**
92     * Version of setEnabled that will also disable any other overlays for the target package.
93     */
94    boolean setEnabledExclusive(in String packageName, in boolean enable, in int userId);
95
96    /**
97     * Change the priority of the given overlay to be just higher than the
98     * overlay with package name newParentPackageName. Both overlay packages
99     * must have the same target and user.
100     *
101     * @see getOverlayInfosForTarget
102     *
103     * @param packageName The name of the overlay package whose priority should
104     *        be adjusted.
105     * @param newParentPackageName The name of the overlay package the newly
106     *        adjusted overlay package should just outrank.
107     * @param userId The user for which to change the overlay.
108     */
109    boolean setPriority(in String packageName, in String newParentPackageName, in int userId);
110
111    /**
112     * Change the priority of the given overlay to the highest priority relative to
113     * the other overlays with the same target and user.
114     *
115     * @see getOverlayInfosForTarget
116     *
117     * @param packageName The name of the overlay package whose priority should
118     *        be adjusted.
119     * @param userId The user for which to change the overlay.
120     */
121    boolean setHighestPriority(in String packageName, in int userId);
122
123    /**
124     * Change the priority of the overlay to the lowest priority relative to
125     * the other overlays for the same target and user.
126     *
127     * @see getOverlayInfosForTarget
128     *
129     * @param packageName The name of the overlay package whose priority should
130     *        be adjusted.
131     * @param userId The user for which to change the overlay.
132     */
133    boolean setLowestPriority(in String packageName, in int userId);
134}
135