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

Commit 4a85611d authored by Michael Groover's avatar Michael Groover
Browse files

Update docs to reflect new receiver flag enforcement 

Android T allows apps to declare a runtime receiver as not exported
by invoking registerReceiver with a new RECEIVER_NOT_EXPORTED flag;
receivers registered with this flag will only receive broadcasts from
the platform and the app itself. However to ensure developers can
properly protect their receivers, all apps targeting U or later
registering a receiver for non-system broadcasts must specify either
the exported or not exported flag when invoking #registerReceiver.
This commit updates the docs to reflect this new requirement.

Bug: 234659204
Test: m -j offline-sdk-docs
Change-Id: I86fe8b66f963064db7420bebb502c2d125327bc0
parent 35feccef

core/java/android/content/Context.java

+56 −41
Original line number Diff line number Diff line
@@ -3045,6 +3045,14 @@ public abstract class Context { 
     * Prior to that, it would be ignored and delivered to all matching registered

     * receivers.  Be careful if using this for security.</p>

     *

     * <p>For apps targeting {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE},

     * either {@link #RECEIVER_EXPORTED} or {@link #RECEIVER_NOT_EXPORTED} must be

     * specified if the receiver is not being registered for <a

     * href="{@docRoot}guide/components/broadcasts#system-broadcasts">system broadcasts</a>

     * or a {@link SecurityException} will be thrown. See {@link

     * #registerReceiver(BroadcastReceiver, IntentFilter, int)} to register a receiver with

     * flags.

     *

     * <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
@@ -3084,16 +3092,16 @@ public abstract class Context { 
     *

     * @param receiver The BroadcastReceiver to handle the broadcast.

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

     * @param flags Additional options for the receiver. In a future release, either

     * {@link #RECEIVER_EXPORTED} or {@link #RECEIVER_NOT_EXPORTED} must be specified if the

     *             receiver isn't being registered for <a href="{@docRoot}guide/components

     *              /broadcasts#system-broadcasts">system broadcasts</a> or an exception will be

     *              thrown. If {@link #RECEIVER_EXPORTED} is specified, a receiver may additionally

     *              specify {@link #RECEIVER_VISIBLE_TO_INSTANT_APPS}. For a complete list of

     *              system broadcast actions, see the BROADCAST_ACTIONS.TXT file in the

     *              Android SDK. If both {@link #RECEIVER_EXPORTED} and

     *              {@link #RECEIVER_NOT_EXPORTED} are specified, an exception will be thrown as

     *              well.

     * @param flags Additional options for the receiver. For apps targeting {@link

     *      android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE} either {@link #RECEIVER_EXPORTED} or

     *      {@link #RECEIVER_NOT_EXPORTED} must be specified if the receiver isn't being registered

     *      for <a href="{@docRoot}guide/components/broadcasts#system-broadcasts">system

     *      broadcasts</a> or a {@link SecurityException} will be thrown. If {@link

     *      #RECEIVER_EXPORTED} is specified, a receiver may additionally specify {@link

     *      #RECEIVER_VISIBLE_TO_INSTANT_APPS}. For a complete list of system broadcast actions,

     *      see the BROADCAST_ACTIONS.TXT file in the Android SDK. If both {@link

     *      #RECEIVER_EXPORTED} and {@link #RECEIVER_NOT_EXPORTED} are specified, an {@link

     *      IllegalArgumentException} will be thrown.

     *

     * @return The first sticky intent found that matches <var>filter</var>,

     *         or null if there are none.
@@ -3123,6 +3131,14 @@ public abstract class Context { 
     * Prior to that, it would be ignored and delivered to all matching registered

     * receivers.  Be careful if using this for security.</p>

     *

     * <p>For apps targeting {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE},

     * either {@link #RECEIVER_EXPORTED} or {@link #RECEIVER_NOT_EXPORTED} must be

     * specified if the receiver is not being registered for <a

     * href="{@docRoot}guide/components/broadcasts#system-broadcasts">system broadcasts</a>

     * or a {@link SecurityException} will be thrown. See {@link

     * #registerReceiver(BroadcastReceiver, IntentFilter, String, Handler, int)} to register a

     * receiver with flags.

     *

     * @param receiver The BroadcastReceiver to handle the broadcast.

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

     * @param broadcastPermission String naming a permissions that a
@@ -3165,17 +3181,16 @@ public abstract class Context { 
     *      no permission is required.

     * @param scheduler Handler identifying the thread that will receive

     *      the Intent.  If null, the main thread of the process will be used.

     * @param flags Additional options for the receiver. In a future release, either

     * {@link #RECEIVER_EXPORTED} or {@link #RECEIVER_NOT_EXPORTED} must be specified if the

     *             receiver isn't being registered for <a href="{@docRoot}guide/components

     *              /broadcasts#system-broadcasts">system broadcasts</a> or an exception will be

     *              thrown. If {@link #RECEIVER_EXPORTED} is specified, a receiver may additionally

     *              specify {@link #RECEIVER_VISIBLE_TO_INSTANT_APPS}. For a complete list of

     *              system broadcast actions, see the BROADCAST_ACTIONS.TXT file in the

     *              Android SDK. If both {@link #RECEIVER_EXPORTED} and

     *              {@link #RECEIVER_NOT_EXPORTED} are specified, an exception will be thrown as

     *              well.

     *

     * @param flags Additional options for the receiver. For apps targeting {@link

     *      android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE} either {@link #RECEIVER_EXPORTED} or

     *      {@link #RECEIVER_NOT_EXPORTED} must be specified if the receiver isn't being registered

     *      for <a href="{@docRoot}guide/components/broadcasts#system-broadcasts">system

     *      broadcasts</a> or a {@link SecurityException} will be thrown. If {@link

     *      #RECEIVER_EXPORTED} is specified, a receiver may additionally specify {@link

     *      #RECEIVER_VISIBLE_TO_INSTANT_APPS}. For a complete list of system broadcast actions,

     *      see the BROADCAST_ACTIONS.TXT file in the Android SDK. If both {@link

     *      #RECEIVER_EXPORTED} and {@link #RECEIVER_NOT_EXPORTED} are specified, an {@link

     *      IllegalArgumentException} will be thrown.

     * @return The first sticky intent found that matches <var>filter</var>,

     *         or null if there are none.

     *
@@ -3233,16 +3248,16 @@ public abstract class Context { 
     *      no permission is required.

     * @param scheduler Handler identifying the thread that will receive

     *      the Intent. If {@code null}, the main thread of the process will be used.

     * @param flags Additional options for the receiver. In a future release, either

     * {@link #RECEIVER_EXPORTED} or {@link #RECEIVER_NOT_EXPORTED} must be specified if the

     *             receiver isn't being registered for <a href="{@docRoot}guide/components

     *              /broadcasts#system-broadcasts">system broadcasts</a> or an exception will be

     *              thrown. If {@link #RECEIVER_EXPORTED} is specified, a receiver may additionally

     *              specify {@link #RECEIVER_VISIBLE_TO_INSTANT_APPS}. For a complete list of

     *              system broadcast actions, see the BROADCAST_ACTIONS.TXT file in the

     *              Android SDK. If both {@link #RECEIVER_EXPORTED} and

     *              {@link #RECEIVER_NOT_EXPORTED} are specified, an exception will be thrown as

     *              well.

     * @param flags Additional options for the receiver. For apps targeting {@link

     *      android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE} either {@link #RECEIVER_EXPORTED} or

     *      {@link #RECEIVER_NOT_EXPORTED} must be specified if the receiver isn't being registered

     *      for <a href="{@docRoot}guide/components/broadcasts#system-broadcasts">system

     *      broadcasts</a> or a {@link SecurityException} will be thrown. If {@link

     *      #RECEIVER_EXPORTED} is specified, a receiver may additionally specify {@link

     *      #RECEIVER_VISIBLE_TO_INSTANT_APPS}. For a complete list of system broadcast actions,

     *      see the BROADCAST_ACTIONS.TXT file in the Android SDK. If both {@link

     *      #RECEIVER_EXPORTED} and {@link #RECEIVER_NOT_EXPORTED} are specified, an {@link

     *      IllegalArgumentException} will be thrown.

     *

     * @return The first sticky intent found that matches <var>filter</var>,

     *         or {@code null} if there are none.
@@ -3306,16 +3321,16 @@ public abstract class Context { 
     *      no permission is required.

     * @param scheduler Handler identifying the thread that will receive

     *      the Intent.  If null, the main thread of the process will be used.

     * @param flags Additional options for the receiver. In a future release, either

     * {@link #RECEIVER_EXPORTED} or {@link #RECEIVER_NOT_EXPORTED} must be specified if the

     *             receiver isn't being registered for <a href="{@docRoot}guide/components

     *              /broadcasts#system-broadcasts">system broadcasts</a> or an exception will be

     *              thrown. If {@link #RECEIVER_EXPORTED} is specified, a receiver may additionally

     *              specify {@link #RECEIVER_VISIBLE_TO_INSTANT_APPS}. For a complete list of

     *              system broadcast actions, see the BROADCAST_ACTIONS.TXT file in the

     *              Android SDK. If both {@link #RECEIVER_EXPORTED} and

     *              {@link #RECEIVER_NOT_EXPORTED} are specified, an exception will be thrown as

     *              well.

     * @param flags Additional options for the receiver. For apps targeting {@link

     *      android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE} either {@link #RECEIVER_EXPORTED} or

     *      {@link #RECEIVER_NOT_EXPORTED} must be specified if the receiver isn't being registered

     *      for <a href="{@docRoot}guide/components/broadcasts#system-broadcasts">system

     *      broadcasts</a> or a {@link SecurityException} will be thrown. If {@link

     *      #RECEIVER_EXPORTED} is specified, a receiver may additionally specify {@link

     *      #RECEIVER_VISIBLE_TO_INSTANT_APPS}. For a complete list of system broadcast actions,

     *      see the BROADCAST_ACTIONS.TXT file in the Android SDK. If both {@link

     *      #RECEIVER_EXPORTED} and {@link #RECEIVER_NOT_EXPORTED} are specified, an {@link

     *      IllegalArgumentException} will be thrown.

     *

     * @return The first sticky intent found that matches <var>filter</var>,

     *         or null if there are none.