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