FileDocCategorySizeDatePackage
DeviceAdminReceiver.javaAPI DocAndroid 5.1 API19719Thu Mar 12 22:22:10 GMT 2015android.app.admin

DeviceAdminReceiver

public class DeviceAdminReceiver extends android.content.BroadcastReceiver
Base class for implementing a device administration component. This class provides a convenience for interpreting the raw intent actions that are sent by the system.

The callback methods, like the base {@link BroadcastReceiver#onReceive(Context, Intent) BroadcastReceiver.onReceive()} method, happen on the main thread of the process. Thus long running operations must be done on another thread. Note that because a receiver is done once returning from its receive function, such long-running operations should probably be done in a {@link Service}.

When publishing your DeviceAdmin subclass as a receiver, it must handle {@link #ACTION_DEVICE_ADMIN_ENABLED} and require the {@link android.Manifest.permission#BIND_DEVICE_ADMIN} permission. A typical manifest entry would look like:

{@sample development/samples/ApiDemos/AndroidManifest.xml device_admin_declaration}

The meta-data referenced here provides addition information specific to the device administrator, as parsed by the {@link DeviceAdminInfo} class. A typical file would be:

{@sample development/samples/ApiDemos/res/xml/device_admin_sample.xml meta_data}

Developer Guides

For more information about device administration, read the Device Administration developer guide.

Fields Summary
private static String
TAG
private static boolean
localLOGV
public static final String
ACTION_DEVICE_ADMIN_ENABLED
This is the primary action that a device administrator must implement to be allowed to manage a device. This will be set to the receiver when the user enables it for administration. You will generally handle this in {@link DeviceAdminReceiver#onEnabled(Context, Intent)}. To be supported, the receiver must also require the {@link android.Manifest.permission#BIND_DEVICE_ADMIN} permission so that other applications can not abuse it.
public static final String
ACTION_DEVICE_ADMIN_DISABLE_REQUESTED
Action sent to a device administrator when the user has requested to disable it, but before this has actually been done. This gives you a chance to supply a message to the user about the impact of disabling your admin, by setting the extra field {@link #EXTRA_DISABLE_WARNING} in the result Intent. If not set, no warning will be displayed. If set, the given text will be shown to the user before they disable your admin.
public static final String
EXTRA_DISABLE_WARNING
A CharSequence that can be shown to the user informing them of the impact of disabling your admin.
public static final String
ACTION_DEVICE_ADMIN_DISABLED
Action sent to a device administrator when the user has disabled it. Upon return, the application no longer has access to the protected device policy manager APIs. You will generally handle this in {@link DeviceAdminReceiver#onDisabled(Context, Intent)}. Note that this action will be sent the receiver regardless of whether it is explicitly listed in its intent filter.
public static final String
ACTION_PASSWORD_CHANGED
Action sent to a device administrator when the user has changed the password of their device. You can at this point check the characteristics of the new password with {@link DevicePolicyManager#isActivePasswordSufficient() DevicePolicyManager.isActivePasswordSufficient()}. You will generally handle this in {@link DeviceAdminReceiver#onPasswordChanged}.

The calling device admin must have requested {@link DeviceAdminInfo#USES_POLICY_LIMIT_PASSWORD} to receive this broadcast.

public static final String
ACTION_PASSWORD_FAILED
Action sent to a device administrator when the user has failed at attempted to enter the password. You can at this point check the number of failed password attempts there have been with {@link DevicePolicyManager#getCurrentFailedPasswordAttempts DevicePolicyManager.getCurrentFailedPasswordAttempts()}. You will generally handle this in {@link DeviceAdminReceiver#onPasswordFailed}.

The calling device admin must have requested {@link DeviceAdminInfo#USES_POLICY_WATCH_LOGIN} to receive this broadcast.

public static final String
ACTION_PASSWORD_SUCCEEDED
Action sent to a device administrator when the user has successfully entered their password, after failing one or more times.

The calling device admin must have requested {@link DeviceAdminInfo#USES_POLICY_WATCH_LOGIN} to receive this broadcast.

public static final String
ACTION_PASSWORD_EXPIRING
Action periodically sent to a device administrator when the device password is expiring.

The calling device admin must have requested {@link DeviceAdminInfo#USES_POLICY_EXPIRE_PASSWORD} to receive this broadcast.

public static final String
ACTION_LOCK_TASK_ENTERING
Action sent to a device administrator to notify that the device is entering lock task mode from an authorized package. The extra {@link #EXTRA_LOCK_TASK_PACKAGE} will describe the authorized package using lock task mode.

The calling device admin must be the device owner or profile owner to receive this broadcast.

public static final String
ACTION_LOCK_TASK_EXITING
Action sent to a device administrator to notify that the device is exiting lock task mode from an authorized package.

The calling device admin must be the device owner or profile owner to receive this broadcast.

public static final String
EXTRA_LOCK_TASK_PACKAGE
A string containing the name of the package entering lock task mode.
public static final String
ACTION_PROFILE_PROVISIONING_COMPLETE
Broadcast Action: This broadcast is sent to indicate that provisioning of a managed profile or managed device has completed successfully.

The broadcast is limited to the profile that will be managed by the application that requested provisioning. In the device owner case the profile is the primary user. The broadcast will also be limited to the {@link DeviceAdminReceiver} component specified in the original intent or NFC bump that started the provisioning process (@see DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE).

A device admin application which listens to this intent can find out if the device was provisioned for the device owner or profile owner case by calling respectively {@link android.app.admin.DevicePolicyManager#isDeviceOwnerApp} and {@link android.app.admin.DevicePolicyManager#isProfileOwnerApp}.

Input: Nothing.

Output: Nothing

public static final String
DEVICE_ADMIN_META_DATA
Name under which a DevicePolicy component publishes information about itself. This meta-data must reference an XML resource containing a device-admin tag. XXX TO DO: describe syntax.
private DevicePolicyManager
mManager
private android.content.ComponentName
mWho
Constructors Summary
Methods Summary
public DevicePolicyManagergetManager(android.content.Context context)
Retrieve the DevicePolicyManager interface for this administrator to work with the system.


                     
        
        if (mManager != null) {
            return mManager;
        }
        mManager = (DevicePolicyManager)context.getSystemService(
                Context.DEVICE_POLICY_SERVICE);
        return mManager;
public android.content.ComponentNamegetWho(android.content.Context context)
Retrieve the ComponentName describing who this device administrator is, for use in {@link DevicePolicyManager} APIs that require the administrator to identify itself.

        if (mWho != null) {
            return mWho;
        }
        mWho = new ComponentName(context, getClass());
        return mWho;
public java.lang.CharSequenceonDisableRequested(android.content.Context context, android.content.Intent intent)
Called when the user has asked to disable the administrator, as a result of receiving {@link #ACTION_DEVICE_ADMIN_DISABLE_REQUESTED}, giving you a chance to present a warning message to them. The message is returned as the result; if null is returned (the default implementation), no message will be displayed.

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
return
Return the warning message to display to the user before being disabled; if null is returned, no message is displayed.

        return null;
public voidonDisabled(android.content.Context context, android.content.Intent intent)
Called prior to the administrator being disabled, as a result of receiving {@link #ACTION_DEVICE_ADMIN_DISABLED}. Upon return, you can no longer use the protected parts of the {@link DevicePolicyManager} API.

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
public voidonEnabled(android.content.Context context, android.content.Intent intent)
Called after the administrator is first enabled, as a result of receiving {@link #ACTION_DEVICE_ADMIN_ENABLED}. At this point you can use {@link DevicePolicyManager} to set your desired policies.

If the admin is activated by a device owner, then the intent may contain private extras that are relevant to user setup. {@see DevicePolicyManager#createAndInitializeUser(ComponentName, String, String, ComponentName, Intent)}

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
public voidonLockTaskModeEntering(android.content.Context context, android.content.Intent intent, java.lang.String pkg)
Called when a device is entering lock task mode by a package authorized by {@link DevicePolicyManager#isLockTaskPermitted(String)}

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
param
pkg If entering, the authorized package using lock task mode, otherwise null.
public voidonLockTaskModeExiting(android.content.Context context, android.content.Intent intent)
Called when a device is exiting lock task mode by a package authorized by {@link DevicePolicyManager#isLockTaskPermitted(String)}

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
public voidonPasswordChanged(android.content.Context context, android.content.Intent intent)
Called after the user has changed their password, as a result of receiving {@link #ACTION_PASSWORD_CHANGED}. At this point you can use {@link DevicePolicyManager#getCurrentFailedPasswordAttempts() DevicePolicyManager.getCurrentFailedPasswordAttempts()} to retrieve the active password characteristics.

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
public voidonPasswordExpiring(android.content.Context context, android.content.Intent intent)
Called periodically when the password is about to expire or has expired. It will typically be called at these times: on device boot, once per day before the password expires, and at the time when the password expires.

If the password is not updated by the user, this method will continue to be called once per day until the password is changed or the device admin disables password expiration.

The admin will typically post a notification requesting the user to change their password in response to this call. The actual password expiration time can be obtained by calling {@link DevicePolicyManager#getPasswordExpiration(ComponentName) }

The admin should be sure to take down any notifications it posted in response to this call when it receives {@link DeviceAdminReceiver#onPasswordChanged(Context, Intent) }.

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
public voidonPasswordFailed(android.content.Context context, android.content.Intent intent)
Called after the user has failed at entering their current password, as a result of receiving {@link #ACTION_PASSWORD_FAILED}. At this point you can use {@link DevicePolicyManager} to retrieve the number of failed password attempts.

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
public voidonPasswordSucceeded(android.content.Context context, android.content.Intent intent)
Called after the user has succeeded at entering their current password, as a result of receiving {@link #ACTION_PASSWORD_SUCCEEDED}. This will only be received the first time they succeed after having previously failed.

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
public voidonProfileProvisioningComplete(android.content.Context context, android.content.Intent intent)
Called when provisioning of a managed profile or managed device has completed successfully.

As a prerequisit for the execution of this callback the (@link DeviceAdminReceiver} has to declare an intent filter for {@link #ACTION_PROFILE_PROVISIONING_COMPLETE}. Its component must also be specified in the {@link DevicePolicyManager#EXTRA_DEVICE_ADMIN} of the {@link DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE} intent that started the managed provisioning.

When provisioning is complete, the managed profile is hidden until the profile owner calls {DevicePolicyManager#setProfileEnabled(ComponentName admin)}. Typically a profile owner will enable the profile when it has finished any additional setup such as adding an account by using the {@link AccountManager} and calling apis to bring the profile into the desired state.

Note that provisioning completes without waiting for any server interactions, so the profile owner needs to wait for data to be available if required (e.g android device ids or other data that is set as a result of server interactions).

param
context The running context as per {@link #onReceive}.
param
intent The received intent as per {@link #onReceive}.
public voidonReceive(android.content.Context context, android.content.Intent intent)
Intercept standard device administrator broadcasts. Implementations should not override this method; it is better to implement the convenience callbacks for each action.

        String action = intent.getAction();

        if (ACTION_PASSWORD_CHANGED.equals(action)) {
            onPasswordChanged(context, intent);
        } else if (ACTION_PASSWORD_FAILED.equals(action)) {
            onPasswordFailed(context, intent);
        } else if (ACTION_PASSWORD_SUCCEEDED.equals(action)) {
            onPasswordSucceeded(context, intent);
        } else if (ACTION_DEVICE_ADMIN_ENABLED.equals(action)) {
            onEnabled(context, intent);
        } else if (ACTION_DEVICE_ADMIN_DISABLE_REQUESTED.equals(action)) {
            CharSequence res = onDisableRequested(context, intent);
            if (res != null) {
                Bundle extras = getResultExtras(true);
                extras.putCharSequence(EXTRA_DISABLE_WARNING, res);
            }
        } else if (ACTION_DEVICE_ADMIN_DISABLED.equals(action)) {
            onDisabled(context, intent);
        } else if (ACTION_PASSWORD_EXPIRING.equals(action)) {
            onPasswordExpiring(context, intent);
        } else if (ACTION_PROFILE_PROVISIONING_COMPLETE.equals(action)) {
            onProfileProvisioningComplete(context, intent);
        } else if (ACTION_LOCK_TASK_ENTERING.equals(action)) {
            String pkg = intent.getStringExtra(EXTRA_LOCK_TASK_PACKAGE);
            onLockTaskModeEntering(context, intent, pkg);
        } else if (ACTION_LOCK_TASK_EXITING.equals(action)) {
            onLockTaskModeExiting(context, intent);
        }