WakefulBroadcastReceiver

Class Overview

Helper for the common 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.

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

[Expand] Inherited Methods
From class android.content.BroadcastReceiver final void abortBroadcast () Sets the flag indicating that this receiver should abort the current broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast . final void clearAbortBroadcast () Clears the flag indicating that this receiver should abort the current broadcast. final boolean getAbortBroadcast () Returns the flag indicating whether or not this receiver should abort the current broadcast. final boolean getDebugUnregister () Return the last value given to setDebugUnregister(boolean) . final int getResultCode () Retrieve the current result code, as set by the previous receiver. final String getResultData () Retrieve the current result data, as set by the previous receiver. final Bundle getResultExtras (boolean makeMap) Retrieve the current result extra data, as set by the previous receiver. final BroadcastReceiver.PendingResult goAsync () This can be called by an application in onReceive(Context, Intent) to allow it to keep the broadcast active after returning from that function. final boolean isInitialStickyBroadcast () Returns true if the receiver is currently processing the initial value of a sticky broadcast -- that is, the value that was last broadcast and is currently held in the sticky cache, so this is not directly the result of a broadcast right now. final boolean isOrderedBroadcast () Returns true if the receiver is currently processing an ordered broadcast. abstract void onReceive ( Context context, Intent intent) This method is called when the BroadcastReceiver is receiving an Intent broadcast. IBinder peekService ( Context myContext, Intent service) Provide a binder to an already-running service. final void setDebugUnregister (boolean debug) Control inclusion of debugging help for mismatched calls to Context.registerReceiver() . final void setOrderedHint (boolean isOrdered) For internal use, sets the hint about whether this BroadcastReceiver is running in ordered mode. final void setResult (int code, String data, Bundle extras) Change all of the result data returned from this broadcasts; only works with broadcasts sent through Context.sendOrderedBroadcast . final void setResultCode (int code) Change the current result code of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast . final void setResultData ( String data) Change the current result data of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast . final void setResultExtras ( Bundle extras) Change the current result extras of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast .
From class java.lang.Object Object clone () Creates and returns a copy of this Object . boolean equals ( Object o) Compares this instance with the specified object and indicates if they are equal. void finalize () Invoked when the garbage collector has detected that this instance is no longer reachable. final Class <?> getClass () Returns the unique instance of Class that represents this object's class. int hashCode () Returns an integer hash code for this object. final void notify () Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll () Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString () Returns a string containing a concise, human-readable description of this object. final void wait () Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait (long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait (long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.