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 
37     /**
38      * How long to temporarily put an app on the power whitelist when executing this broadcast
39      * to it.
40      */
41     static final String KEY_TEMPORARY_APP_WHITELIST_DURATION
42             = "android:broadcast.temporaryAppWhitelistDuration";
43 
44     /**
45      * Corresponds to {@link #setMinManifestReceiverApiLevel}.
46      */
47     static final String KEY_MIN_MANIFEST_RECEIVER_API_LEVEL
48             = "android:broadcast.minManifestReceiverApiLevel";
49 
50     /**
51      * Corresponds to {@link #setMaxManifestReceiverApiLevel}.
52      */
53     static final String KEY_MAX_MANIFEST_RECEIVER_API_LEVEL
54             = "android:broadcast.maxManifestReceiverApiLevel";
55 
56     /**
57      * Corresponds to {@link #setMaxManifestReceiverApiLevel}.
58      */
59     static final String KEY_DONT_SEND_TO_RESTRICTED_APPS =
60             "android:broadcast.dontSendToRestrictedApps";
61 
makeBasic()62     public static BroadcastOptions makeBasic() {
63         BroadcastOptions opts = new BroadcastOptions();
64         return opts;
65     }
66 
BroadcastOptions()67     private BroadcastOptions() {
68     }
69 
70     /** @hide */
BroadcastOptions(Bundle opts)71     public BroadcastOptions(Bundle opts) {
72         mTemporaryAppWhitelistDuration = opts.getLong(KEY_TEMPORARY_APP_WHITELIST_DURATION);
73         mMinManifestReceiverApiLevel = opts.getInt(KEY_MIN_MANIFEST_RECEIVER_API_LEVEL, 0);
74         mMaxManifestReceiverApiLevel = opts.getInt(KEY_MAX_MANIFEST_RECEIVER_API_LEVEL,
75                 Build.VERSION_CODES.CUR_DEVELOPMENT);
76         mDontSendToRestrictedApps = opts.getBoolean(KEY_DONT_SEND_TO_RESTRICTED_APPS, false);
77     }
78 
79     /**
80      * Set a duration for which the system should temporary place an application on the
81      * power whitelist when this broadcast is being delivered to it.
82      * @param duration The duration in milliseconds; 0 means to not place on whitelist.
83      */
84     @RequiresPermission(android.Manifest.permission.CHANGE_DEVICE_IDLE_TEMP_WHITELIST)
setTemporaryAppWhitelistDuration(long duration)85     public void setTemporaryAppWhitelistDuration(long duration) {
86         mTemporaryAppWhitelistDuration = duration;
87     }
88 
89     /**
90      * Return {@link #setTemporaryAppWhitelistDuration}.
91      * @hide
92      */
getTemporaryAppWhitelistDuration()93     public long getTemporaryAppWhitelistDuration() {
94         return mTemporaryAppWhitelistDuration;
95     }
96 
97     /**
98      * Set the minimum target API level of receivers of the broadcast.  If an application
99      * is targeting an API level less than this, the broadcast will not be delivered to
100      * them.  This only applies to receivers declared in the app's AndroidManifest.xml.
101      * @hide
102      */
setMinManifestReceiverApiLevel(int apiLevel)103     public void setMinManifestReceiverApiLevel(int apiLevel) {
104         mMinManifestReceiverApiLevel = apiLevel;
105     }
106 
107     /**
108      * Return {@link #setMinManifestReceiverApiLevel}.
109      * @hide
110      */
getMinManifestReceiverApiLevel()111     public int getMinManifestReceiverApiLevel() {
112         return mMinManifestReceiverApiLevel;
113     }
114 
115     /**
116      * Set the maximum target API level of receivers of the broadcast.  If an application
117      * is targeting an API level greater than this, the broadcast will not be delivered to
118      * them.  This only applies to receivers declared in the app's AndroidManifest.xml.
119      * @hide
120      */
setMaxManifestReceiverApiLevel(int apiLevel)121     public void setMaxManifestReceiverApiLevel(int apiLevel) {
122         mMaxManifestReceiverApiLevel = apiLevel;
123     }
124 
125     /**
126      * Return {@link #setMaxManifestReceiverApiLevel}.
127      * @hide
128      */
getMaxManifestReceiverApiLevel()129     public int getMaxManifestReceiverApiLevel() {
130         return mMaxManifestReceiverApiLevel;
131     }
132 
133     /**
134      * Sets whether pending intent can be sent for an application with background restrictions
135      * @param dontSendToRestrictedApps if true, pending intent will not be sent for an application
136      * with background restrictions. Default value is {@code false}
137      */
setDontSendToRestrictedApps(boolean dontSendToRestrictedApps)138     public void setDontSendToRestrictedApps(boolean dontSendToRestrictedApps) {
139         mDontSendToRestrictedApps = dontSendToRestrictedApps;
140     }
141 
142     /**
143      * @hide
144      * @return #setDontSendToRestrictedApps
145      */
isDontSendToRestrictedApps()146     public boolean isDontSendToRestrictedApps() {
147         return mDontSendToRestrictedApps;
148     }
149 
150     /**
151      * Returns the created options as a Bundle, which can be passed to
152      * {@link android.content.Context#sendBroadcast(android.content.Intent)
153      * Context.sendBroadcast(Intent)} and related methods.
154      * Note that the returned Bundle is still owned by the BroadcastOptions
155      * object; you must not modify it, but can supply it to the sendBroadcast
156      * methods that take an options Bundle.
157      */
toBundle()158     public Bundle toBundle() {
159         Bundle b = new Bundle();
160         if (mTemporaryAppWhitelistDuration > 0) {
161             b.putLong(KEY_TEMPORARY_APP_WHITELIST_DURATION, mTemporaryAppWhitelistDuration);
162         }
163         if (mMinManifestReceiverApiLevel != 0) {
164             b.putInt(KEY_MIN_MANIFEST_RECEIVER_API_LEVEL, mMinManifestReceiverApiLevel);
165         }
166         if (mMaxManifestReceiverApiLevel != Build.VERSION_CODES.CUR_DEVELOPMENT) {
167             b.putInt(KEY_MAX_MANIFEST_RECEIVER_API_LEVEL, mMaxManifestReceiverApiLevel);
168         }
169         if (mDontSendToRestrictedApps) {
170             b.putBoolean(KEY_DONT_SEND_TO_RESTRICTED_APPS, true);
171         }
172         return b.isEmpty() ? null : b;
173     }
174 }
175