1 /*
2  * Copyright (C) 2015 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.app;
18 
19 import android.annotation.RequiresPermission;
20 import android.annotation.SystemApi;
21 import android.os.Build;
22 import android.os.Bundle;
23 
24 /**
25  * Helper class for building an options Bundle that can be used with
26  * {@link android.content.Context#sendBroadcast(android.content.Intent)
27  * Context.sendBroadcast(Intent)} and related methods.
28  * {@hide}
29  */
30 @SystemApi
31 public class BroadcastOptions {
32     private long mTemporaryAppWhitelistDuration;
33     private int mMinManifestReceiverApiLevel = 0;
34     private int mMaxManifestReceiverApiLevel = Build.VERSION_CODES.CUR_DEVELOPMENT;
35     private boolean mDontSendToRestrictedApps = false;
36     private boolean mAllowBackgroundActivityStarts;
37 
38     /**
39      * How long to temporarily put an app on the power whitelist when executing this broadcast
40      * to it.
41      */
42     static final String KEY_TEMPORARY_APP_WHITELIST_DURATION
43             = "android:broadcast.temporaryAppWhitelistDuration";
44 
45     /**
46      * Corresponds to {@link #setMinManifestReceiverApiLevel}.
47      */
48     static final String KEY_MIN_MANIFEST_RECEIVER_API_LEVEL
49             = "android:broadcast.minManifestReceiverApiLevel";
50 
51     /**
52      * Corresponds to {@link #setMaxManifestReceiverApiLevel}.
53      */
54     static final String KEY_MAX_MANIFEST_RECEIVER_API_LEVEL
55             = "android:broadcast.maxManifestReceiverApiLevel";
56 
57     /**
58      * Corresponds to {@link #setDontSendToRestrictedApps}.
59      */
60     static final String KEY_DONT_SEND_TO_RESTRICTED_APPS =
61             "android:broadcast.dontSendToRestrictedApps";
62 
63     /**
64      * Corresponds to {@link #setBackgroundActivityStartsAllowed}.
65      */
66     static final String KEY_ALLOW_BACKGROUND_ACTIVITY_STARTS =
67             "android:broadcast.allowBackgroundActivityStarts";
68 
makeBasic()69     public static BroadcastOptions makeBasic() {
70         BroadcastOptions opts = new BroadcastOptions();
71         return opts;
72     }
73 
BroadcastOptions()74     private BroadcastOptions() {
75     }
76 
77     /** @hide */
BroadcastOptions(Bundle opts)78     public BroadcastOptions(Bundle opts) {
79         mTemporaryAppWhitelistDuration = opts.getLong(KEY_TEMPORARY_APP_WHITELIST_DURATION);
80         mMinManifestReceiverApiLevel = opts.getInt(KEY_MIN_MANIFEST_RECEIVER_API_LEVEL, 0);
81         mMaxManifestReceiverApiLevel = opts.getInt(KEY_MAX_MANIFEST_RECEIVER_API_LEVEL,
82                 Build.VERSION_CODES.CUR_DEVELOPMENT);
83         mDontSendToRestrictedApps = opts.getBoolean(KEY_DONT_SEND_TO_RESTRICTED_APPS, false);
84         mAllowBackgroundActivityStarts = opts.getBoolean(KEY_ALLOW_BACKGROUND_ACTIVITY_STARTS,
85                 false);
86     }
87 
88     /**
89      * Set a duration for which the system should temporary place an application on the
90      * power whitelist when this broadcast is being delivered to it.
91      * @param duration The duration in milliseconds; 0 means to not place on whitelist.
92      */
93     @RequiresPermission(android.Manifest.permission.CHANGE_DEVICE_IDLE_TEMP_WHITELIST)
setTemporaryAppWhitelistDuration(long duration)94     public void setTemporaryAppWhitelistDuration(long duration) {
95         mTemporaryAppWhitelistDuration = duration;
96     }
97 
98     /**
99      * Return {@link #setTemporaryAppWhitelistDuration}.
100      * @hide
101      */
getTemporaryAppWhitelistDuration()102     public long getTemporaryAppWhitelistDuration() {
103         return mTemporaryAppWhitelistDuration;
104     }
105 
106     /**
107      * Set the minimum target API level of receivers of the broadcast.  If an application
108      * is targeting an API level less than this, the broadcast will not be delivered to
109      * them.  This only applies to receivers declared in the app's AndroidManifest.xml.
110      * @hide
111      */
setMinManifestReceiverApiLevel(int apiLevel)112     public void setMinManifestReceiverApiLevel(int apiLevel) {
113         mMinManifestReceiverApiLevel = apiLevel;
114     }
115 
116     /**
117      * Return {@link #setMinManifestReceiverApiLevel}.
118      * @hide
119      */
getMinManifestReceiverApiLevel()120     public int getMinManifestReceiverApiLevel() {
121         return mMinManifestReceiverApiLevel;
122     }
123 
124     /**
125      * Set the maximum target API level of receivers of the broadcast.  If an application
126      * is targeting an API level greater than this, the broadcast will not be delivered to
127      * them.  This only applies to receivers declared in the app's AndroidManifest.xml.
128      * @hide
129      */
setMaxManifestReceiverApiLevel(int apiLevel)130     public void setMaxManifestReceiverApiLevel(int apiLevel) {
131         mMaxManifestReceiverApiLevel = apiLevel;
132     }
133 
134     /**
135      * Return {@link #setMaxManifestReceiverApiLevel}.
136      * @hide
137      */
getMaxManifestReceiverApiLevel()138     public int getMaxManifestReceiverApiLevel() {
139         return mMaxManifestReceiverApiLevel;
140     }
141 
142     /**
143      * Sets whether pending intent can be sent for an application with background restrictions
144      * @param dontSendToRestrictedApps if true, pending intent will not be sent for an application
145      * with background restrictions. Default value is {@code false}
146      */
setDontSendToRestrictedApps(boolean dontSendToRestrictedApps)147     public void setDontSendToRestrictedApps(boolean dontSendToRestrictedApps) {
148         mDontSendToRestrictedApps = dontSendToRestrictedApps;
149     }
150 
151     /**
152      * @hide
153      * @return #setDontSendToRestrictedApps
154      */
isDontSendToRestrictedApps()155     public boolean isDontSendToRestrictedApps() {
156         return mDontSendToRestrictedApps;
157     }
158 
159     /**
160      * Sets the process will be able to start activities from background for the duration of
161      * the broadcast dispatch. Default value is {@code false}
162      */
163     @RequiresPermission(android.Manifest.permission.START_ACTIVITIES_FROM_BACKGROUND)
setBackgroundActivityStartsAllowed(boolean allowBackgroundActivityStarts)164     public void setBackgroundActivityStartsAllowed(boolean allowBackgroundActivityStarts) {
165         mAllowBackgroundActivityStarts = allowBackgroundActivityStarts;
166     }
167 
168     /**
169      * @hide
170      * @return #setAllowBackgroundActivityStarts
171      */
allowsBackgroundActivityStarts()172     public boolean allowsBackgroundActivityStarts() {
173         return mAllowBackgroundActivityStarts;
174     }
175 
176     /**
177      * Returns the created options as a Bundle, which can be passed to
178      * {@link android.content.Context#sendBroadcast(android.content.Intent)
179      * Context.sendBroadcast(Intent)} and related methods.
180      * Note that the returned Bundle is still owned by the BroadcastOptions
181      * object; you must not modify it, but can supply it to the sendBroadcast
182      * methods that take an options Bundle.
183      */
toBundle()184     public Bundle toBundle() {
185         Bundle b = new Bundle();
186         if (mTemporaryAppWhitelistDuration > 0) {
187             b.putLong(KEY_TEMPORARY_APP_WHITELIST_DURATION, mTemporaryAppWhitelistDuration);
188         }
189         if (mMinManifestReceiverApiLevel != 0) {
190             b.putInt(KEY_MIN_MANIFEST_RECEIVER_API_LEVEL, mMinManifestReceiverApiLevel);
191         }
192         if (mMaxManifestReceiverApiLevel != Build.VERSION_CODES.CUR_DEVELOPMENT) {
193             b.putInt(KEY_MAX_MANIFEST_RECEIVER_API_LEVEL, mMaxManifestReceiverApiLevel);
194         }
195         if (mDontSendToRestrictedApps) {
196             b.putBoolean(KEY_DONT_SEND_TO_RESTRICTED_APPS, true);
197         }
198         if (mAllowBackgroundActivityStarts) {
199             b.putBoolean(KEY_ALLOW_BACKGROUND_ACTIVITY_STARTS, true);
200         }
201         return b.isEmpty() ? null : b;
202     }
203 }
204