Save the date! Android Dev Summit is coming to Sunnyvale, CA on Oct 23-24, 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.

{@sample frameworks/support/samples/Support4Demos/src/main/java/com/example/android/supportv4/content/SimpleWakefulReceiver.java * complete}

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.

{@sample frameworks/support/samples/Support4Demos/src/main/java/com/example/android/supportv4/content/SimpleWakefulService.java * complete}

Summary

Public constructors

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

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

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

open static Boolean

Finish the execution from a previous startWakefulService.

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.

{@sample frameworks/support/samples/Support4Demos/src/main/java/com/example/android/supportv4/content/SimpleWakefulReceiver.java * complete}

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.

{@sample frameworks/support/samples/Support4Demos/src/main/java/com/example/android/supportv4/content/SimpleWakefulService.java * complete}

Public methods

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.

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.