diff options
| -rw-r--r-- | core/java/android/app/AlarmManager.java | 11 | ||||
| -rw-r--r-- | core/java/android/content/BroadcastReceiver.java | 22 | ||||
| -rw-r--r-- | core/java/android/content/Context.java | 13 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/receiver-element.jd | 21 |
4 files changed, 48 insertions, 19 deletions
diff --git a/core/java/android/app/AlarmManager.java b/core/java/android/app/AlarmManager.java index b4c0e31..53c7935 100644 --- a/core/java/android/app/AlarmManager.java +++ b/core/java/android/app/AlarmManager.java @@ -29,6 +29,17 @@ import android.os.ServiceManager; * if it is not already running. Registered alarms are retained while the * device is asleep (and can optionally wake the device up if they go off * during that time), but will be cleared if it is turned off and rebooted. + * + * <p>The Alarm Manager holds a CPU wake lock as long as the alarm receiver's + * onReceive() method is executing. This guarantees that the phone will not sleep + * until you have finished handling the broadcast. Once onReceive() returns, the + * Alarm Manager releases this wake lock. This means that the phone will in some + * cases sleep as soon as your onReceive() method completes. If your alarm receiver + * called {@link android.content.Context#startService Context.startService()}, it + * is possible that the phone will sleep before the requested service is launched. + * To prevent this, your BroadcastReceiver and Service will need to implement a + * separate wake lock policy to ensure that the phone continues running until the + * service becomes available. * * <p><b>Note: The Alarm Manager is intended for cases where you want to have * your application code run at a specific time, even if your application is diff --git a/core/java/android/content/BroadcastReceiver.java b/core/java/android/content/BroadcastReceiver.java index a41627a..b391c57 100644 --- a/core/java/android/content/BroadcastReceiver.java +++ b/core/java/android/content/BroadcastReceiver.java @@ -44,14 +44,14 @@ import android.util.Log; * <ul> * <li> <b>Normal broadcasts</b> (sent with {@link Context#sendBroadcast(Intent) * Context.sendBroadcast}) are completely asynchronous. All receivers of the - * broadcast are run, in an undefined order, often at the same time. This is - * more efficient, but means that receivers can not use the result or abort + * broadcast are run in an undefined order, often at the same time. This is + * more efficient, but means that receivers cannot use the result or abort * APIs included here. * <li> <b>Ordered broadcasts</b> (sent with {@link Context#sendOrderedBroadcast(Intent, String) * Context.sendOrderedBroadcast}) are delivered to one receiver at a time. * As each receiver executes in turn, it can propagate a result to the next * receiver, or it can completely abort the broadcast so that it won't be passed - * to other receivers. The order receivers runs in can be controlled with the + * to other receivers. The order receivers run in can be controlled with the * {@link android.R.styleable#AndroidManifestIntentFilter_priority * android:priority} attribute of the matching intent-filter; receivers with * the same priority will be run in an arbitrary order. @@ -61,8 +61,8 @@ import android.util.Log; * situations revert to delivering the broadcast one receiver at a time. In * particular, for receivers that may require the creation of a process, only * one will be run at a time to avoid overloading the system with new processes. - * In this situation, however, the non-ordered semantics hold: these receivers - * can not return results or abort their broadcast.</p> + * In this situation, however, the non-ordered semantics hold: these receivers still + * cannot return results or abort their broadcast.</p> * * <p>Note that, although the Intent class is used for sending and receiving * these broadcasts, the Intent broadcast mechanism here is completely separate @@ -156,7 +156,7 @@ import android.util.Log; * more important processes. * * <p>This means that for longer-running operations you will often use - * an {@link android.app.Service} in conjunction with a BroadcastReceiver to keep + * a {@link android.app.Service} in conjunction with a BroadcastReceiver to keep * the containing process active for the entire time of your operation. */ public abstract class BroadcastReceiver { @@ -167,7 +167,7 @@ public abstract class BroadcastReceiver { * This method is called when the BroadcastReceiver is receiving an Intent * broadcast. During this time you can use the other methods on * BroadcastReceiver to view/modify the current result values. The function - * is normally called from the main thread of its process, so you should + * is normally called within the main thread of its process, so you should * never perform long-running operations in it (there is a timeout of * 10 seconds that the system allows before considering the receiver to * be blocked and a candidate to be killed). You cannot launch a popup dialog @@ -183,6 +183,14 @@ public abstract class BroadcastReceiver { * to interact with a service that is already running, you can use * {@link #peekService}. * + * <p>The Intent filters used in {@link android.content.Context#registerReceiver} + * and in application manifests are <em>not</em> guaranteed to be exclusive. They + * are hints to the operating system about how to find suitable recipients. It is + * possible for senders to force delivery to specific recipients, bypassing filter + * resolution. For this reason, {@link #onReceive(Context, Intent) onReceive()} + * implementations should respond only to known actions, ignoring any unexpected + * Intents that they may receive. + * * @param context The Context in which the receiver is running. * @param intent The Intent being received. */ diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java index 9a0dc9f..600dfa4 100644 --- a/core/java/android/content/Context.java +++ b/core/java/android/content/Context.java @@ -738,7 +738,7 @@ public abstract class Context { public abstract void removeStickyBroadcast(Intent intent); /** - * Register an BroadcastReceiver to be run in the main activity thread. The + * Register a BroadcastReceiver to be run in the main activity thread. The * <var>receiver</var> will be called with any broadcast Intent that * matches <var>filter</var>, in the main application thread. * @@ -762,11 +762,12 @@ public abstract class Context { * * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. * - * <p class="note">Note: this method <em>can not be called from an - * {@link BroadcastReceiver} component</em>. It is okay, however, to use - * this method from another BroadcastReceiver that has itself been registered with - * {@link #registerReceiver}, since the lifetime of such an BroadcastReceiver - * is tied to another object (the one that registered it).</p> + * <p class="note">Note: this method <em>cannot be called from a + * {@link BroadcastReceiver} component;</em> that is, from a BroadcastReceiver + * that is declared in an application's manifest. It is okay, however, to call + * this method from another BroadcastReceiver that has itself been registered + * at run time with {@link #registerReceiver}, since the lifetime of such a + * registered BroadcastReceiver is tied to the object that registered it.</p> * * @param receiver The BroadcastReceiver to handle the broadcast. * @param filter Selects the Intent broadcasts to be received. diff --git a/docs/html/guide/topics/manifest/receiver-element.jd b/docs/html/guide/topics/manifest/receiver-element.jd index 777d016..8df6273 100644 --- a/docs/html/guide/topics/manifest/receiver-element.jd +++ b/docs/html/guide/topics/manifest/receiver-element.jd @@ -17,7 +17,7 @@ page.title=<receiver> <dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> <dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filer></a></code> +<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> <br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> <dt>description:</dt> @@ -47,10 +47,16 @@ The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">< <code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all application components, including broadcast receivers. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and -{@code <receiver>} attributes must both be "{@code true}" for -the broadcast receiver to be enabled. If either is "{@code false}", it is -disabled; it cannot be instantiated. -</p></dd> +{@code <receiver>} elements must both set {@code android:enabled} equal to +"{@code true}" for the broadcast receiver to be enabled. If either is "{@code false}", +the receiver is disabled and cannot be instantiated. +</p> + +<p> +The default value depends on whether the broadcast receiver contains intent filters. +If any intent filters are specified, the default value is "{@code true}". If no +filters are specified, the default value is "{@code false}". +</dd> <dt><a name="exported"></a>{@code android:exported}</dt> <dd>Whether or not the broadcast receiver can receive messages from sources @@ -117,9 +123,12 @@ it can also be set as a raw string. {@link android.content.BroadcastReceiver}. This should be a fully qualified class name (such as, "{@code com.example.project.ReportReceiver}"). However, as a shorthand, if the first character of the name is a period (for example, -"{@code . ReportReceiver}"), it is appended to the package name specified in +"{@code .ReportReceiver}"), it is appended to the package name specified in the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. +<p>The {@link android.content.BroadcastReceiver} subclass can be a static inner +class, although it cannot be an ordinary (non-static) inner class. + <p> There is no default. The name must be specified. </p></dd> |