1 /* 2 * Copyright (C) 2017 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.app.backup; 18 19 import android.annotation.SystemApi; 20 import android.app.backup.BackupAnnotations.OperationType; 21 import android.content.pm.PackageInfo; 22 import android.os.Bundle; 23 24 /** 25 * Callback class for receiving important events during backup/restore operations. 26 * Events consist mostly of errors and exceptions, giving detailed reason on why a restore/backup 27 * failed or any time BackupManager makes an important decision. 28 * On the other hand {@link BackupObserver} will give a failure/success view without 29 * getting into details why. This callback runs on the thread it was called on because it can get 30 * a bit spammy. 31 * These callbacks will run on the binder thread. 32 * 33 * @hide 34 */ 35 @SystemApi 36 public class BackupManagerMonitor { 37 38 // Logging constants for BackupManagerMonitor 39 public static final int LOG_EVENT_CATEGORY_TRANSPORT = 1; 40 public static final int LOG_EVENT_CATEGORY_AGENT = 2; 41 public static final int LOG_EVENT_CATEGORY_BACKUP_MANAGER_POLICY = 3; 42 /** string : the package name */ 43 public static final String EXTRA_LOG_EVENT_PACKAGE_NAME = 44 "android.app.backup.extra.LOG_EVENT_PACKAGE_NAME"; 45 /** int : the versionCode of the package named by EXTRA_LOG_EVENT_PACKAGE_NAME 46 * @deprecated Use {@link #EXTRA_LOG_EVENT_PACKAGE_LONG_VERSION} */ 47 @Deprecated 48 public static final String EXTRA_LOG_EVENT_PACKAGE_VERSION = 49 "android.app.backup.extra.LOG_EVENT_PACKAGE_VERSION"; 50 /** long : the full versionCode of the package named by EXTRA_LOG_EVENT_PACKAGE_NAME */ 51 public static final String EXTRA_LOG_EVENT_PACKAGE_LONG_VERSION = 52 "android.app.backup.extra.LOG_EVENT_PACKAGE_FULL_VERSION"; 53 /** int : the id of the log message, will be a unique identifier */ 54 public static final String EXTRA_LOG_EVENT_ID = "android.app.backup.extra.LOG_EVENT_ID"; 55 /** 56 * int : category will be one of 57 * { LOG_EVENT_CATEGORY_TRANSPORT, 58 * LOG_EVENT_CATEGORY_AGENT, 59 * LOG_EVENT_CATEGORY_BACKUP_MANAGER_POLICY}. 60 */ 61 public static final String EXTRA_LOG_EVENT_CATEGORY = 62 "android.app.backup.extra.LOG_EVENT_CATEGORY"; 63 64 65 /** 66 * boolean: when we have an event with id LOG_EVENT_ID_KEY_VALUE_BACKUP_CANCEL we record if 67 * the call was to cancel backup of all packages 68 */ 69 public static final String EXTRA_LOG_CANCEL_ALL = "android.app.backup.extra.LOG_CANCEL_ALL"; 70 71 /** 72 * string: when we have an event with id LOG_EVENT_ID_ILLEGAL_KEY we send the key that was used 73 * by the app 74 */ 75 public static final String EXTRA_LOG_ILLEGAL_KEY = "android.app.backup.extra.LOG_ILLEGAL_KEY"; 76 77 /** 78 * long: when we have an event with id LOG_EVENT_ID_ERROR_PREFLIGHT we send the error code that 79 * was returned by the transport during preflight 80 */ 81 public static final String EXTRA_LOG_PREFLIGHT_ERROR = 82 "android.app.backup.extra.LOG_PREFLIGHT_ERROR"; 83 84 /** 85 * string: when we have an event with id LOG_EVENT_ID_EXCEPTION_FULL_BACKUP we send the 86 * exception's stacktrace 87 */ 88 public static final String EXTRA_LOG_EXCEPTION_FULL_BACKUP = 89 "android.app.backup.extra.LOG_EXCEPTION_FULL_BACKUP"; 90 91 /** 92 * int: when we have an event with id LOG_EVENT_ID_RESTORE_VERSION_HIGHER we send the 93 * restore package version 94 */ 95 public static final String EXTRA_LOG_RESTORE_VERSION = 96 "android.app.backup.extra.LOG_RESTORE_VERSION"; 97 98 /** 99 * boolean: when we have an event with id LOG_EVENT_ID_RESTORE_VERSION_HIGHER we record if 100 * ApplicationInfo.FLAG_RESTORE_ANY_VERSION flag is set 101 */ 102 public static final String EXTRA_LOG_RESTORE_ANYWAY = 103 "android.app.backup.extra.LOG_RESTORE_ANYWAY"; 104 105 106 /** 107 * boolean: when we have an event with id LOG_EVENT_ID_APK_NOT_INSTALLED we record if 108 * the policy allows to install apks provided with the dataset 109 */ 110 public static final String EXTRA_LOG_POLICY_ALLOW_APKS = 111 "android.app.backup.extra.LOG_POLICY_ALLOW_APKS"; 112 113 114 /** 115 * string: when we have an event with id LOG_EVENT_ID_EXPECTED_DIFFERENT_PACKAGE we record the 116 * package name provided in the restore manifest 117 */ 118 public static final String EXTRA_LOG_MANIFEST_PACKAGE_NAME = 119 "android.app.backup.extra.LOG_MANIFEST_PACKAGE_NAME"; 120 121 /** 122 * string: when we have an event with id LOG_EVENT_ID_WIDGET_METADATA_MISMATCH we record the 123 * package name provided in the widget metadata 124 */ 125 public static final String EXTRA_LOG_WIDGET_PACKAGE_NAME = 126 "android.app.backup.extra.LOG_WIDGET_PACKAGE_NAME"; 127 128 /** 129 * int: when we have event of id LOG_EVENT_ID_VERSION_OF_BACKUP_OLDER we send the version 130 * of the backup. 131 */ 132 public static final String EXTRA_LOG_OLD_VERSION = "android.app.backup.extra.LOG_OLD_VERSION"; 133 134 /** 135 * ParcelableList: when we have an event of id LOG_EVENT_ID_AGENT_LOGGING_RESULTS we send a list 136 * of {@link android.app.backup.BackupRestoreEventLogger.DataTypeResult}. 137 */ 138 public static final String EXTRA_LOG_AGENT_LOGGING_RESULTS = 139 "android.app.backup.extra.LOG_AGENT_LOGGING_RESULTS"; 140 141 /** 142 * The operation type this log is associated with. See {@link OperationType}. 143 * 144 * @hide 145 */ 146 public static final String EXTRA_LOG_OPERATION_TYPE = "android.app.backup.extra.OPERATION_TYPE"; 147 148 /** 149 * List of system components that do not support restore in a V-> U OS downgrade, even if 150 * restoreAnyVersion is set to true. 151 * Read from Settings.Secure.V_TO_U_RESTORE_DENYLIST 152 * 153 * @hide 154 */ 155 public static final String EXTRA_LOG_V_TO_U_DENYLIST = "android.app.backup.extra.V_TO_U_DENYLIST"; 156 157 /** 158 * List of system components that support restore in a V-> U OS downgrade, even if 159 * restoreAnyVersion is set to false. 160 * Read from Settings.Secure.V_TO_U_RESTORE_ALLOWLIST 161 * 162 * @hide 163 */ 164 public static final String EXTRA_LOG_V_TO_U_ALLOWLIST = 165 "android.app.backup.extra.V_TO_U_ALLOWLIST"; 166 167 /** 168 * An int indicating why a backup was cancelled. One of {@link 169 * com.android.server.backup.BackupRestoreTask.CancellationReason}. 170 * 171 * @hide 172 */ 173 public static final String EXTRA_LOG_CANCELLATION_REASON = 174 "android.app.backup.extra.CANCELLATION_REASON"; 175 176 // TODO complete this list with all log messages. And document properly. 177 public static final int LOG_EVENT_ID_FULL_BACKUP_CANCEL = 4; 178 public static final int LOG_EVENT_ID_ILLEGAL_KEY = 5; 179 public static final int LOG_EVENT_ID_NO_DATA_TO_SEND = 7; 180 public static final int LOG_EVENT_ID_PACKAGE_INELIGIBLE = 9; 181 public static final int LOG_EVENT_ID_PACKAGE_KEY_VALUE_PARTICIPANT = 10; 182 public static final int LOG_EVENT_ID_PACKAGE_STOPPED = 11; 183 public static final int LOG_EVENT_ID_PACKAGE_NOT_FOUND = 12; 184 public static final int LOG_EVENT_ID_BACKUP_DISABLED = 13; 185 public static final int LOG_EVENT_ID_DEVICE_NOT_PROVISIONED = 14; 186 public static final int LOG_EVENT_ID_PACKAGE_TRANSPORT_NOT_PRESENT = 15; 187 public static final int LOG_EVENT_ID_ERROR_PREFLIGHT = 16; 188 public static final int LOG_EVENT_ID_QUOTA_HIT_PREFLIGHT = 18; 189 public static final int LOG_EVENT_ID_EXCEPTION_FULL_BACKUP = 19; 190 public static final int LOG_EVENT_ID_KEY_VALUE_BACKUP_CANCEL = 21; 191 public static final int LOG_EVENT_ID_NO_RESTORE_METADATA_AVAILABLE = 22; 192 public static final int LOG_EVENT_ID_NO_PM_METADATA_RECEIVED = 23; 193 public static final int LOG_EVENT_ID_PM_AGENT_HAS_NO_METADATA = 24; 194 public static final int LOG_EVENT_ID_LOST_TRANSPORT = 25; 195 public static final int LOG_EVENT_ID_PACKAGE_NOT_PRESENT = 26; 196 public static final int LOG_EVENT_ID_RESTORE_VERSION_HIGHER = 27; 197 public static final int LOG_EVENT_ID_APP_HAS_NO_AGENT = 28; 198 public static final int LOG_EVENT_ID_SIGNATURE_MISMATCH = 29; 199 public static final int LOG_EVENT_ID_CANT_FIND_AGENT = 30; 200 public static final int LOG_EVENT_ID_KEY_VALUE_RESTORE_TIMEOUT = 31; 201 public static final int LOG_EVENT_ID_RESTORE_ANY_VERSION = 34; 202 public static final int LOG_EVENT_ID_VERSIONS_MATCH = 35; 203 public static final int LOG_EVENT_ID_VERSION_OF_BACKUP_OLDER = 36; 204 public static final int LOG_EVENT_ID_FULL_RESTORE_SIGNATURE_MISMATCH = 37; 205 public static final int LOG_EVENT_ID_SYSTEM_APP_NO_AGENT = 38; 206 public static final int LOG_EVENT_ID_FULL_RESTORE_ALLOW_BACKUP_FALSE = 39; 207 public static final int LOG_EVENT_ID_APK_NOT_INSTALLED = 40; 208 public static final int LOG_EVENT_ID_CANNOT_RESTORE_WITHOUT_APK = 41; 209 public static final int LOG_EVENT_ID_MISSING_SIGNATURE = 42; 210 public static final int LOG_EVENT_ID_EXPECTED_DIFFERENT_PACKAGE = 43; 211 public static final int LOG_EVENT_ID_UNKNOWN_VERSION = 44; 212 public static final int LOG_EVENT_ID_FULL_RESTORE_TIMEOUT = 45; 213 public static final int LOG_EVENT_ID_CORRUPT_MANIFEST = 46; 214 public static final int LOG_EVENT_ID_WIDGET_METADATA_MISMATCH = 47; 215 public static final int LOG_EVENT_ID_WIDGET_UNKNOWN_VERSION = 48; 216 public static final int LOG_EVENT_ID_NO_PACKAGES = 49; 217 public static final int LOG_EVENT_ID_TRANSPORT_IS_NULL = 50; 218 /** The transport returned {@link BackupTransport#TRANSPORT_NON_INCREMENTAL_BACKUP_REQUIRED}. */ 219 public static final int LOG_EVENT_ID_TRANSPORT_NON_INCREMENTAL_BACKUP_REQUIRED = 51; 220 221 public static final int LOG_EVENT_ID_AGENT_LOGGING_RESULTS = 52; 222 /** @hide */ 223 public static final int LOG_EVENT_ID_START_SYSTEM_RESTORE = 53; 224 /** @hide */ 225 public static final int LOG_EVENT_ID_START_RESTORE_AT_INSTALL = 54; 226 /** A transport error happened during {@link PerformUnifiedRestoreTask#startRestore()} 227 @hide */ 228 public static final int LOG_EVENT_ID_TRANSPORT_ERROR_DURING_START_RESTORE = 55; 229 /** Unable to get the name of the next package in the queue during a restore operation 230 @hide */ 231 public static final int LOG_EVENT_ID_CANNOT_GET_NEXT_PKG_NAME = 56; 232 /** Attempting a restore operation that is neither KV nor full 233 @hide */ 234 public static final int LOG_EVENT_ID_UNKNOWN_RESTORE_TYPE = 57; 235 /** The package is part of KeyValue restore 236 @hide */ 237 public static final int LOG_EVENT_ID_KV_RESTORE = 58; 238 /** The package is part of Full restore 239 @hide */ 240 public static final int LOG_EVENT_ID_FULL_RESTORE = 59; 241 /** Unable to fetch the nest restore target in the queue 242 @hide */ 243 public static final int LOG_EVENT_ID_NO_NEXT_RESTORE_TARGET = 60; 244 /** An error occurred while attempting KeyValueRestore 245 @hide */ 246 public static final int LOG_EVENT_ID_KV_AGENT_ERROR = 61; 247 /** Restore operation finished for the given package 248 @hide */ 249 public static final int LOG_EVENT_ID_PACKAGE_RESTORE_FINISHED= 62; 250 /** A transport error happened during 251 * {@link PerformUnifiedRestoreTask#initiateOneRestore(PackageInfo, long)} 252 @hide */ 253 public static final int LOG_EVENT_ID_TRANSPORT_ERROR_KV_RESTORE = 63; 254 /** Unable to instantiate the feeder thread in full restore 255 @hide */ 256 public static final int LOG_EVENT_ID_NO_FEEDER_THREAD = 64; 257 /** An error occurred while attempting Full restore 258 @hide */ 259 public static final int LOG_EVENT_ID_FULL_AGENT_ERROR = 65; 260 /** A transport error happened during a full restore 261 @hide */ 262 public static final int LOG_EVENT_ID_TRANSPORT_ERROR_FULL_RESTORE = 66; 263 /** Start restore operation for a given package 264 @hide */ 265 public static final int LOG_EVENT_ID_START_PACKAGE_RESTORE = 67; 266 /** Whole restore operation is complete 267 @hide */ 268 public static final int LOG_EVENT_ID_RESTORE_COMPLETE = 68; 269 /** Agent error during {@link PerformUnifiedRestoreTask#restoreFinished()} 270 @hide */ 271 public static final int LOG_EVENT_ID_AGENT_FAILURE = 69; 272 /** V to U restore attempt, pkg is eligible 273 @hide */ 274 public static final int LOG_EVENT_ID_V_TO_U_RESTORE_PKG_ELIGIBLE = 70; 275 /** V to U restore attempt, pkg is not eligible 276 @hide */ 277 public static final int LOG_EVENT_ID_V_TO_U_RESTORE_PKG_NOT_ELIGIBLE = 71; 278 /** V to U restore attempt, allowlist and denlist are set 279 @hide */ 280 public static final int LOG_EVENT_ID_V_TO_U_RESTORE_SET_LIST = 72; 281 /** As part of package install, {@link PackageManager} invoked restore. 282 @hide */ 283 public static final int LOG_EVENT_ID_RESTORE_AT_INSTALL_INVOKED = 73; 284 /** Skipping restore at package install 285 @hide */ 286 public static final int LOG_EVENT_ID_SKIP_RESTORE_AT_INSTALL = 74; 287 /** Package is eligible and is accepted for restore 288 @hide */ 289 public static final int LOG_EVENT_ID_PACKAGE_ACCEPTED_FOR_RESTORE = 75; 290 /** Restore data doesn't belong to the package for which restore is started 291 @hide */ 292 public static final int LOG_EVENT_ID_RESTORE_DATA_DOES_NOT_BELONG_TO_PACKAGE = 76; 293 /** Unable to create BackupAgent for package for restore 294 @hide */ 295 public static final int LOG_EVENT_ID_UNABLE_TO_CREATE_AGENT_FOR_RESTORE = 77; 296 /** BackupAgent crashed after creation but before accepting any data 297 @hide */ 298 public static final int LOG_EVENT_ID_AGENT_CRASHED_BEFORE_RESTORE_DATA_IS_SENT = 78; 299 /** Failure in streaming restore data to BackupAgent 300 @hide */ 301 public static final int LOG_EVENT_ID_FAILED_TO_SEND_DATA_TO_AGENT_DURING_RESTORE = 79; 302 /** BackupAgent related failure during restore 303 @hide */ 304 public static final int LOG_EVENT_ID_AGENT_FAILURE_DURING_RESTORE = 80; 305 /** Failure in reading data from TransportPackage during restore 306 @hide */ 307 public static final int LOG_EVENT_ID_FAILED_TO_READ_DATA_FROM_TRANSPORT = 81; 308 309 /** The pipe between the BackupAgent and the framework was broken during full backup. @hide */ 310 public static final int LOG_EVENT_ID_FULL_BACKUP_AGENT_PIPE_BROKEN = 82; 311 312 /** 313 * This method will be called each time something important happens on BackupManager. 314 * 315 * @param event bundle will contain data about event: 316 * - event id, not optional, a unique identifier for each event. 317 * - package name, optional, the current package we're backing up/restoring if applicable. 318 * - package version, optional, the current package version we're backing up/restoring 319 * if applicable. 320 * - category of event, not optional, one of 321 * { LOG_EVENT_CATEGORY_TRANSPORT, 322 * LOG_EVENT_CATEGORY_AGENT, 323 * LOG_EVENT_CATEGORY_BACKUP_MANAGER_POLICY} 324 * 325 */ onEvent(Bundle event)326 public void onEvent(Bundle event) { 327 } 328 } 329