WakeLock

Kotlin |Java

class WakeLock

kotlin.Any
↳	android.os.PowerManager.WakeLock

A wake lock is a mechanism to indicate that your application needs to have the device stay on.

Any application using a WakeLock must request the android.permission.WAKE_LOCK permission in an <uses-permission> element of the application's manifest. Obtain a wake lock by calling PowerManager#newWakeLock(int, String).

Call acquire() to acquire the wake lock and force the device to stay on at the level that was requested when the wake lock was created.

Call release() when you are done and don't need the lock anymore. It is very important to do this as soon as possible to avoid running down the device's battery excessively.

Summary

Public methods
Unit	`acquire()` Acquires the wake lock.
Unit	`acquire(timeout: Long)` Acquires the wake lock with a timeout.
Boolean	`isHeld()` Returns true if the wake lock has been acquired but not yet released.
Unit	`release()` Releases the wake lock.
Unit	`release(flags: Int)` Releases the wake lock with flags to modify the release behavior.
Unit	`setReferenceCounted(value: Boolean)` Sets whether this WakeLock is reference counted.
Unit	`setStateListener(executor: Executor, listener: PowerManager.WakeLockStateListener?)` Set the listener to get notified when the wakelock is enabled/disabled.
Unit	`setWorkSource(ws: WorkSource!)` Sets the work source associated with the wake lock.
String	`toString()`

Protected methods
Unit	`finalize()`

Public methods

acquire

Added in API level 1

fun acquire(): Unit

Acquires the wake lock.

Ensures that the device is on at the level requested when the wake lock was created.

acquire

Added in API level 1

fun acquire(timeout: Long): Unit

Acquires the wake lock with a timeout.

Ensures that the device is on at the level requested when the wake lock was created. The lock will be released after the given timeout expires.

Parameters
`timeout`	Long: The timeout after which to release the wake lock, in milliseconds.

isHeld

Added in API level 1

fun isHeld(): Boolean

Returns true if the wake lock has been acquired but not yet released.

Return
`Boolean`	True if the wake lock is held.

release

Added in API level 1

fun release(): Unit

Releases the wake lock.

This method releases your claim to the CPU or screen being on. The screen may turn off shortly after you release the wake lock, or it may not if there are other wake locks still held.

release

Added in API level 21

fun release(flags: Int): Unit

Releases the wake lock with flags to modify the release behavior.

This method releases your claim to the CPU or screen being on. The screen may turn off shortly after you release the wake lock, or it may not if there are other wake locks still held.

Parameters
`flags`	Int: Combination of flag values to modify the release behavior. Currently only `RELEASE_FLAG_WAIT_FOR_NO_PROXIMITY` is supported. Passing 0 is equivalent to calling `release()`.

setReferenceCounted

Added in API level 1

fun setReferenceCounted(value: Boolean): Unit

Sets whether this WakeLock is reference counted.

Wake locks are reference counted by default. If a wake lock is reference counted, then each call to acquire() must be balanced by an equal number of calls to release(). If a wake lock is not reference counted, then one call to release() is sufficient to undo the effect of all previous calls to acquire().

Parameters
`value`	Boolean: True to make the wake lock reference counted, false to make the wake lock non-reference counted.

setStateListener

Added in API level 33

fun setStateListener(
    executor: Executor, 
    listener: PowerManager.WakeLockStateListener?
): Unit

Set the listener to get notified when the wakelock is enabled/disabled.

Parameters
`executor`	Executor: `Executor` to handle listener 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.
`listener`	PowerManager.WakeLockStateListener?: listener to be added, set the listener to null to cancel a listener.

setWorkSource

Added in API level 9

fun setWorkSource(ws: WorkSource!): Unit

Sets the work source associated with the wake lock.

The work source is used to determine on behalf of which application the wake lock is being held. This is useful in the case where a service is performing work on behalf of an application so that the cost of that work can be accounted to the application.

Make sure to follow the tag naming convention when using WorkSource to make it easier for app developers to understand wake locks attributed to them. See PowerManager#newWakeLock(int, String) documentation.

Parameters
`ws`	WorkSource!: The work source, or null if none.

toString

Added in API level 1

fun toString(): String

Return
`String`	a string representation of the object.

Protected methods

finalize

Added in API level 1

protected fun finalize(): Unit

Exceptions
`java.lang.Throwable`	the `Exception` raised by this method