1 /* 2 * Copyright (C) 2010 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.admin; 18 19 import android.accounts.AccountManager; 20 import android.annotation.BroadcastBehavior; 21 import android.annotation.IntDef; 22 import android.annotation.SdkConstant; 23 import android.annotation.SdkConstant.SdkConstantType; 24 import android.annotation.SystemApi; 25 import android.app.Service; 26 import android.content.BroadcastReceiver; 27 import android.content.ComponentName; 28 import android.content.Context; 29 import android.content.Intent; 30 import android.net.Uri; 31 import android.os.Bundle; 32 import android.os.Process; 33 import android.os.UserHandle; 34 import android.security.KeyChain; 35 36 import java.lang.annotation.Retention; 37 import java.lang.annotation.RetentionPolicy; 38 39 /** 40 * Base class for implementing a device administration component. This 41 * class provides a convenience for interpreting the raw intent actions 42 * that are sent by the system. 43 * 44 * <p>The callback methods, like the base 45 * {@link BroadcastReceiver#onReceive(Context, Intent) BroadcastReceiver.onReceive()} 46 * method, happen on the main thread of the process. Thus long running 47 * operations must be done on another thread. Note that because a receiver 48 * is done once returning from its receive function, such long-running operations 49 * should probably be done in a {@link Service}. 50 * 51 * <p>When publishing your DeviceAdmin subclass as a receiver, it must 52 * handle {@link #ACTION_DEVICE_ADMIN_ENABLED} and require the 53 * {@link android.Manifest.permission#BIND_DEVICE_ADMIN} permission. A typical 54 * manifest entry would look like:</p> 55 * 56 * {@sample development/samples/ApiDemos/AndroidManifest.xml device_admin_declaration} 57 * 58 * <p>The meta-data referenced here provides addition information specific 59 * to the device administrator, as parsed by the {@link DeviceAdminInfo} class. 60 * A typical file would be:</p> 61 * 62 * {@sample development/samples/ApiDemos/res/xml/device_admin_sample.xml meta_data} 63 * 64 * <div class="special reference"> 65 * <h3>Developer Guides</h3> 66 * <p>For more information about device administration, read the 67 * <a href="{@docRoot}guide/topics/admin/device-admin.html">Device Administration</a> 68 * developer guide.</p> 69 * </div> 70 */ 71 public class DeviceAdminReceiver extends BroadcastReceiver { 72 private static String TAG = "DevicePolicy"; 73 private static boolean localLOGV = false; 74 75 /** 76 * This is the primary action that a device administrator must implement to be 77 * allowed to manage a device. This will be set to the receiver 78 * when the user enables it for administration. You will generally 79 * handle this in {@link DeviceAdminReceiver#onEnabled(Context, Intent)}. To be 80 * supported, the receiver must also require the 81 * {@link android.Manifest.permission#BIND_DEVICE_ADMIN} permission so 82 * that other applications can not abuse it. 83 */ 84 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 85 @BroadcastBehavior(explicitOnly = true) 86 public static final String ACTION_DEVICE_ADMIN_ENABLED 87 = "android.app.action.DEVICE_ADMIN_ENABLED"; 88 89 /** 90 * Action sent to a device administrator when the user has requested to 91 * disable it, but before this has actually been done. This gives you 92 * a chance to supply a message to the user about the impact of 93 * disabling your admin, by setting the extra field 94 * {@link #EXTRA_DISABLE_WARNING} in the result Intent. If not set, 95 * no warning will be displayed. If set, the given text will be shown 96 * to the user before they disable your admin. 97 */ 98 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 99 @BroadcastBehavior(explicitOnly = true) 100 public static final String ACTION_DEVICE_ADMIN_DISABLE_REQUESTED 101 = "android.app.action.DEVICE_ADMIN_DISABLE_REQUESTED"; 102 103 /** 104 * A CharSequence that can be shown to the user informing them of the 105 * impact of disabling your admin. 106 * 107 * @see #ACTION_DEVICE_ADMIN_DISABLE_REQUESTED 108 */ 109 public static final String EXTRA_DISABLE_WARNING = "android.app.extra.DISABLE_WARNING"; 110 111 /** 112 * Action sent to a device administrator when the user has disabled 113 * it. Upon return, the application no longer has access to the 114 * protected device policy manager APIs. You will generally 115 * handle this in {@link DeviceAdminReceiver#onDisabled(Context, Intent)}. Note 116 * that this action will be 117 * sent the receiver regardless of whether it is explicitly listed in 118 * its intent filter. 119 */ 120 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 121 @BroadcastBehavior(explicitOnly = true) 122 public static final String ACTION_DEVICE_ADMIN_DISABLED 123 = "android.app.action.DEVICE_ADMIN_DISABLED"; 124 125 /** 126 * Action sent to a device administrator when the user has changed the password of their device 127 * or profile challenge. You can at this point check the characteristics 128 * of the new password with {@link DevicePolicyManager#isActivePasswordSufficient() 129 * DevicePolicyManager.isActivePasswordSufficient()}. 130 * You will generally 131 * handle this in {@link DeviceAdminReceiver#onPasswordChanged(Context, Intent, UserHandle)}. 132 * 133 * <p>The calling device admin must have requested 134 * {@link DeviceAdminInfo#USES_POLICY_LIMIT_PASSWORD} to receive 135 * this broadcast. 136 */ 137 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 138 @BroadcastBehavior(explicitOnly = true) 139 public static final String ACTION_PASSWORD_CHANGED 140 = "android.app.action.ACTION_PASSWORD_CHANGED"; 141 142 /** 143 * Action sent to a device administrator when the user has entered an incorrect device 144 * or profile challenge password. You can at this point check the 145 * number of failed password attempts there have been with 146 * {@link DevicePolicyManager#getCurrentFailedPasswordAttempts 147 * DevicePolicyManager.getCurrentFailedPasswordAttempts()}. You will generally 148 * handle this in {@link DeviceAdminReceiver#onPasswordFailed(Context, Intent, UserHandle)}. 149 * 150 * <p>The calling device admin must have requested 151 * {@link DeviceAdminInfo#USES_POLICY_WATCH_LOGIN} to receive 152 * this broadcast. 153 */ 154 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 155 @BroadcastBehavior(explicitOnly = true) 156 public static final String ACTION_PASSWORD_FAILED 157 = "android.app.action.ACTION_PASSWORD_FAILED"; 158 159 /** 160 * Action sent to a device administrator when the user has successfully entered their device 161 * or profile challenge password, after failing one or more times. You will generally 162 * handle this in {@link DeviceAdminReceiver#onPasswordSucceeded(Context, Intent, UserHandle)}. 163 * 164 * <p>The calling device admin must have requested 165 * {@link DeviceAdminInfo#USES_POLICY_WATCH_LOGIN} to receive 166 * this broadcast. 167 */ 168 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 169 @BroadcastBehavior(explicitOnly = true) 170 public static final String ACTION_PASSWORD_SUCCEEDED 171 = "android.app.action.ACTION_PASSWORD_SUCCEEDED"; 172 173 /** 174 * Action periodically sent to a device administrator when the device or profile challenge 175 * password is expiring. You will generally 176 * handle this in {@link DeviceAdminReceiver#onPasswordExpiring(Context, Intent, UserHandle)}. 177 * 178 * <p>The calling device admin must have requested 179 * {@link DeviceAdminInfo#USES_POLICY_EXPIRE_PASSWORD} to receive 180 * this broadcast. 181 */ 182 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 183 @BroadcastBehavior(explicitOnly = true) 184 public static final String ACTION_PASSWORD_EXPIRING 185 = "android.app.action.ACTION_PASSWORD_EXPIRING"; 186 187 /** 188 * Action sent to a device administrator to notify that the device is entering 189 * lock task mode. The extra {@link #EXTRA_LOCK_TASK_PACKAGE} 190 * will describe the package using lock task mode. 191 * 192 * <p>The calling device admin must be the device owner or profile 193 * owner to receive this broadcast. 194 * 195 * @see DevicePolicyManager#isLockTaskPermitted(String) 196 */ 197 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 198 @BroadcastBehavior(explicitOnly = true) 199 public static final String ACTION_LOCK_TASK_ENTERING 200 = "android.app.action.LOCK_TASK_ENTERING"; 201 202 /** 203 * Action sent to a device administrator to notify that the device is exiting 204 * lock task mode. 205 * 206 * <p>The calling device admin must be the device owner or profile 207 * owner to receive this broadcast. 208 * 209 * @see DevicePolicyManager#isLockTaskPermitted(String) 210 */ 211 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 212 @BroadcastBehavior(explicitOnly = true) 213 public static final String ACTION_LOCK_TASK_EXITING 214 = "android.app.action.LOCK_TASK_EXITING"; 215 216 /** 217 * A string containing the name of the package entering lock task mode. 218 * 219 * @see #ACTION_LOCK_TASK_ENTERING 220 */ 221 public static final String EXTRA_LOCK_TASK_PACKAGE = 222 "android.app.extra.LOCK_TASK_PACKAGE"; 223 224 /** 225 * Broadcast Action: This broadcast is sent to indicate that provisioning of a managed profile 226 * or managed device has completed successfully. 227 * 228 * <p>The broadcast is limited to the profile that will be managed by the application that 229 * requested provisioning. In the device owner case the profile is the primary user. 230 * The broadcast will also be limited to the {@link DeviceAdminReceiver} component 231 * specified in the original intent or NFC bump that started the provisioning process 232 * (see {@link DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE 233 * DevicePolicyManager.ACTION_PROVISION_MANAGED_PROFILE}). 234 * 235 * <p>A device admin application which listens to this intent can find out if the device was 236 * provisioned for the device owner or profile owner case by calling respectively 237 * {@link android.app.admin.DevicePolicyManager#isDeviceOwnerApp} and 238 * {@link android.app.admin.DevicePolicyManager#isProfileOwnerApp}. You will generally handle 239 * this in {@link DeviceAdminReceiver#onProfileProvisioningComplete}. 240 * 241 * @see DevicePolicyManager#ACTION_PROVISIONING_SUCCESSFUL 242 */ 243 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 244 @BroadcastBehavior(explicitOnly = true) 245 public static final String ACTION_PROFILE_PROVISIONING_COMPLETE = 246 "android.app.action.PROFILE_PROVISIONING_COMPLETE"; 247 248 /** 249 * Action sent to a device administrator to notify that the device user 250 * has declined sharing a bugreport. 251 * 252 * <p>The calling device admin must be the device owner to receive this broadcast. 253 * @see DevicePolicyManager#requestBugreport 254 * @hide 255 */ 256 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 257 @BroadcastBehavior(explicitOnly = true) 258 public static final String ACTION_BUGREPORT_SHARING_DECLINED = 259 "android.app.action.BUGREPORT_SHARING_DECLINED"; 260 261 /** 262 * Action sent to a device administrator to notify that the collection of a bugreport 263 * has failed. 264 * 265 * <p>The calling device admin must be the device owner to receive this broadcast. 266 * @see DevicePolicyManager#requestBugreport 267 * @hide 268 */ 269 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 270 @BroadcastBehavior(explicitOnly = true) 271 public static final String ACTION_BUGREPORT_FAILED = "android.app.action.BUGREPORT_FAILED"; 272 273 /** 274 * Action sent to a device administrator to share the bugreport. 275 * 276 * <p>The calling device admin must be the device owner to receive this broadcast. 277 * @see DevicePolicyManager#requestBugreport 278 * @hide 279 */ 280 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 281 @BroadcastBehavior(explicitOnly = true) 282 public static final String ACTION_BUGREPORT_SHARE = 283 "android.app.action.BUGREPORT_SHARE"; 284 285 /** 286 * Broadcast action: notify that a new batch of security logs is ready to be collected. 287 * @hide 288 */ 289 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 290 @BroadcastBehavior(explicitOnly = true) 291 public static final String ACTION_SECURITY_LOGS_AVAILABLE 292 = "android.app.action.SECURITY_LOGS_AVAILABLE"; 293 294 /** 295 * Broadcast action: notify that a new batch of network logs is ready to be collected. 296 * @see DeviceAdminReceiver#onNetworkLogsAvailable 297 * @hide 298 */ 299 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 300 @BroadcastBehavior(explicitOnly = true) 301 public static final String ACTION_NETWORK_LOGS_AVAILABLE 302 = "android.app.action.NETWORK_LOGS_AVAILABLE"; 303 304 /** 305 * A {@code long} containing a token of the current batch of network logs, that has to be used 306 * to retrieve the batch of logs by the device owner. 307 * 308 * @see #ACTION_NETWORK_LOGS_AVAILABLE 309 * @see DevicePolicyManager#retrieveNetworkLogs 310 * @hide 311 */ 312 public static final String EXTRA_NETWORK_LOGS_TOKEN = 313 "android.app.extra.EXTRA_NETWORK_LOGS_TOKEN"; 314 315 /** 316 * An {@code int} count representing a total count of network logs inside the current batch of 317 * network logs. 318 * 319 * @see #ACTION_NETWORK_LOGS_AVAILABLE 320 * @hide 321 */ 322 public static final String EXTRA_NETWORK_LOGS_COUNT = 323 "android.app.extra.EXTRA_NETWORK_LOGS_COUNT"; 324 325 /** 326 * Broadcast action: notify the device owner that a user or profile has been added. 327 * Carries an extra {@link Intent#EXTRA_USER} that has the {@link UserHandle} of 328 * the new user. 329 * @hide 330 */ 331 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 332 @BroadcastBehavior(explicitOnly = true) 333 public static final String ACTION_USER_ADDED = "android.app.action.USER_ADDED"; 334 335 /** 336 * Broadcast action: notify the device owner that a user or profile has been removed. 337 * Carries an extra {@link Intent#EXTRA_USER} that has the {@link UserHandle} of 338 * the new user. 339 * @hide 340 */ 341 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 342 @BroadcastBehavior(explicitOnly = true) 343 public static final String ACTION_USER_REMOVED = "android.app.action.USER_REMOVED"; 344 345 /** 346 * A string containing the SHA-256 hash of the bugreport file. 347 * 348 * @see #ACTION_BUGREPORT_SHARE 349 * @hide 350 */ 351 public static final String EXTRA_BUGREPORT_HASH = "android.app.extra.BUGREPORT_HASH"; 352 353 /** 354 * An {@code int} failure code representing the reason of the bugreport failure. One of 355 * {@link #BUGREPORT_FAILURE_FAILED_COMPLETING} 356 * or {@link #BUGREPORT_FAILURE_FILE_NO_LONGER_AVAILABLE} 357 * 358 * @see #ACTION_BUGREPORT_FAILED 359 * @hide 360 */ 361 public static final String EXTRA_BUGREPORT_FAILURE_REASON = 362 "android.app.extra.BUGREPORT_FAILURE_REASON"; 363 364 /** 365 * An interface representing reason of bugreport failure. 366 * 367 * @see #EXTRA_BUGREPORT_FAILURE_REASON 368 * @hide 369 */ 370 @Retention(RetentionPolicy.SOURCE) 371 @IntDef({ 372 BUGREPORT_FAILURE_FAILED_COMPLETING, 373 BUGREPORT_FAILURE_FILE_NO_LONGER_AVAILABLE 374 }) 375 public @interface BugreportFailureCode {} 376 377 /** 378 * Bugreport completion process failed. 379 * 380 * <p>If this error code is received, the requesting of bugreport can be retried. 381 * @see DevicePolicyManager#requestBugreport 382 */ 383 public static final int BUGREPORT_FAILURE_FAILED_COMPLETING = 0; 384 385 /** 386 * Bugreport has been created, but is no longer available for collection. 387 * 388 * <p>This error likely occurs because the user of the device hasn't consented to share 389 * the bugreport for a long period after its creation. 390 * 391 * <p>If this error code is received, the requesting of bugreport can be retried. 392 * @see DevicePolicyManager#requestBugreport 393 */ 394 public static final int BUGREPORT_FAILURE_FILE_NO_LONGER_AVAILABLE = 1; 395 396 /** @hide */ 397 public static final String ACTION_CHOOSE_PRIVATE_KEY_ALIAS = 398 "android.app.action.CHOOSE_PRIVATE_KEY_ALIAS"; 399 400 /** @hide */ 401 public static final String EXTRA_CHOOSE_PRIVATE_KEY_SENDER_UID = 402 "android.app.extra.CHOOSE_PRIVATE_KEY_SENDER_UID"; 403 404 /** @hide */ 405 public static final String EXTRA_CHOOSE_PRIVATE_KEY_URI = 406 "android.app.extra.CHOOSE_PRIVATE_KEY_URI"; 407 408 /** @hide */ 409 public static final String EXTRA_CHOOSE_PRIVATE_KEY_ALIAS = 410 "android.app.extra.CHOOSE_PRIVATE_KEY_ALIAS"; 411 412 /** @hide */ 413 public static final String EXTRA_CHOOSE_PRIVATE_KEY_RESPONSE = 414 "android.app.extra.CHOOSE_PRIVATE_KEY_RESPONSE"; 415 416 /** 417 * Broadcast action: notify device owner that there is a pending system update. 418 * @hide 419 */ 420 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 421 @BroadcastBehavior(explicitOnly = true) 422 public static final String ACTION_NOTIFY_PENDING_SYSTEM_UPDATE = 423 "android.app.action.NOTIFY_PENDING_SYSTEM_UPDATE"; 424 425 /** 426 * A long type extra for {@link #onSystemUpdatePending} recording the system time as given by 427 * {@link System#currentTimeMillis()} when the current pending system update is first available. 428 * @hide 429 */ 430 public static final String EXTRA_SYSTEM_UPDATE_RECEIVED_TIME = 431 "android.app.extra.SYSTEM_UPDATE_RECEIVED_TIME"; 432 433 /** 434 * Name under which a DevicePolicy component publishes information 435 * about itself. This meta-data must reference an XML resource containing 436 * a device-admin tag. 437 */ 438 // TO DO: describe syntax. 439 public static final String DEVICE_ADMIN_META_DATA = "android.app.device_admin"; 440 441 private DevicePolicyManager mManager; 442 private ComponentName mWho; 443 444 /** 445 * Retrieve the DevicePolicyManager interface for this administrator to work 446 * with the system. 447 */ 448 public DevicePolicyManager getManager(Context context) { 449 if (mManager != null) { 450 return mManager; 451 } 452 mManager = (DevicePolicyManager)context.getSystemService( 453 Context.DEVICE_POLICY_SERVICE); 454 return mManager; 455 } 456 457 /** 458 * Retrieve the ComponentName describing who this device administrator is, for 459 * use in {@link DevicePolicyManager} APIs that require the administrator to 460 * identify itself. 461 */ 462 public ComponentName getWho(Context context) { 463 if (mWho != null) { 464 return mWho; 465 } 466 mWho = new ComponentName(context, getClass()); 467 return mWho; 468 } 469 470 /** 471 * Called after the administrator is first enabled, as a result of 472 * receiving {@link #ACTION_DEVICE_ADMIN_ENABLED}. At this point you 473 * can use {@link DevicePolicyManager} to set your desired policies. 474 * 475 * <p> If the admin is activated by a device owner, then the intent 476 * may contain private extras that are relevant to user setup. 477 * {@see DevicePolicyManager#createAndManageUser(ComponentName, String, ComponentName, 478 * PersistableBundle, int)} 479 * 480 * @param context The running context as per {@link #onReceive}. 481 * @param intent The received intent as per {@link #onReceive}. 482 */ 483 public void onEnabled(Context context, Intent intent) { 484 } 485 486 /** 487 * Called when the user has asked to disable the administrator, as a result of 488 * receiving {@link #ACTION_DEVICE_ADMIN_DISABLE_REQUESTED}, giving you 489 * a chance to present a warning message to them. The message is returned 490 * as the result; if null is returned (the default implementation), no 491 * message will be displayed. 492 * @param context The running context as per {@link #onReceive}. 493 * @param intent The received intent as per {@link #onReceive}. 494 * @return Return the warning message to display to the user before 495 * being disabled; if null is returned, no message is displayed. 496 */ 497 public CharSequence onDisableRequested(Context context, Intent intent) { 498 return null; 499 } 500 501 /** 502 * Called prior to the administrator being disabled, as a result of 503 * receiving {@link #ACTION_DEVICE_ADMIN_DISABLED}. Upon return, you 504 * can no longer use the protected parts of the {@link DevicePolicyManager} 505 * API. 506 * @param context The running context as per {@link #onReceive}. 507 * @param intent The received intent as per {@link #onReceive}. 508 */ 509 public void onDisabled(Context context, Intent intent) { 510 } 511 512 /** 513 * Called after the user has changed their device or profile challenge password, as a result of 514 * receiving {@link #ACTION_PASSWORD_CHANGED}. At this point you 515 * can use {@link DevicePolicyManager#getPasswordQuality(android.content.ComponentName)} 516 * to retrieve the active password characteristics. 517 * @param context The running context as per {@link #onReceive}. 518 * @param intent The received intent as per {@link #onReceive}. 519 * 520 * @deprecated From {@link android.os.Build.VERSION_CODES#O}, use 521 * {@link #onPasswordChanged(Context, Intent, UserHandle)} instead. 522 */ 523 @Deprecated 524 public void onPasswordChanged(Context context, Intent intent) { 525 } 526 527 /** 528 * Called after the user has changed their device or profile challenge password, as a result of 529 * receiving {@link #ACTION_PASSWORD_CHANGED}. At this point you 530 * can use {@link DevicePolicyManager#getPasswordQuality(android.content.ComponentName)} 531 * to retrieve the active password characteristics. 532 * @param context The running context as per {@link #onReceive}. 533 * @param intent The received intent as per {@link #onReceive}. 534 * @param user The user or profile for whom the password changed. To see whether this 535 * user is the current profile or a parent user, check for equality with 536 * {@link Process#myUserHandle}. 537 */ 538 public void onPasswordChanged(Context context, Intent intent, UserHandle user) { 539 onPasswordChanged(context, intent); 540 } 541 542 /** 543 * Called after the user has failed at entering their device or profile challenge password, 544 * as a result of receiving {@link #ACTION_PASSWORD_FAILED}. At this point you can use 545 * {@link DevicePolicyManager#getCurrentFailedPasswordAttempts()} to retrieve the number of 546 * failed password attempts. 547 * @param context The running context as per {@link #onReceive}. 548 * @param intent The received intent as per {@link #onReceive}. 549 * 550 * @deprecated From {@link android.os.Build.VERSION_CODES#O}, use 551 * {@link #onPasswordFailed(Context, Intent, UserHandle)} instead. 552 */ 553 @Deprecated 554 public void onPasswordFailed(Context context, Intent intent) { 555 } 556 557 /** 558 * Called after the user has failed at entering their device or profile challenge password, 559 * as a result of receiving {@link #ACTION_PASSWORD_FAILED}. At this point you can use 560 * {@link DevicePolicyManager#getCurrentFailedPasswordAttempts()} to retrieve the number of 561 * failed password attempts. 562 * @param context The running context as per {@link #onReceive}. 563 * @param intent The received intent as per {@link #onReceive}. 564 * @param user The user or profile for whom the password check failed. To see whether this 565 * user is the current profile or a parent user, check for equality with 566 * {@link Process#myUserHandle}. 567 */ 568 public void onPasswordFailed(Context context, Intent intent, UserHandle user) { 569 onPasswordFailed(context, intent); 570 } 571 572 /** 573 * Called after the user has succeeded at entering their device or profile challenge password, 574 * as a result of receiving {@link #ACTION_PASSWORD_SUCCEEDED}. This will 575 * only be received the first time they succeed after having previously 576 * failed. 577 * @param context The running context as per {@link #onReceive}. 578 * @param intent The received intent as per {@link #onReceive}. 579 * 580 * @deprecated From {@link android.os.Build.VERSION_CODES#O}, use 581 * {@link #onPasswordSucceeded(Context, Intent, UserHandle)} instead. 582 */ 583 @Deprecated 584 public void onPasswordSucceeded(Context context, Intent intent) { 585 } 586 587 /** 588 * Called after the user has succeeded at entering their device or profile challenge password, 589 * as a result of receiving {@link #ACTION_PASSWORD_SUCCEEDED}. This will 590 * only be received the first time they succeed after having previously 591 * failed. 592 * @param context The running context as per {@link #onReceive}. 593 * @param intent The received intent as per {@link #onReceive}. 594 * @param user The user of profile for whom the password check succeeded. To see whether this 595 * user is the current profile or a parent user, check for equality with 596 * {@link Process#myUserHandle}. 597 */ 598 public void onPasswordSucceeded(Context context, Intent intent, UserHandle user) { 599 onPasswordSucceeded(context, intent); 600 } 601 602 /** 603 * Called periodically when the device or profile challenge password is about to expire 604 * or has expired. It will typically be called at these times: on device boot, once per day 605 * before the password expires, and at the time when the password expires. 606 * 607 * <p>If the password is not updated by the user, this method will continue to be called 608 * once per day until the password is changed or the device admin disables password expiration. 609 * 610 * <p>The admin will typically post a notification requesting the user to change their password 611 * in response to this call. The actual password expiration time can be obtained by calling 612 * {@link DevicePolicyManager#getPasswordExpiration(ComponentName) } 613 * 614 * <p>The admin should be sure to take down any notifications it posted in response to this call 615 * when it receives {@link DeviceAdminReceiver#onPasswordChanged(Context, Intent) }. 616 * 617 * @param context The running context as per {@link #onReceive}. 618 * @param intent The received intent as per {@link #onReceive}. 619 * 620 * @deprecated From {@link android.os.Build.VERSION_CODES#O}, use 621 * {@link #onPasswordExpiring(Context, Intent, UserHandle)} instead. 622 */ 623 @Deprecated 624 public void onPasswordExpiring(Context context, Intent intent) { 625 } 626 627 /** 628 * Called periodically when the device or profile challenge password is about to expire 629 * or has expired. It will typically be called at these times: on device boot, once per day 630 * before the password expires, and at the time when the password expires. 631 * 632 * <p>If the password is not updated by the user, this method will continue to be called 633 * once per day until the password is changed or the device admin disables password expiration. 634 * 635 * <p>The admin will typically post a notification requesting the user to change their password 636 * in response to this call. The actual password expiration time can be obtained by calling 637 * {@link DevicePolicyManager#getPasswordExpiration(ComponentName) } 638 * 639 * <p>The admin should be sure to take down any notifications it posted in response to this call 640 * when it receives {@link DeviceAdminReceiver#onPasswordChanged(Context, Intent, UserHandle) }. 641 * 642 * @param context The running context as per {@link #onReceive}. 643 * @param intent The received intent as per {@link #onReceive}. 644 * @param user The user or profile for whom the password is expiring. To see whether this 645 * user is the current profile or a parent user, check for equality with 646 * {@link Process#myUserHandle}. 647 */ 648 public void onPasswordExpiring(Context context, Intent intent, UserHandle user) { 649 onPasswordExpiring(context, intent); 650 } 651 652 /** 653 * Called when provisioning of a managed profile or managed device has completed successfully. 654 * 655 * <p> As a prerequisite for the execution of this callback the {@link DeviceAdminReceiver} has 656 * to declare an intent filter for {@link #ACTION_PROFILE_PROVISIONING_COMPLETE}. 657 * Its component must also be specified in the {@link DevicePolicyManager#EXTRA_DEVICE_ADMIN} 658 * of the {@link DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE} intent that started the 659 * managed provisioning. 660 * 661 * <p>When provisioning of a managed profile is complete, the managed profile is hidden until 662 * the profile owner calls {@link DevicePolicyManager#setProfileEnabled(ComponentName admin)}. 663 * Typically a profile owner will enable the profile when it has finished any additional setup 664 * such as adding an account by using the {@link AccountManager} and calling APIs to bring the 665 * profile into the desired state. 666 * 667 * <p> Note that provisioning completes without waiting for any server interactions, so the 668 * profile owner needs to wait for data to be available if required (e.g. Android device IDs or 669 * other data that is set as a result of server interactions). 670 * 671 * <p>From version {@link android.os.Build.VERSION_CODES#O}, when managed provisioning has 672 * completed, along with this callback the activity intent 673 * {@link DevicePolicyManager#ACTION_PROVISIONING_SUCCESSFUL} will also be sent to the same 674 * application. 675 * 676 * @param context The running context as per {@link #onReceive}. 677 * @param intent The received intent as per {@link #onReceive}. 678 */ 679 public void onProfileProvisioningComplete(Context context, Intent intent) { 680 } 681 682 /** 683 * Called during provisioning of a managed device to allow the device initializer to perform 684 * user setup steps. 685 * 686 * @param context The running context as per {@link #onReceive}. 687 * @param intent The received intent as per {@link #onReceive}. 688 * @deprecated Do not use 689 */ 690 @Deprecated 691 @SystemApi 692 public void onReadyForUserInitialization(Context context, Intent intent) { 693 } 694 695 /** 696 * Called when a device is entering lock task mode. 697 * 698 * @param context The running context as per {@link #onReceive}. 699 * @param intent The received intent as per {@link #onReceive}. 700 * @param pkg If entering, the authorized package using lock task mode, otherwise null. 701 */ 702 public void onLockTaskModeEntering(Context context, Intent intent, String pkg) { 703 } 704 705 /** 706 * Called when a device is exiting lock task mode. 707 * 708 * @param context The running context as per {@link #onReceive}. 709 * @param intent The received intent as per {@link #onReceive}. 710 */ 711 public void onLockTaskModeExiting(Context context, Intent intent) { 712 } 713 714 /** 715 * Allows this receiver to select the alias for a private key and certificate pair for 716 * authentication. If this method returns null, the default {@link android.app.Activity} will be 717 * shown that lets the user pick a private key and certificate pair. 718 * 719 * @param context The running context as per {@link #onReceive}. 720 * @param intent The received intent as per {@link #onReceive}. 721 * @param uid The uid asking for the private key and certificate pair. 722 * @param uri The URI to authenticate, may be null. 723 * @param alias The alias preselected by the client, or null. 724 * @return The private key alias to return and grant access to. 725 * @see KeyChain#choosePrivateKeyAlias 726 */ 727 public String onChoosePrivateKeyAlias(Context context, Intent intent, int uid, Uri uri, 728 String alias) { 729 return null; 730 } 731 732 /** 733 * Called when the information about a pending system update is available. 734 * 735 * <p>Allows the receiver to be notified when information about a pending system update is 736 * available from the system update service. The same pending system update can trigger multiple 737 * calls to this method, so it is necessary to examine the incoming parameters for details about 738 * the update. 739 * 740 * <p>This callback is only applicable to device owners and profile owners. 741 * 742 * <p>To get further information about a pending system update (for example, whether or not the 743 * update is a security patch), the device owner or profile owner can call 744 * {@link DevicePolicyManager#getPendingSystemUpdate}. 745 * 746 * @param context The running context as per {@link #onReceive}. 747 * @param intent The received intent as per {@link #onReceive}. 748 * @param receivedTime The time as given by {@link System#currentTimeMillis()} indicating when 749 * the current pending update was first available. -1 if no pending update is available. 750 * @see DevicePolicyManager#getPendingSystemUpdate 751 */ 752 public void onSystemUpdatePending(Context context, Intent intent, long receivedTime) { 753 } 754 755 /** 756 * Called when sharing a bugreport has been cancelled by the user of the device. 757 * 758 * <p>This callback is only applicable to device owners. 759 * 760 * @param context The running context as per {@link #onReceive}. 761 * @param intent The received intent as per {@link #onReceive}. 762 * @see DevicePolicyManager#requestBugreport 763 */ 764 public void onBugreportSharingDeclined(Context context, Intent intent) { 765 } 766 767 /** 768 * Called when the bugreport has been shared with the device administrator app. 769 * 770 * <p>This callback is only applicable to device owners. 771 * 772 * @param context The running context as per {@link #onReceive}. 773 * @param intent The received intent as per {@link #onReceive}. Contains the URI of 774 * the bugreport file (with MIME type "application/vnd.android.bugreport"), that can be accessed 775 * by calling {@link Intent#getData()} 776 * @param bugreportHash SHA-256 hash of the bugreport file. 777 * @see DevicePolicyManager#requestBugreport 778 */ 779 public void onBugreportShared(Context context, Intent intent, String bugreportHash) { 780 } 781 782 /** 783 * Called when the bugreport collection flow has failed. 784 * 785 * <p>This callback is only applicable to device owners. 786 * 787 * @param context The running context as per {@link #onReceive}. 788 * @param intent The received intent as per {@link #onReceive}. 789 * @param failureCode int containing failure code. One of 790 * {@link #BUGREPORT_FAILURE_FAILED_COMPLETING} 791 * or {@link #BUGREPORT_FAILURE_FILE_NO_LONGER_AVAILABLE} 792 * @see DevicePolicyManager#requestBugreport 793 */ 794 public void onBugreportFailed(Context context, Intent intent, 795 @BugreportFailureCode int failureCode) { 796 } 797 798 /** 799 * Called when a new batch of security logs can be retrieved. 800 * 801 * <p>If a secondary user or profile is created, this callback won't be received until all users 802 * become affiliated again (even if security logging is enabled). 803 * See {@link DevicePolicyManager#setAffiliationIds} 804 * 805 * <p>This callback will be re-triggered if the logs are not retrieved. 806 * 807 * <p>This callback is only applicable to device owners. 808 * 809 * @param context The running context as per {@link #onReceive}. 810 * @param intent The received intent as per {@link #onReceive}. 811 * @see DevicePolicyManager#retrieveSecurityLogs(ComponentName) 812 */ 813 public void onSecurityLogsAvailable(Context context, Intent intent) { 814 } 815 816 /** 817 * Called each time a new batch of network logs can be retrieved. This callback method will only 818 * ever be called when network logging is enabled. The logs can only be retrieved while network 819 * logging is enabled. 820 * 821 * <p>If a secondary user or profile is created, this callback won't be received until all users 822 * become affiliated again (even if network logging is enabled). It will also no longer be 823 * possible to retrieve the network logs batch with the most recent {@code batchToken} provided 824 * by this callback. See {@link DevicePolicyManager#setAffiliationIds}. 825 * 826 * <p>This callback is only applicable to device owners. 827 * 828 * @param context The running context as per {@link #onReceive}. 829 * @param intent The received intent as per {@link #onReceive}. 830 * @param batchToken The token representing the current batch of network logs. 831 * @param networkLogsCount The total count of events in the current batch of network logs. 832 * @see DevicePolicyManager#retrieveNetworkLogs 833 */ 834 public void onNetworkLogsAvailable(Context context, Intent intent, long batchToken, 835 int networkLogsCount) { 836 } 837 838 /** 839 * Called when a user or profile is created. 840 * 841 * <p>This callback is only applicable to device owners. 842 * 843 * @param context The running context as per {@link #onReceive}. 844 * @param intent The received intent as per {@link #onReceive}. 845 * @param newUser The {@link UserHandle} of the user that has just been added. 846 */ 847 public void onUserAdded(Context context, Intent intent, UserHandle newUser) { 848 } 849 850 /** 851 * Called when a user or profile is removed. 852 * 853 * <p>This callback is only applicable to device owners. 854 * 855 * @param context The running context as per {@link #onReceive}. 856 * @param intent The received intent as per {@link #onReceive}. 857 * @param removedUser The {@link UserHandle} of the user that has just been removed. 858 */ 859 public void onUserRemoved(Context context, Intent intent, UserHandle removedUser) { 860 } 861 862 /** 863 * Intercept standard device administrator broadcasts. Implementations 864 * should not override this method; it is better to implement the 865 * convenience callbacks for each action. 866 */ 867 @Override 868 public void onReceive(Context context, Intent intent) { 869 String action = intent.getAction(); 870 871 if (ACTION_PASSWORD_CHANGED.equals(action)) { 872 onPasswordChanged(context, intent, intent.getParcelableExtra(Intent.EXTRA_USER)); 873 } else if (ACTION_PASSWORD_FAILED.equals(action)) { 874 onPasswordFailed(context, intent, intent.getParcelableExtra(Intent.EXTRA_USER)); 875 } else if (ACTION_PASSWORD_SUCCEEDED.equals(action)) { 876 onPasswordSucceeded(context, intent, intent.getParcelableExtra(Intent.EXTRA_USER)); 877 } else if (ACTION_DEVICE_ADMIN_ENABLED.equals(action)) { 878 onEnabled(context, intent); 879 } else if (ACTION_DEVICE_ADMIN_DISABLE_REQUESTED.equals(action)) { 880 CharSequence res = onDisableRequested(context, intent); 881 if (res != null) { 882 Bundle extras = getResultExtras(true); 883 extras.putCharSequence(EXTRA_DISABLE_WARNING, res); 884 } 885 } else if (ACTION_DEVICE_ADMIN_DISABLED.equals(action)) { 886 onDisabled(context, intent); 887 } else if (ACTION_PASSWORD_EXPIRING.equals(action)) { 888 onPasswordExpiring(context, intent, intent.getParcelableExtra(Intent.EXTRA_USER)); 889 } else if (ACTION_PROFILE_PROVISIONING_COMPLETE.equals(action)) { 890 onProfileProvisioningComplete(context, intent); 891 } else if (ACTION_CHOOSE_PRIVATE_KEY_ALIAS.equals(action)) { 892 int uid = intent.getIntExtra(EXTRA_CHOOSE_PRIVATE_KEY_SENDER_UID, -1); 893 Uri uri = intent.getParcelableExtra(EXTRA_CHOOSE_PRIVATE_KEY_URI); 894 String alias = intent.getStringExtra(EXTRA_CHOOSE_PRIVATE_KEY_ALIAS); 895 String chosenAlias = onChoosePrivateKeyAlias(context, intent, uid, uri, alias); 896 setResultData(chosenAlias); 897 } else if (ACTION_LOCK_TASK_ENTERING.equals(action)) { 898 String pkg = intent.getStringExtra(EXTRA_LOCK_TASK_PACKAGE); 899 onLockTaskModeEntering(context, intent, pkg); 900 } else if (ACTION_LOCK_TASK_EXITING.equals(action)) { 901 onLockTaskModeExiting(context, intent); 902 } else if (ACTION_NOTIFY_PENDING_SYSTEM_UPDATE.equals(action)) { 903 long receivedTime = intent.getLongExtra(EXTRA_SYSTEM_UPDATE_RECEIVED_TIME, -1); 904 onSystemUpdatePending(context, intent, receivedTime); 905 } else if (ACTION_BUGREPORT_SHARING_DECLINED.equals(action)) { 906 onBugreportSharingDeclined(context, intent); 907 } else if (ACTION_BUGREPORT_SHARE.equals(action)) { 908 String bugreportFileHash = intent.getStringExtra(EXTRA_BUGREPORT_HASH); 909 onBugreportShared(context, intent, bugreportFileHash); 910 } else if (ACTION_BUGREPORT_FAILED.equals(action)) { 911 int failureCode = intent.getIntExtra(EXTRA_BUGREPORT_FAILURE_REASON, 912 BUGREPORT_FAILURE_FAILED_COMPLETING); 913 onBugreportFailed(context, intent, failureCode); 914 } else if (ACTION_SECURITY_LOGS_AVAILABLE.equals(action)) { 915 onSecurityLogsAvailable(context, intent); 916 } else if (ACTION_NETWORK_LOGS_AVAILABLE.equals(action)) { 917 long batchToken = intent.getLongExtra(EXTRA_NETWORK_LOGS_TOKEN, -1); 918 int networkLogsCount = intent.getIntExtra(EXTRA_NETWORK_LOGS_COUNT, 0); 919 onNetworkLogsAvailable(context, intent, batchToken, networkLogsCount); 920 } else if (ACTION_USER_ADDED.equals(action)) { 921 onUserAdded(context, intent, intent.getParcelableExtra(Intent.EXTRA_USER)); 922 } else if (ACTION_USER_REMOVED.equals(action)) { 923 onUserRemoved(context, intent, intent.getParcelableExtra(Intent.EXTRA_USER)); 924 } 925 } 926 } 927