Added in API level 34

DeviceLockManager

class DeviceLockManager
kotlin.Any
   ↳ android.devicelock.DeviceLockManager

Manager used to interact with the system device lock service. The device lock feature is used by special applications ('kiosk apps', downloaded and installed by the device lock solution) to lock and unlock a device. A typical use case is a financed device, where the financing entity has the capability to lock the device in case of a missed payment. When a device is locked, only a limited set of interactions with the device is allowed (for example, placing emergency calls).

Use android.content.Context#getSystemService(java.lang.String) with Context.DEVICE_LOCK_SERVICE to create a DeviceLockManager.


Requires the PackageManager#FEATURE_DEVICE_LOCK feature which can be detected using PackageManager.hasSystemFeature(String).

Summary

Constants
static Int

Constant representing a financed device role, returned by getKioskApps.
static String

Extra passed to the kiosk setup activity containing the version of the Device Lock solution that started the activity.
Public methods
Unit

Clear device restrictions.
Unit

Gets the device id.
Unit

Get the kiosk app roles and packages.
Unit

Checks if the device is locked or not.
Unit
lockDevice(executor: Executor, callback: OutcomeReceiver<Void!, Exception!>)

Locks the device.
Unit

Notifies DLC that kiosk set-up has finished and we no longer need to lock to the set-up activity.
Unit
unlockDevice(executor: Executor, callback: OutcomeReceiver<Void!, Exception!>)

Unlocks the device.

Constants

DEVICE_LOCK_ROLE_FINANCING

Added in API level 34
static val DEVICE_LOCK_ROLE_FINANCING: Int

Constant representing a financed device role, returned by getKioskApps.

Value: 0

EXTRA_DEVICE_LOCK_VERSION

Added in API level Baklava
static val EXTRA_DEVICE_LOCK_VERSION: String

Extra passed to the kiosk setup activity containing the version of the Device Lock solution that started the activity. The kiosk setup activity can retrieve the version by calling getIntent().getIntExtra(DeviceLockManager.EXTRA_DEVICE_LOCK_VERSION, 1) This is meant to be used by kiosk apps sharing the same setup activity between the legacy Device Owner(DO) based DeviceLock solution (version 1) and successive versions.

Value: "android.devicelock.extra.DEVICE_LOCK_VERSION"

Public methods

clearDeviceRestrictions

Added in API level Baklava
fun clearDeviceRestrictions(
    executor: Executor, 
    callback: OutcomeReceiver<Void!, Exception!>
): Unit

Clear device restrictions.

After a device determines that it's part of a program (e.g. financing) by checking in with the device lock backend, it will go though a provisioning flow and install a kiosk app.

At this point, the device is "restricted" and the creditor kiosk app is able to lock the device. For example, a creditor kiosk app in a financing use case may lock the device (using lockDevice) if payments are missed and unlock (using unlockDevice)) once they are resumed.

The Device Lock solution will also put in place some additional restrictions when a device is enrolled in the program, namely:

Once the program is completed (e.g. the device has been fully paid off), the kiosk app can use the clearDeviceRestrictions API to lift the above restrictions.

At this point, the kiosk app has relinquished its ability to lock the device.

Exceptions that can be returned through the ParcelableException on the callback's onError method:

  • SecurityException if the caller is missing the android.android.Manifest.permission.MANAGE_DEVICE_LOCK_STATE permission.
  • IllegalStateException if the device has already been cleared or if policies could not be enforced for the clear state.
  • java.util.concurrent.TimeoutException if the response from the underlying binder call is not received within the specified duration (10 seconds).

Requires android.Manifest.permission#MANAGE_DEVICE_LOCK_STATE
Parameters
executor Executor: the Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<Void!, Exception!>: this returns either success or an exception. This value cannot be null.
Exceptions
java.lang.RuntimeException if there are binder communications errors

getDeviceId

Added in API level 34
fun getDeviceId(
    executor: Executor, 
    callback: OutcomeReceiver<DeviceId!, Exception!>
): Unit

Gets the device id.

Exceptions that can be returned through the ParcelableException on the callback's onError method:


Requires android.Manifest.permission#MANAGE_DEVICE_LOCK_STATE
Parameters
executor Executor: the Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<DeviceId!, Exception!>: this returns either the DeviceId or an exception. This value cannot be null.
Exceptions
java.lang.RuntimeException if there are binder communications errors

getKioskApps

Added in API level 34
fun getKioskApps(
    executor: Executor, 
    callback: OutcomeReceiver<MutableMap<Int!, String!>!, Exception!>
): Unit

Get the kiosk app roles and packages.

Parameters
executor Executor: the Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<MutableMap<Int!, String!>!, Exception!>: this returns either a Map of device roles/package names, or an exception. The Integer in the map represent the device lock role (at this moment, the only supported role is {@value #DEVICE_LOCK_ROLE_FINANCING}. The String represents the package name of the kiosk app for that role. This value cannot be null.
Exceptions
java.lang.RuntimeException if there are binder communications errors

isDeviceLocked

Added in API level 34
fun isDeviceLocked(
    executor: Executor, 
    callback: OutcomeReceiver<Boolean!, Exception!>
): Unit

Checks if the device is locked or not.

Exceptions that can be returned through the ParcelableException on the callback's onError method:


Requires android.Manifest.permission#MANAGE_DEVICE_LOCK_STATE
Parameters
executor Executor: the Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<Boolean!, Exception!>: this returns either the lock status or an exception. This value cannot be null.
Exceptions
java.lang.RuntimeException if there are binder communications errors

lockDevice

Added in API level 34
fun lockDevice(
    executor: Executor, 
    callback: OutcomeReceiver<Void!, Exception!>
): Unit

Locks the device.

Exceptions that can be returned through the ParcelableException on the callback's onError method:

  • SecurityException if the caller is missing the android.android.Manifest.permission.MANAGE_DEVICE_LOCK_STATE permission.
  • IllegalStateException if the device has already been cleared or if policies could not be enforced for the lock state.
  • java.util.concurrent.TimeoutException if the response from the underlying binder call is not received within the specified duration (10 seconds).

Requires android.Manifest.permission#MANAGE_DEVICE_LOCK_STATE
Parameters
executor Executor: the Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<Void!, Exception!>: this returns either success or an exception. This value cannot be null.
Exceptions
java.lang.RuntimeException if there are binder communications errors

notifyKioskSetupFinished

Added in API level Baklava
fun notifyKioskSetupFinished(
    executor: Executor, 
    callback: OutcomeReceiver<Void!, Exception!>
): Unit

Notifies DLC that kiosk set-up has finished and we no longer need to lock to the set-up activity. This will close the set-up activity as specified through a callback and then respect the current device lock state. If the device has never been locked or unlocked by the kiosk, it will unlock the device. Invoking lockDevice or unlockDevice will also result in the device provision state moving from kiosk_provisioned to provision_success.

Exceptions that can be returned through the ParcelableException on the callback's onError method:

  • SecurityException if the caller is missing the android.android.Manifest.permission.MANAGE_DEVICE_LOCK_STATE permission.
  • IllegalStateException if the device has already been cleared or if policies could not be enforced for the lock or unlock state.
  • java.util.concurrent.TimeoutException if the response from the underlying binder call is not received within the specified duration (10 seconds).

Requires android.Manifest.permission#MANAGE_DEVICE_LOCK_STATE
Parameters
executor Executor: the Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<Void!, Exception!>: this returns either success or an exception. This value cannot be null.
Exceptions
java.lang.RuntimeException if there are binder communications errors

unlockDevice

Added in API level 34
fun unlockDevice(
    executor: Executor, 
    callback: OutcomeReceiver<Void!, Exception!>
): Unit

Unlocks the device.

Exceptions that can be returned through the ParcelableException on the callback's onError method:

  • SecurityException if the caller is missing the android.android.Manifest.permission.MANAGE_DEVICE_LOCK_STATE permission.
  • IllegalStateException if the device has already been cleared or if policies could not be enforced for the unlock state.
  • java.util.concurrent.TimeoutException If the response from the underlying binder call is not received within the specified duration (10 seconds).

Requires android.Manifest.permission#MANAGE_DEVICE_LOCK_STATE
Parameters
executor Executor: the Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<Void!, Exception!>: this returns either success or an exception. This value cannot be null.
Exceptions
java.lang.RuntimeException if there are binder communications errors