Register now for Android Dev Summit 2019!

WakefulBroadcastReceiver

abstract class WakefulBroadcastReceiver : BroadcastReceiver
kotlin.Any
   ↳ android.content.BroadcastReceiver
   ↳ androidx.legacy.content.WakefulBroadcastReceiver

This helper is for an old pattern of implementing a BroadcastReceiver that receives a device wakeup event and then passes the work off to a android.app.Service, while ensuring that the device does not go back to sleep during the transition.

This class takes care of creating and managing a partial wake lock for you; you must request the android.Manifest.permission#WAKE_LOCK permission to use it.

Wakelocks held by this class are reported to tools as "androidx.core:wake:<component-name>".

Example

A WakefulBroadcastReceiver uses the method startWakefulService() to start the service that does the work. This method is comparable to startService(), except that the WakefulBroadcastReceiver is holding a wake lock when the service starts. The intent that is passed with startWakefulService() holds an extra identifying the wake lock.

The service (in this example, an android.app.IntentService) does some work. When it is finished, it releases the wake lock by calling completeWakefulIntent(intent). The intent it passes as a parameter is the same intent that the WakefulBroadcastReceiver originally passed in.

Summary

Public constructors

This helper is for an old pattern of implementing a BroadcastReceiver that receives a device wakeup event and then passes the work off to a android.app.Service, while ensuring that the device does not go back to sleep during the transition.

Public methods

open static Boolean

Finish the execution from a previous startWakefulService.

open static ComponentName!
startWakefulService(context: Context!, intent: Intent!)

Do a Context.startService, but holding a wake lock while the service starts.

Public constructors

<init>

WakefulBroadcastReceiver()

Deprecated: As of Android O, background check restrictions make this class no longer generally useful. (It is generally not safe to start a service from the receipt of a broadcast, because you don't have any guarantees that your app is in the foreground at this point and thus allowed to do so.) Instead, developers should use android.app.job.JobScheduler to schedule a job, and this does not require that the app hold a wake lock while doing so (the system will take care of holding a wake lock for the job).

This helper is for an old pattern of implementing a BroadcastReceiver that receives a device wakeup event and then passes the work off to a android.app.Service, while ensuring that the device does not go back to sleep during the transition.

This class takes care of creating and managing a partial wake lock for you; you must request the android.Manifest.permission#WAKE_LOCK permission to use it.

Wakelocks held by this class are reported to tools as "androidx.core:wake:<component-name>".

Example

A WakefulBroadcastReceiver uses the method startWakefulService() to start the service that does the work. This method is comparable to startService(), except that the WakefulBroadcastReceiver is holding a wake lock when the service starts. The intent that is passed with startWakefulService() holds an extra identifying the wake lock.

The service (in this example, an android.app.IntentService) does some work. When it is finished, it releases the wake lock by calling completeWakefulIntent(intent). The intent it passes as a parameter is the same intent that the WakefulBroadcastReceiver originally passed in.

Public methods

completeWakefulIntent

open static fun completeWakefulIntent(intent: Intent!): Boolean

Finish the execution from a previous startWakefulService. Any wake lock that was being held will now be released.

Parameters
intent Intent!: The Intent as originally generated by startWakefulService.
Return
Boolean: Returns true if the intent is associated with a wake lock that is now released; returns false if there was no wake lock specified for it.

startWakefulService

open static fun startWakefulService(context: Context!, intent: Intent!): ComponentName!

Do a Context.startService, but holding a wake lock while the service starts. This will modify the Intent to hold an extra identifying the wake lock; when the service receives it in Service.onStartCommand, it should pass back the Intent it receives there to completeWakefulIntent(android.content.Intent) in order to release the wake lock.

Parameters
context Context!: The Context in which it operate.
intent Context!: The Intent with which to start the service, as per Context.startService.