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