Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a34df8a2 authored by Chris Tate's avatar Chris Tate Committed by The Android Open Source Project
Browse files

AI 144405: am: CL 144307 am: CL 144306 Fix SDK issue 1716562 - Broadcast... 

AI 144405: am: CL 144307 am: CL 144306 Fix SDK issue 1716562 - Broadcast mechanism documentation should be improved.
  Original author: ctate
  Merged from: //branches/cupcake/...
  Original author: android-build

Automated import of CL 144405
parent 5cb6f988

core/java/android/app/AlarmManager.java

+11 −0
Original line number Original line Diff line number Diff line
@@ -30,6 +30,17 @@ import android.os.ServiceManager; 
 * device is asleep (and can optionally wake the device up if they go off

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

 * 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

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

 * your application code run at a specific time, even if your application is

 * not currently running.  For normal timing operations (ticks, timeouts,

 * not currently running.  For normal timing operations (ticks, timeouts,

core/java/android/content/BroadcastReceiver.java

+15 −7
Original line number Original line Diff line number Diff line
@@ -44,14 +44,14 @@ import android.util.Log; 
 * <ul>

 * <ul>

 * <li> <b>Normal broadcasts</b> (sent with {@link Context#sendBroadcast(Intent)

 * <li> <b>Normal broadcasts</b> (sent with {@link Context#sendBroadcast(Intent)

 * Context.sendBroadcast}) are completely asynchronous.  All receivers of the

 * Context.sendBroadcast}) are completely asynchronous.  All receivers of the

 * broadcast are run, in an undefined order, often at the same time.  This is

 * 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

 * more efficient, but means that receivers cannot use the result or abort

 * APIs included here.

 * APIs included here.

 * <li> <b>Ordered broadcasts</b> (sent with {@link Context#sendOrderedBroadcast(Intent, String)

 * <li> <b>Ordered broadcasts</b> (sent with {@link Context#sendOrderedBroadcast(Intent, String)

 * Context.sendOrderedBroadcast}) are delivered to one receiver at a time.

 * Context.sendOrderedBroadcast}) are delivered to one receiver at a time.

 * As each receiver executes in turn, it can propagate a result to the next

 * 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

 * 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

 * {@link android.R.styleable#AndroidManifestIntentFilter_priority

 * android:priority} attribute of the matching intent-filter; receivers with

 * android:priority} attribute of the matching intent-filter; receivers with

 * the same priority will be run in an arbitrary order.

 * the same priority will be run in an arbitrary order.
@@ -61,7 +61,7 @@ import android.util.Log; 
 * situations revert to delivering the broadcast one receiver at a time.  In

 * situations revert to delivering the broadcast one receiver at a time.  In

 * particular, for receivers that may require the creation of a process, only

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

 * 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

 * In this situation, however, the non-ordered semantics hold: these receivers still

 * cannot return results or abort their broadcast.</p>

 * cannot return results or abort their broadcast.</p>

 * 

 * 

 * <p>Note that, although the Intent class is used for sending and receiving

 * <p>Note that, although the Intent class is used for sending and receiving
@@ -156,7 +156,7 @@ import android.util.Log; 
 * more important processes.

 * more important processes.

 * 

 * 

 * <p>This means that for longer-running operations you will often use

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

 * the containing process active for the entire time of your operation.

 */

 */

public abstract class BroadcastReceiver {

public abstract class BroadcastReceiver {
@@ -167,7 +167,7 @@ public abstract class BroadcastReceiver { 
     * This method is called when the BroadcastReceiver is receiving an Intent

     * This method is called when the BroadcastReceiver is receiving an Intent

     * broadcast.  During this time you can use the other methods on

     * broadcast.  During this time you can use the other methods on

     * BroadcastReceiver to view/modify the current result values.  The function

     * 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

     * never perform long-running operations in it (there is a timeout of

     * 10 seconds that the system allows before considering the receiver to

     * 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

     * 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

     * to interact with a service that is already running, you can use

     * {@link #peekService}.

     * {@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 context The Context in which the receiver is running.

     * @param intent The Intent being received.

     * @param intent The Intent being received.

     */

     */

core/java/android/content/Context.java

+7 −6
Original line number Original line Diff line number Diff line
@@ -738,7 +738,7 @@ public abstract class Context { 
    public abstract void removeStickyBroadcast(Intent intent);

    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

     * <var>receiver</var> will be called with any broadcast Intent that

     * matches <var>filter</var>, in the main application thread.

     * 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>See {@link BroadcastReceiver} for more information on Intent broadcasts.

     *

     *

     * <p class="note">Note: this method <em>can not be called from an

     * <p class="note">Note: this method <em>cannot be called from a

     * {@link BroadcastReceiver} component</em>.  It is okay, however, to use

     * {@link BroadcastReceiver} component;</em> that is, from a BroadcastReceiver

     * this method from another BroadcastReceiver that has itself been registered with

     * that is declared in an application's manifest.  It is okay, however, to call

     * {@link #registerReceiver}, since the lifetime of such an BroadcastReceiver

     * this method from another BroadcastReceiver that has itself been registered

     * is tied to another object (the one that registered it).</p>

     * 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 receiver The BroadcastReceiver to handle the broadcast.

     * @param filter Selects the Intent broadcasts to be received.

     * @param filter Selects the Intent broadcasts to be received.

docs/html/guide/topics/manifest/receiver-element.jd

+15 −6
Original line number Original line Diff line number Diff line
@@ -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>

<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>





<dt>can contain:</dt>

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

<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></dd>





<dt>description:</dt>

<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 

<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 

application components, including broadcast receivers.  The 

<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> and

<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 

{@code &lt;receiver&gt;} elements must both set {@code android:enabled} equal to

the broadcast receiver to be enabled.  If either is "{@code false}", it is

"{@code true}" for the broadcast receiver to be enabled.  If either is "{@code false}",

disabled; it cannot be instantiated.

the receiver is disabled and cannot be instantiated.

</p></dd>

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

<dt><a name="exported"></a>{@code android:exported}</dt>

<dd>Whether or not the broadcast receiver can receive messages from sources 

<dd>Whether or not the broadcast receiver can receive messages from sources
@@ -120,6 +126,9 @@ 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.  

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>

<p>

There is no default.  The name must be specified.

There is no default.  The name must be specified.

</p></dd>

</p></dd>