public class DeviceAdminReceiver extends BroadcastReceiver
The callback methods, like the base
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 Service
.
When publishing your DeviceAdmin subclass as a receiver, it must
handle ACTION_DEVICE_ADMIN_ENABLED
and require the
android.Manifest.permission#BIND_DEVICE_ADMIN
permission. A typical
manifest entry would look like:
The meta-data referenced here provides addition information specific
to the device administrator, as parsed by the DeviceAdminInfo
class.
A typical file would be:
For more information about device administration, read the Device Administration developer guide.
Modifier and Type | Class and Description |
---|---|
static interface |
DeviceAdminReceiver.BugreportFailureCode
An interface representing reason of bugreport failure.
|
BroadcastReceiver.PendingResult
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_BUGREPORT_FAILED
Action sent to a device administrator to notify that the collection of a bugreport
has failed.
|
static String |
ACTION_BUGREPORT_SHARE
Action sent to a device administrator to share the bugreport.
|
static String |
ACTION_BUGREPORT_SHARING_DECLINED
Action sent to a device administrator to notify that the device user
has declined sharing a bugreport.
|
static String |
ACTION_CHOOSE_PRIVATE_KEY_ALIAS |
static 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.
|
static String |
ACTION_DEVICE_ADMIN_DISABLED
Action sent to a device administrator when the user has disabled
it.
|
static String |
ACTION_DEVICE_ADMIN_ENABLED
This is the primary action that a device administrator must implement to be
allowed to manage a device.
|
static String |
ACTION_LOCK_TASK_ENTERING
Action sent to a device administrator to notify that the device is entering
lock task mode.
|
static String |
ACTION_LOCK_TASK_EXITING
Action sent to a device administrator to notify that the device is exiting
lock task mode.
|
static String |
ACTION_NOTIFY_PENDING_SYSTEM_UPDATE
Broadcast action: notify device owner that there is a pending system update.
|
static String |
ACTION_PASSWORD_CHANGED
Action sent to a device administrator when the user has changed the password of their device
or profile challenge.
|
static String |
ACTION_PASSWORD_EXPIRING
Action periodically sent to a device administrator when the device or profile challenge
password is expiring.
|
static String |
ACTION_PASSWORD_FAILED
Action sent to a device administrator when the user has entered an incorrect device
or profile challenge password.
|
static String |
ACTION_PASSWORD_SUCCEEDED
Action sent to a device administrator when the user has successfully entered their device
or profile challenge password, after failing one or more times.
|
static 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.
|
static String |
ACTION_SECURITY_LOGS_AVAILABLE
Broadcast action: notify that a new batch of security logs is ready to be collected.
|
static int |
BUGREPORT_FAILURE_FAILED_COMPLETING
Bugreport completion process failed.
|
static int |
BUGREPORT_FAILURE_FILE_NO_LONGER_AVAILABLE
Bugreport has been created, but is no longer available for collection.
|
static String |
DEVICE_ADMIN_META_DATA
Name under which a DevicePolicy component publishes information
about itself.
|
static String |
EXTRA_BUGREPORT_FAILURE_REASON
An
int failure code representing the reason of the bugreport failure. |
static String |
EXTRA_BUGREPORT_HASH
A string containing the SHA-256 hash of the bugreport file.
|
static String |
EXTRA_CHOOSE_PRIVATE_KEY_ALIAS |
static String |
EXTRA_CHOOSE_PRIVATE_KEY_RESPONSE |
static String |
EXTRA_CHOOSE_PRIVATE_KEY_SENDER_UID |
static String |
EXTRA_CHOOSE_PRIVATE_KEY_URI |
static String |
EXTRA_DISABLE_WARNING
A CharSequence that can be shown to the user informing them of the
impact of disabling your admin.
|
static String |
EXTRA_LOCK_TASK_PACKAGE
A string containing the name of the package entering lock task mode.
|
static String |
EXTRA_SYSTEM_UPDATE_RECEIVED_TIME
A long type extra for
onSystemUpdatePending(android.content.Context, android.content.Intent, long) recording the system time as given by
System.currentTimeMillis() when the current pending system update is first available. |
Constructor and Description |
---|
DeviceAdminReceiver() |
Modifier and Type | Method and Description |
---|---|
DevicePolicyManager |
getManager(Context context)
Retrieve the DevicePolicyManager interface for this administrator to work
with the system.
|
ComponentName |
getWho(Context context)
Retrieve the ComponentName describing who this device administrator is, for
use in
DevicePolicyManager APIs that require the administrator to
identify itself. |
void |
onBugreportFailed(Context context,
Intent intent,
int failureCode)
Called when the bugreport collection flow has failed.
|
void |
onBugreportShared(Context context,
Intent intent,
String bugreportHash)
Called when the bugreport has been shared with the device administrator app.
|
void |
onBugreportSharingDeclined(Context context,
Intent intent)
Called when sharing a bugreport has been cancelled by the user of the device.
|
String |
onChoosePrivateKeyAlias(Context context,
Intent intent,
int uid,
Uri uri,
String alias)
Allows this receiver to select the alias for a private key and certificate pair for
authentication.
|
void |
onDisabled(Context context,
Intent intent)
Called prior to the administrator being disabled, as a result of
receiving
ACTION_DEVICE_ADMIN_DISABLED . |
CharSequence |
onDisableRequested(Context context,
Intent intent)
Called when the user has asked to disable the administrator, as a result of
receiving
ACTION_DEVICE_ADMIN_DISABLE_REQUESTED , giving you
a chance to present a warning message to them. |
void |
onEnabled(Context context,
Intent intent)
Called after the administrator is first enabled, as a result of
receiving
ACTION_DEVICE_ADMIN_ENABLED . |
void |
onLockTaskModeEntering(Context context,
Intent intent,
String pkg)
Called when a device is entering lock task mode.
|
void |
onLockTaskModeExiting(Context context,
Intent intent)
Called when a device is exiting lock task mode.
|
void |
onPasswordChanged(Context context,
Intent intent)
Called after the user has changed their device or profile challenge password, as a result of
receiving
ACTION_PASSWORD_CHANGED . |
void |
onPasswordExpiring(Context context,
Intent intent)
Called periodically when the device or profile challenge password is about to expire
or has expired.
|
void |
onPasswordFailed(Context context,
Intent intent)
Called after the user has failed at entering their device or profile challenge password,
as a result of receiving
ACTION_PASSWORD_FAILED . |
void |
onPasswordSucceeded(Context context,
Intent intent)
Called after the user has succeeded at entering their device or profile challenge password,
as a result of receiving
ACTION_PASSWORD_SUCCEEDED . |
void |
onProfileProvisioningComplete(Context context,
Intent intent)
Called when provisioning of a managed profile or managed device has completed successfully.
|
void |
onReadyForUserInitialization(Context context,
Intent intent)
Deprecated.
Do not use
|
void |
onReceive(Context context,
Intent intent)
Intercept standard device administrator broadcasts.
|
void |
onSecurityLogsAvailable(Context context,
Intent intent)
Called when a new batch of security logs can be retrieved.
|
void |
onSystemUpdatePending(Context context,
Intent intent,
long receivedTime)
Allows the receiver to be notified when information about a pending system update is
available from the system update service.
|
abortBroadcast, clearAbortBroadcast, getAbortBroadcast, getDebugUnregister, getPendingResult, getResultCode, getResultData, getResultExtras, getSendingUserId, goAsync, isInitialStickyBroadcast, isOrderedBroadcast, peekService, setDebugUnregister, setOrderedHint, setPendingResult, setResult, setResultCode, setResultData, setResultExtras
public static final String ACTION_DEVICE_ADMIN_ENABLED
onEnabled(Context, Intent)
. To be
supported, the receiver must also require the
android.Manifest.permission#BIND_DEVICE_ADMIN
permission so
that other applications can not abuse it.public static final String ACTION_DEVICE_ADMIN_DISABLE_REQUESTED
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
public static final String ACTION_DEVICE_ADMIN_DISABLED
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
DevicePolicyManager.isActivePasswordSufficient()
.
You will generally
handle this in onPasswordChanged(android.content.Context, android.content.Intent)
.
The calling device admin must have requested
DeviceAdminInfo.USES_POLICY_LIMIT_PASSWORD
to receive
this broadcast.
public static final String ACTION_PASSWORD_FAILED
DevicePolicyManager.getCurrentFailedPasswordAttempts()
. You will generally
handle this in onPasswordFailed(android.content.Context, android.content.Intent)
.
The calling device admin must have requested
DeviceAdminInfo.USES_POLICY_WATCH_LOGIN
to receive
this broadcast.
public static final String ACTION_PASSWORD_SUCCEEDED
onPasswordSucceeded(android.content.Context, android.content.Intent)
.
The calling device admin must have requested
DeviceAdminInfo.USES_POLICY_WATCH_LOGIN
to receive
this broadcast.
public static final String ACTION_PASSWORD_EXPIRING
onPasswordExpiring(android.content.Context, android.content.Intent)
.
The calling device admin must have requested
DeviceAdminInfo.USES_POLICY_EXPIRE_PASSWORD
to receive
this broadcast.
public static final String ACTION_LOCK_TASK_ENTERING
EXTRA_LOCK_TASK_PACKAGE
will describe the 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
The calling device admin must be the device owner or profile owner to receive this broadcast.
public static final String EXTRA_LOCK_TASK_PACKAGE
ACTION_LOCK_TASK_ENTERING
,
Constant Field Valuespublic static final String ACTION_PROFILE_PROVISIONING_COMPLETE
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 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
DevicePolicyManager.isDeviceOwnerApp(java.lang.String)
and
DevicePolicyManager.isProfileOwnerApp(java.lang.String)
. You will generally handle
this in onProfileProvisioningComplete(android.content.Context, android.content.Intent)
.
Input: Nothing.
Output: Nothing
public static final String ACTION_BUGREPORT_SHARING_DECLINED
The calling device admin must be the device owner to receive this broadcast.
public static final String ACTION_BUGREPORT_FAILED
The calling device admin must be the device owner to receive this broadcast.
public static final String ACTION_BUGREPORT_SHARE
The calling device admin must be the device owner to receive this broadcast.
public static final String ACTION_SECURITY_LOGS_AVAILABLE
public static final String EXTRA_BUGREPORT_HASH
ACTION_BUGREPORT_SHARE
,
Constant Field Valuespublic static final String EXTRA_BUGREPORT_FAILURE_REASON
int
failure code representing the reason of the bugreport failure. One of
BUGREPORT_FAILURE_FAILED_COMPLETING
or BUGREPORT_FAILURE_FILE_NO_LONGER_AVAILABLE
ACTION_BUGREPORT_FAILED
,
Constant Field Valuespublic static final int BUGREPORT_FAILURE_FAILED_COMPLETING
If this error code is received, the requesting of bugreport can be retried.
public static final int BUGREPORT_FAILURE_FILE_NO_LONGER_AVAILABLE
This error likely occurs because the user of the device hasn't consented to share the bugreport for a long period after its creation.
If this error code is received, the requesting of bugreport can be retried.
public static final String ACTION_CHOOSE_PRIVATE_KEY_ALIAS
public static final String EXTRA_CHOOSE_PRIVATE_KEY_SENDER_UID
public static final String EXTRA_CHOOSE_PRIVATE_KEY_URI
public static final String EXTRA_CHOOSE_PRIVATE_KEY_ALIAS
public static final String EXTRA_CHOOSE_PRIVATE_KEY_RESPONSE
public static final String ACTION_NOTIFY_PENDING_SYSTEM_UPDATE
public static final String EXTRA_SYSTEM_UPDATE_RECEIVED_TIME
onSystemUpdatePending(android.content.Context, android.content.Intent, long)
recording the system time as given by
System.currentTimeMillis()
when the current pending system update is first available.public static final String DEVICE_ADMIN_META_DATA
public DevicePolicyManager getManager(Context context)
public ComponentName getWho(Context context)
DevicePolicyManager
APIs that require the administrator to
identify itself.public void onEnabled(Context context, Intent intent)
ACTION_DEVICE_ADMIN_ENABLED
. At this point you
can use 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.
DevicePolicyManager.createAndManageUser(ComponentName, String, ComponentName,
PersistableBundle, int)
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public CharSequence onDisableRequested(Context context, Intent intent)
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.context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public void onDisabled(Context context, Intent intent)
ACTION_DEVICE_ADMIN_DISABLED
. Upon return, you
can no longer use the protected parts of the DevicePolicyManager
API.context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public void onPasswordChanged(Context context, Intent intent)
ACTION_PASSWORD_CHANGED
. At this point you
can use DevicePolicyManager.getPasswordQuality(android.content.ComponentName)
to retrieve the active password characteristics.context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public void onPasswordFailed(Context context, Intent intent)
ACTION_PASSWORD_FAILED
. At this point you can use
DevicePolicyManager.getCurrentFailedPasswordAttempts()
to retrieve the number of
failed password attempts.context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public void onPasswordSucceeded(Context context, Intent intent)
ACTION_PASSWORD_SUCCEEDED
. This will
only be received the first time they succeed after having previously
failed.context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public void onPasswordExpiring(Context context, Intent intent)
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
DevicePolicyManager.getPasswordExpiration(ComponentName)
The admin should be sure to take down any notifications it posted in response to this call
when it receives onPasswordChanged(Context, Intent)
.
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public void onProfileProvisioningComplete(Context context, Intent intent)
As a prerequisite for the execution of this callback the DeviceAdminReceiver
has
to declare an intent filter for ACTION_PROFILE_PROVISIONING_COMPLETE
.
Its component must also be specified in the DevicePolicyManager.EXTRA_DEVICE_ADMIN
of the DevicePolicyManager.ACTION_PROVISION_MANAGED_PROFILE
intent that started the
managed provisioning.
When provisioning of a managed profile 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 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).
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.@Deprecated public void onReadyForUserInitialization(Context context, Intent intent)
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public void onLockTaskModeEntering(Context context, Intent intent, String pkg)
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.pkg
- If entering, the authorized package using lock task mode, otherwise null.public void onLockTaskModeExiting(Context context, Intent intent)
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.public String onChoosePrivateKeyAlias(Context context, Intent intent, int uid, Uri uri, String alias)
Activity
will be
shown that lets the user pick a private key and certificate pair.context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.uid
- The uid asking for the private key and certificate pair.uri
- The URI to authenticate, may be null.alias
- The alias preselected by the client, or null.KeyChain.choosePrivateKeyAlias(android.app.Activity, android.security.KeyChainAliasCallback, java.lang.String[], java.security.Principal[], java.lang.String, int, java.lang.String)
public void onSystemUpdatePending(Context context, Intent intent, long receivedTime)
This callback is only applicable to device owners.
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.receivedTime
- The time as given by System.currentTimeMillis()
indicating when
the current pending update was first available. -1 if no pending update is available.public void onBugreportSharingDeclined(Context context, Intent intent)
This callback is only applicable to device owners.
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.DevicePolicyManager.requestBugreport(android.content.ComponentName)
public void onBugreportShared(Context context, Intent intent, String bugreportHash)
This callback is only applicable to device owners.
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
. Contains the URI of
the bugreport file (with MIME type "application/vnd.android.bugreport"), that can be accessed
by calling Intent.getData()
bugreportHash
- SHA-256 hash of the bugreport file.DevicePolicyManager.requestBugreport(android.content.ComponentName)
public void onBugreportFailed(Context context, Intent intent, int failureCode)
This callback is only applicable to device owners.
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.failureCode
- int containing failure code. One of
BUGREPORT_FAILURE_FAILED_COMPLETING
or BUGREPORT_FAILURE_FILE_NO_LONGER_AVAILABLE
DevicePolicyManager.requestBugreport(android.content.ComponentName)
public void onSecurityLogsAvailable(Context context, Intent intent)
This callback is only applicable to device owners.
context
- The running context as per onReceive(android.content.Context, android.content.Intent)
.intent
- The received intent as per onReceive(android.content.Context, android.content.Intent)
.DevicePolicyManager.retrieveSecurityLogs(ComponentName)
public void onReceive(Context context, Intent intent)
onReceive
in class BroadcastReceiver
context
- The Context in which the receiver is running.intent
- The Intent being received.