FileDocCategorySizeDatePackage
WakefulBroadcastReceiver.javaAPI DocAndroid 5.1 API5956Thu Mar 12 22:22:56 GMT 2015android.support.v4.content

WakefulBroadcastReceiver

public abstract class WakefulBroadcastReceiver extends android.content.BroadcastReceiver
Helper for the common pattern of implementing a {@link BroadcastReceiver} that receives a device wakeup event and then passes the work off to a {@link 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 {@link android.Manifest.permission#WAKE_LOCK} permission to use it.

Example

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

{@sample development/samples/Support4Demos/src/com/example/android/supportv4/content/SimpleWakefulReceiver.java complete}

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

{@sample development/samples/Support4Demos/src/com/example/android/supportv4/content/SimpleWakefulService.java complete}

Fields Summary
private static final String
EXTRA_WAKE_LOCK_ID
private static final android.util.SparseArray
mActiveWakeLocks
private static int
mNextId
Constructors Summary
Methods Summary
public static booleancompleteWakefulIntent(android.content.Intent intent)
Finish the execution from a previous {@link #startWakefulService}. Any wake lock that was being held will now be released.

param
intent The Intent as originally generated by {@link #startWakefulService}.
return
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.

        final int id = intent.getIntExtra(EXTRA_WAKE_LOCK_ID, 0);
        if (id == 0) {
            return false;
        }
        synchronized (mActiveWakeLocks) {
            PowerManager.WakeLock wl = mActiveWakeLocks.get(id);
            if (wl != null) {
                wl.release();
                mActiveWakeLocks.remove(id);
                return true;
            }
            // We return true whether or not we actually found the wake lock
            // the return code is defined to indicate whether the Intent contained
            // an identifier for a wake lock that it was supposed to match.
            // We just log a warning here if there is no wake lock found, which could
            // happen for example if this function is called twice on the same
            // intent or the process is killed and restarted before processing the intent.
            Log.w("WakefulBroadcastReceiver", "No active wake lock id #" + id);
            return true;
        }
public static android.content.ComponentNamestartWakefulService(android.content.Context context, android.content.Intent intent)
Do a {@link android.content.Context#startService(android.content.Intent) 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 {@link android.app.Service#onStartCommand Service.onStartCommand}, it should pass back the Intent it receives there to {@link #completeWakefulIntent(android.content.Intent)} in order to release the wake lock.

param
context The Context in which it operate.
param
intent The Intent with which to start the service, as per {@link android.content.Context#startService(android.content.Intent) Context.startService}.


                                                                                       
           
        synchronized (mActiveWakeLocks) {
            int id = mNextId;
            mNextId++;
            if (mNextId <= 0) {
                mNextId = 1;
            }

            intent.putExtra(EXTRA_WAKE_LOCK_ID, id);
            ComponentName comp = context.startService(intent);
            if (comp == null) {
                return null;
            }

            PowerManager pm = (PowerManager)context.getSystemService(Context.POWER_SERVICE);
            PowerManager.WakeLock wl = pm.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK,
                    "wake:" + comp.flattenToShortString());
            wl.setReferenceCounted(false);
            wl.acquire(60*1000);
            mActiveWakeLocks.put(id, wl);
            return comp;
        }