WakefulBroadcastReceiver

<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.

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.

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.