added in version 22.1.0
belongs to Maven artifact com.android.support:support-core-utils:28.0.0-alpha1
Deprecated since version 26.1.0

WakefulBroadcastReceiver

public abstract class WakefulBroadcastReceiver
extends BroadcastReceiver

java.lang.Object
   ↳ android.content.BroadcastReceiver
     ↳ android.support.v4.content.WakefulBroadcastReceiver


This class was deprecated in API level 26.1.0.
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 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 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.

import android.content.Context;
import android.content.Intent;
import android.os.SystemClock;
import android.support.v4.content.WakefulBroadcastReceiver;
import android.util.Log;

public class SimpleWakefulReceiver extends WakefulBroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // This is the Intent to deliver to our service.
        Intent service = new Intent(context, SimpleWakefulService.class);

        // Start the service, keeping the device awake while it is launching.
        Log.i("SimpleWakefulReceiver", "Starting service @ " + SystemClock.elapsedRealtime());
        startWakefulService(context, service);
    }
}

The service (in this example, an 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.

import android.app.IntentService;
import android.content.Intent;
import android.os.SystemClock;
import android.util.Log;

public class SimpleWakefulService extends IntentService {
    public SimpleWakefulService() {
        super("SimpleWakefulService");
    }

    @Override
    protected void onHandleIntent(Intent intent) {
        // At this point SimpleWakefulReceiver is still holding a wake lock
        // for us.  We can do whatever we need to here and then tell it that
        // it can release the wakelock.  This sample just does some slow work,
        // but more complicated implementations could take their own wake
        // lock here before releasing the receiver's.
        //
        // Note that when using this approach you should be aware that if your
        // service gets killed and restarted while in the middle of such work
        // (so the Intent gets re-delivered to perform the work again), it will
        // at that point no longer be holding a wake lock since we are depending
        // on SimpleWakefulReceiver to that for us.  If this is a concern, you can
        // acquire a separate wake lock here.
        for (int i=0; i<5; i++) {
            Log.i("SimpleWakefulReceiver", "Running service " + (i+1)
                    + "/5 @ " + SystemClock.elapsedRealtime());
            try {
                Thread.sleep(5000);
            } catch (InterruptedException e) {
            }
        }
        Log.i("SimpleWakefulReceiver", "Completed service @ " + SystemClock.elapsedRealtime());
        SimpleWakefulReceiver.completeWakefulIntent(intent);
    }
}

Summary

Public constructors

WakefulBroadcastReceiver()

Public methods

static boolean completeWakefulIntent(Intent intent)

Finish the execution from a previous startWakefulService(Context, Intent).

static ComponentName startWakefulService(Context context, Intent intent)

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

Inherited methods

From class android.content.BroadcastReceiver
From class java.lang.Object

Public constructors

WakefulBroadcastReceiver

added in version 22.1.0
WakefulBroadcastReceiver ()

Public methods

completeWakefulIntent

added in version 22.1.0
boolean completeWakefulIntent (Intent intent)

Finish the execution from a previous startWakefulService(Context, Intent). Any wake lock that was being held will now be released.

Parameters
intent Intent: The Intent as originally generated by startWakefulService(Context, Intent).

Returns
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

added in version 22.1.0
ComponentName startWakefulService (Context context, 
                Intent intent)

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 Intent: The Intent with which to start the service, as per Context.startService.

Returns
ComponentName