1 /* 2 * Copyright (C) 2019 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 com.android.internal.compat; 18 19 import android.content.pm.ApplicationInfo; 20 import com.android.internal.compat.IOverrideValidator; 21 import java.util.Map; 22 23 parcelable CompatibilityChangeConfig; 24 parcelable CompatibilityOverrideConfig; 25 parcelable CompatibilityOverridesToRemoveConfig; 26 parcelable CompatibilityChangeInfo; 27 /** 28 * Platform private API for talking with the PlatformCompat service. 29 * 30 * <p>Should be used for gating and logging from non-app processes. 31 * 32 * <p>Note: for app processes please use {@code android.compat.Compatibility} API. 33 * 34 * {@hide} 35 */ 36 interface IPlatformCompat { 37 38 /** 39 * Reports that a compatibility change is affecting an app process now. 40 * 41 * <p>Note: for changes that are gated using {@link #isChangeEnabled(long, ApplicationInfo)}, 42 * you do not need to call this API directly. The change will be reported for you. 43 * 44 * @param changeId the ID of the compatibility change taking effect 45 * @param appInfo representing the affected app 46 * @throws SecurityException if logging is not allowed 47 */ reportChange(long changeId, in ApplicationInfo appInfo)48 void reportChange(long changeId, in ApplicationInfo appInfo); 49 50 /** 51 * Reports that a compatibility change is affecting an app process now. 52 * 53 * <p>Note: for changes that are gated using {@link #isChangeEnabled(long, String)}, 54 * you do not need to call this API directly. The change will be reported for you. 55 * 56 * @param changeId the ID of the compatibility change taking effect 57 * @param userId the ID of the user that the operation is done for 58 * @param packageName the package name of the app in question 59 * @throws SecurityException if logging is not allowed 60 */ reportChangeByPackageName(long changeId, in String packageName, int userId)61 void reportChangeByPackageName(long changeId, in String packageName, int userId); 62 63 /** 64 * Reports that a compatibility change is affecting an app process now. 65 * 66 * <p>Note: for changes that are gated using {@link #isChangeEnabled(long, int)}, 67 * you do not need to call this API directly. The change will be reported for you. 68 * 69 * @param changeId the ID of the compatibility change taking effect 70 * @param uid the UID of the app in question 71 * @throws SecurityException if logging is not allowed 72 */ reportChangeByUid(long changeId, int uid)73 void reportChangeByUid(long changeId, int uid); 74 75 /** 76 * Queries if a given compatibility change is enabled for an app process. This method should 77 * be called when implementing functionality on behalf of the affected app. 78 * 79 * <p>If this method returns {@code true}, the calling code should implement the compatibility 80 * change, resulting in differing behaviour compared to earlier releases. If this method returns 81 * {@code false}, the calling code should behave as it did in earlier releases. 82 * 83 * <p>It will also report the change as {@link #reportChange(long, ApplicationInfo)} would, so 84 * there is no need to call that method directly. 85 * 86 * @param changeId the ID of the compatibility change in question 87 * @param appInfo representing the app in question 88 * @return {@code true} if the change is enabled for the current app 89 * @throws SecurityException if logging or reading compat confis is not allowed 90 */ isChangeEnabled(long changeId, in ApplicationInfo appInfo)91 boolean isChangeEnabled(long changeId, in ApplicationInfo appInfo); 92 93 /** 94 * Queries if a given compatibility change is enabled for an app process. This method should 95 * be called when implementing functionality on behalf of the affected app. 96 * 97 * <p>Same as {@link #isChangeEnabled(long, ApplicationInfo)}, except it receives a package name 98 * and userId instead of an {@link ApplicationInfo} 99 * object, and finds an app info object based on the package name. Returns {@code true} if 100 * there is no installed package by that name. 101 * 102 * <p>If this method returns {@code true}, the calling code should implement the compatibility 103 * change, resulting in differing behaviour compared to earlier releases. If this method 104 * returns 105 * {@code false}, the calling code should behave as it did in earlier releases. 106 * 107 * <p>It will also report the change as {@link #reportChange(long, String)} would, so there is 108 * no need to call that method directly. 109 * 110 * @param changeId the ID of the compatibility change in question 111 * @param packageName the package name of the app in question 112 * @param userId the ID of the user that the operation is done for 113 * @return {@code true} if the change is enabled for the current app 114 * @throws SecurityException if logging or reading compat confis is not allowed 115 */ isChangeEnabledByPackageName(long changeId, in String packageName, int userId)116 boolean isChangeEnabledByPackageName(long changeId, in String packageName, int userId); 117 118 /** 119 * Queries if a given compatibility change is enabled for an app process. This method should 120 * be called when implementing functionality on behalf of the affected app. 121 * 122 * <p>Same as {@link #isChangeEnabled(long, ApplicationInfo)}, except it receives a uid 123 * instead of an {@link ApplicationInfo} object, and finds an app info object based on the 124 * uid (or objects if there's more than one package associated with the UID). 125 * Returns {@code true} if there are no installed packages for the required UID, or if the 126 * change is enabled for ALL of the installed packages associated with the provided UID. Please 127 * use a more specific API if you want a different behaviour for multi-package UIDs. 128 * 129 * <p>If this method returns {@code true}, the calling code should implement the compatibility 130 * change, resulting in differing behaviour compared to earlier releases. If this method 131 * returns {@code false}, the calling code should behave as it did in earlier releases. 132 * 133 * <p>It will also report the change as {@link #reportChange(long, int)} would, so there is 134 * no need to call that method directly. 135 * 136 * @param changeId the ID of the compatibility change in question 137 * @param uid the UID of the app in question 138 * @return {@code true} if the change is enabled for the current app 139 * @throws SecurityException if logging or reading compat confis is not allowed 140 */ isChangeEnabledByUid(long changeId, int uid)141 boolean isChangeEnabledByUid(long changeId, int uid); 142 143 /** 144 * Adds overrides to compatibility changes. 145 * 146 * <p>Kills the app to allow the changes to take effect. 147 * 148 * @param overrides parcelable containing the compat change overrides to be applied 149 * @param packageName the package name of the app whose changes will be overridden 150 * @throws SecurityException if overriding changes is not permitted 151 */ setOverrides(in CompatibilityChangeConfig overrides, in String packageName)152 void setOverrides(in CompatibilityChangeConfig overrides, in String packageName); 153 154 /** 155 * Adds overrides to compatibility changes on release builds. 156 * 157 * <p>The caller to this API needs to hold 158 * {@code android.permission.OVERRIDE_COMPAT_CHANGE_CONFIG_ON_RELEASE_BUILD} and all change ids 159 * in {@code overrides} need to annotated with {@link android.compat.annotation.Overridable}. 160 * 161 * A release build in this definition means that {@link android.os.Build#IS_DEBUGGABLE} needs to 162 * be {@code false}. 163 * 164 * <p>Note that this does not kill the app, and therefore overrides read from the app process 165 * will not be updated. Overrides read from the system process do take effect. 166 * 167 * @param overrides parcelable containing the compat change overrides to be applied 168 * @param packageName the package name of the app whose changes will be overridden 169 * @throws SecurityException if overriding changes is not permitted 170 */ putOverridesOnReleaseBuilds(in CompatibilityOverrideConfig overrides, in String packageName)171 void putOverridesOnReleaseBuilds(in CompatibilityOverrideConfig overrides, in String packageName); 172 173 /** 174 * Adds overrides to compatibility changes. 175 * 176 * <p>Does not kill the app, to be only used in tests. 177 * 178 * @param overrides parcelable containing the compat change overrides to be applied 179 * @param packageName the package name of the app whose changes will be overridden 180 * @throws SecurityException if overriding changes is not permitted. 181 */ setOverridesForTest(in CompatibilityChangeConfig overrides, in String packageName)182 void setOverridesForTest(in CompatibilityChangeConfig overrides, in String packageName); 183 184 /** 185 * Restores the default behaviour for the given change and app. 186 * 187 * <p>Kills the app to allow the changes to take effect. 188 * 189 * @param changeId the ID of the change that was overridden 190 * @param packageName the app package name that was overridden 191 * @return {@code true} if an override existed 192 * @throws SecurityException if overriding changes is not permitted 193 */ clearOverride(long changeId, String packageName)194 boolean clearOverride(long changeId, String packageName); 195 196 /** 197 * Restores the default behaviour for the given change and app. 198 * 199 * <p>Does not kill the app; to be only used in tests. 200 * 201 * @param changeId the ID of the change that was overridden 202 * @param packageName the app package name that was overridden 203 * @return {@code true} if an override existed 204 * @throws SecurityException if overriding changes is not permitted 205 */ clearOverrideForTest(long changeId, String packageName)206 boolean clearOverrideForTest(long changeId, String packageName); 207 208 /** 209 * Restores the default behaviour for compatibility changes on release builds. 210 * 211 * <p>The caller to this API needs to hold 212 * {@code android.permission.OVERRIDE_COMPAT_CHANGE_CONFIG_ON_RELEASE_BUILD} and all change ids 213 * in {@code overridesToRemove} need to annotated with 214 * {@link android.compat.annotation.Overridable}. 215 * 216 * A release build in this definition means that {@link android.os.Build#IS_DEBUGGABLE} needs to 217 * be {@code false}. 218 * 219 * <p>Note that this does not kill the app, and therefore overrides read from the app process 220 * will not be updated. Overrides read from the system process do take effect. 221 * 222 * @param overridesToRemove parcelable containing the compat change overrides to be removed 223 * @param packageName the package name of the app whose changes will be restored to the 224 * default behaviour 225 * @throws SecurityException if overriding changes is not permitted 226 */ removeOverridesOnReleaseBuilds(in CompatibilityOverridesToRemoveConfig overridesToRemove, in String packageName)227 void removeOverridesOnReleaseBuilds(in CompatibilityOverridesToRemoveConfig overridesToRemove, in String packageName); 228 229 /** 230 * Enables all compatibility changes that have enabledSinceTargetSdk == 231 * {@param targetSdkVersion} for an app, subject to the policy. 232 * 233 * <p>Kills the app to allow the changes to take effect. 234 * 235 * @param packageName The package name of the app whose compatibility changes will be 236 * enabled. 237 * @param targetSdkVersion The targetSdkVersion for filtering the changes to be enabled. 238 * @return The number of changes that were enabled. 239 * @throws SecurityException if overriding changes is not permitted. 240 */ enableTargetSdkChanges(in String packageName, int targetSdkVersion)241 int enableTargetSdkChanges(in String packageName, int targetSdkVersion); 242 243 /** 244 * Disables all compatibility changes that have enabledAfterTargetSdk == 245 * {@param targetSdkVersion} for an app, subject to the policy. 246 * 247 * <p>Kills the app to allow the changes to take effect. 248 * 249 * @param packageName the package name of the app whose compatibility changes will be 250 * disabled 251 * @param targetSdkVersion the targetSdkVersion for filtering the changes to be disabled 252 * @return the number of changes that were disabled 253 * @throws SecurityException if overriding changes is not permitted. 254 */ disableTargetSdkChanges(in String packageName, int targetSdkVersion)255 int disableTargetSdkChanges(in String packageName, int targetSdkVersion); 256 257 /** 258 * Restores the default behaviour for the given app. 259 * 260 * <p>Kills the app to allow the changes to take effect. 261 * 262 * @param packageName the package name of the app whose overrides will be cleared 263 * @throws SecurityException if overriding changes is not permitted 264 */ clearOverrides(in String packageName)265 void clearOverrides(in String packageName); 266 267 /** 268 * Restores the default behaviour for the given app. 269 * 270 * <p>Does not kill the app; to be only used in tests. 271 * 272 * @param packageName the package name of the app whose overrides will be cleared 273 * @throws SecurityException if overriding changes is not permitted 274 */ clearOverridesForTest(in String packageName)275 void clearOverridesForTest(in String packageName); 276 277 /** 278 * Get configs for an application. 279 * 280 * @param appInfo the application whose config will be returned 281 * @return a {@link CompatibilityChangeConfig}, representing whether a change is enabled for 282 * the given app or not 283 */ getAppConfig(in ApplicationInfo appInfo)284 CompatibilityChangeConfig getAppConfig(in ApplicationInfo appInfo); 285 286 /** 287 * List all compatibility changes. 288 * 289 * @return an array of {@link CompatibilityChangeInfo} known to the service 290 */ listAllChanges()291 CompatibilityChangeInfo[] listAllChanges(); 292 293 /** 294 * List the compatibility changes that should be present in the UI. 295 * Filters out certain changes like e.g. logging only. 296 * 297 * @return an array of {@link CompatibilityChangeInfo} 298 */ listUIChanges()299 CompatibilityChangeInfo[] listUIChanges(); 300 301 /** 302 * Gets an instance that can determine whether a changeid can be overridden for a package name. 303 */ getOverrideValidator()304 IOverrideValidator getOverrideValidator(); 305 } 306