Added in API level 1

WakeLock

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

Acquires the wake lock.

Unit
acquire(timeout: Long)

Acquires the wake lock with a timeout.

Boolean

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

Unit

Releases the wake lock.

Unit
release(flags: Int)

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

Unit

Sets whether this WakeLock is reference counted.

Unit

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

Unit

Sets the work source associated with the wake lock.

String

Protected methods
Unit

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