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