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.OverlayIdentifier; 20 import android.content.om.OverlayInfo; 21 import android.content.om.OverlayManagerTransaction; 22 23 /** 24 * Api for getting information about overlay packages. 25 * 26 * {@hide} 27 */ 28 interface IOverlayManager { 29 /** 30 * Returns information about all installed overlay packages for the 31 * specified user. If there are no installed overlay packages for this user, 32 * an empty map is returned (i.e. null is never returned). The returned map is a 33 * mapping of target package names to lists of overlays. Each list for a 34 * given target package is sorted in priority order, with the overlay with 35 * the highest priority at the end of the list. 36 * 37 * @param userId The user to get the OverlayInfos for. 38 * @return A Map<String, List<OverlayInfo>> with target package names 39 * mapped to lists of overlays; if no overlays exist for the 40 * requested user, an empty map is returned. 41 */ 42 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) getAllOverlays(in int userId)43 Map getAllOverlays(in int userId); 44 45 /** 46 * Returns information about all overlays for the given target package for 47 * the specified user. The returned list is ordered according to the 48 * overlay priority with the highest priority at the end of the list. 49 * 50 * @param targetPackageName The name of the target package. 51 * @param userId The user to get the OverlayInfos for. 52 * @return A list of OverlayInfo objects; if no overlays exist for the 53 * requested package, an empty list is returned. 54 */ getOverlayInfosForTarget(in String targetPackageName, in int userId)55 List getOverlayInfosForTarget(in String targetPackageName, in int userId); 56 57 /** 58 * Returns information about the overlay with the given package name for the 59 * specified user. 60 * 61 * @param packageName The name of the overlay package. 62 * @param userId The user to get the OverlayInfo for. 63 * @return The OverlayInfo for the overlay package; or null if no such 64 * overlay package exists. 65 */ 66 @UnsupportedAppUsage(maxTargetSdk = 30, trackingBug = 170729553) getOverlayInfo(in String packageName, in int userId)67 OverlayInfo getOverlayInfo(in String packageName, in int userId); 68 69 /** 70 * Returns information about the overlay with the given package name for the 71 * specified user. 72 * 73 * @param packageName The name of the overlay package. 74 * @param userId The user to get the OverlayInfo for. 75 * @return The OverlayInfo for the overlay package; or null if no such 76 * overlay package exists. 77 */ getOverlayInfoByIdentifier(in OverlayIdentifier packageName, in int userId)78 OverlayInfo getOverlayInfoByIdentifier(in OverlayIdentifier packageName, in int userId); 79 80 /** 81 * Request that an overlay package be enabled or disabled when possible to 82 * do so. 83 * 84 * It is always possible to disable an overlay, but due to technical and 85 * security reasons it may not always be possible to enable an overlay. An 86 * example of the latter is when the related target package is not 87 * installed. If the technical obstacle is later overcome, the overlay is 88 * automatically enabled at that point in time. 89 * 90 * An enabled overlay is a part of target package's resources, i.e. it will 91 * be part of any lookups performed via {@link android.content.res.Resources} 92 * and {@link android.content.res.AssetManager}. A disabled overlay will no 93 * longer affect the resources of the target package. If the target is 94 * currently running, its outdated resources will be replaced by new ones. 95 * This happens the same way as when an application enters or exits split 96 * window mode. 97 * 98 * @param packageName The name of the overlay package. 99 * @param enable true to enable the overlay, false to disable it. 100 * @param userId The user for which to change the overlay. 101 * @return true if the system successfully registered the request, false otherwise. 102 */ setEnabled(in String packageName, in boolean enable, in int userId)103 boolean setEnabled(in String packageName, in boolean enable, in int userId); 104 105 /** 106 * Request that an overlay package is enabled and any other overlay packages with the same 107 * target package are disabled. 108 * 109 * See {@link #setEnabled} for the details on overlay packages. 110 * 111 * @param packageName the name of the overlay package to enable. 112 * @param enabled must be true, otherwise the operation fails. 113 * @param userId The user for which to change the overlay. 114 * @return true if the system successfully registered the request, false otherwise. 115 */ setEnabledExclusive(in String packageName, in boolean enable, in int userId)116 boolean setEnabledExclusive(in String packageName, in boolean enable, in int userId); 117 118 /** 119 * Request that an overlay package is enabled and any other overlay packages with the same 120 * target package and category are disabled. 121 * 122 * See {@link #setEnabled} for the details on overlay packages. 123 * 124 * @param packageName the name of the overlay package to enable. 125 * @param userId The user for which to change the overlay. 126 * @return true if the system successfully registered the request, false otherwise. 127 */ setEnabledExclusiveInCategory(in String packageName, in int userId)128 boolean setEnabledExclusiveInCategory(in String packageName, in int userId); 129 130 /** 131 * Change the priority of the given overlay to be just higher than the 132 * overlay with package name newParentPackageName. Both overlay packages 133 * must have the same target and user. 134 * 135 * @see getOverlayInfosForTarget 136 * 137 * @param packageName The name of the overlay package whose priority should 138 * be adjusted. 139 * @param newParentPackageName The name of the overlay package the newly 140 * adjusted overlay package should just outrank. 141 * @param userId The user for which to change the overlay. 142 */ setPriority(in String packageName, in String newParentPackageName, in int userId)143 boolean setPriority(in String packageName, in String newParentPackageName, in int userId); 144 145 /** 146 * Change the priority of the given overlay to the highest priority relative to 147 * the other overlays with the same target and user. 148 * 149 * @see getOverlayInfosForTarget 150 * 151 * @param packageName The name of the overlay package whose priority should 152 * be adjusted. 153 * @param userId The user for which to change the overlay. 154 */ setHighestPriority(in String packageName, in int userId)155 boolean setHighestPriority(in String packageName, in int userId); 156 157 /** 158 * Change the priority of the overlay to the lowest priority relative to 159 * the other overlays for the same target and user. 160 * 161 * @see getOverlayInfosForTarget 162 * 163 * @param packageName The name of the overlay package whose priority should 164 * be adjusted. 165 * @param userId The user for which to change the overlay. 166 */ setLowestPriority(in String packageName, in int userId)167 boolean setLowestPriority(in String packageName, in int userId); 168 169 /** 170 * Returns the list of default overlay packages, or an empty array if there are none. 171 */ getDefaultOverlayPackages()172 String[] getDefaultOverlayPackages(); 173 174 /** 175 * Invalidates and removes the idmap for an overlay, 176 * @param packageName The name of the overlay package whose idmap should be deleted. 177 */ invalidateCachesForOverlay(in String packageName, in int userId)178 void invalidateCachesForOverlay(in String packageName, in int userId); 179 180 /** 181 * Perform a series of requests related to overlay packages. This is an 182 * atomic operation: either all requests were performed successfully and 183 * the changes were propagated to the rest of the system, or at least one 184 * request could not be performed successfully and nothing is changed and 185 * nothing is propagated to the rest of the system. 186 * 187 * @see OverlayManagerTransaction 188 * 189 * @param transaction the series of overlay related requests to perform 190 * @throws SecurityException if the transaction failed 191 */ commit(in OverlayManagerTransaction transaction)192 void commit(in OverlayManagerTransaction transaction); 193 } 194