Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

AI 144405: am: CL 144307 am: CL 144306 Fix SDK issue 1716562 - Broadcast mechanism documentation should be improved.

Browse Source 
Original author: ctate
  Merged from: //branches/cupcake/...
  Original author: android-build

Automated import of CL 144405
This commit is contained in:
Chris Tate
2009-04-02 23:15:58 -07:00
committed by The Android Open Source Project
parent 5cb6f988b2
commit a34df8a2ba
4 changed files with 48 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
core/java/android/app/AlarmManager.java
View File

@@ -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

22
core/java/android/content/BroadcastReceiver.java
View File

@@ -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.
*/

13
core/java/android/content/Context.java
View File

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

21
docs/html/guide/topics/manifest/receiver-element.jd
View File

@@ -17,7 +17,7 @@ page.title=&lt;receiver&gt;
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filer&gt;</a></code>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></dd>
<dt>description:</dt>
@@ -47,10 +47,16 @@ The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt
<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">&lt;application&gt;</a></code> and
{@code &lt;receiver&gt;} 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 &lt;receiver&gt;} 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">&lt;manifest&gt;</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>