1 /* 2 * Copyright (C) 2010 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.provider; 18 19 import android.annotation.SdkConstant; 20 import android.annotation.SdkConstant.SdkConstantType; 21 22 /** 23 * The AlarmClock provider contains an Intent action and extras that can be used 24 * to start an Activity to set a new alarm or timer in an alarm clock application. 25 * 26 * Applications that wish to receive the ACTION_SET_ALARM and ACTION_SET_TIMER Intents 27 * should create an activity to handle the Intent that requires the permission 28 * com.android.alarm.permission.SET_ALARM. Applications that wish to create a 29 * new alarm or timer should use 30 * {@link android.content.Context#startActivity Context.startActivity()} so that 31 * the user has the option of choosing which alarm clock application to use. 32 * 33 * Android TV devices may not support the alarm intents. 34 */ 35 public final class AlarmClock { 36 /** 37 * Activity Action: Set an alarm. 38 * <p> 39 * Activates an existing alarm or creates a new one. 40 * </p><p> 41 * This action requests an alarm to be set for a given time of day. If no time of day is 42 * specified, an implementation should start an activity that is capable of setting an alarm 43 * ({@link #EXTRA_SKIP_UI} is ignored in this case). If a time of day is specified, and 44 * {@link #EXTRA_SKIP_UI} is {@code true}, and the alarm is not repeating, the implementation 45 * should remove this alarm after it has been dismissed. If an identical alarm exists matching 46 * all parameters, the implementation may re-use it instead of creating a new one (in this case, 47 * the alarm should not be removed after dismissal). 48 * </p><p> 49 * This action always enables the alarm. 50 * </p><p> 51 * This activity could also be started in Voice Interaction mode. The activity should check 52 * {@link android.app.Activity#isVoiceInteraction}, and if true, the implementation should 53 * report a deeplink of the created/enabled alarm using 54 * {@link android.app.VoiceInteractor.CompleteVoiceRequest}. This allows follow-on voice actions 55 * such as {@link #ACTION_DISMISS_ALARM} to dismiss the alarm that was just enabled. 56 * </p> 57 * <h3>Request parameters</h3> 58 * <ul> 59 * <li>{@link #EXTRA_HOUR} <em>(optional)</em>: The hour of the alarm being set. 60 * <li>{@link #EXTRA_MINUTES} <em>(optional)</em>: The minutes of the alarm being set. 61 * <li>{@link #EXTRA_DAYS} <em>(optional)</em>: Weekdays for repeating alarm. 62 * <li>{@link #EXTRA_MESSAGE} <em>(optional)</em>: A custom message for the alarm. 63 * <li>{@link #EXTRA_RINGTONE} <em>(optional)</em>: A ringtone to play with this alarm. 64 * <li>{@link #EXTRA_VIBRATE} <em>(optional)</em>: Whether or not to activate the device 65 * vibrator for this alarm. 66 * <li>{@link #EXTRA_SKIP_UI} <em>(optional)</em>: Whether or not to display an activity for 67 * setting this alarm. 68 * </ul> 69 */ 70 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 71 public static final String ACTION_SET_ALARM = "android.intent.action.SET_ALARM"; 72 73 /** 74 * Activity Action: Dismiss an alarm. 75 * <p> 76 * The alarm to dismiss can be specified or searched for in one of the following ways: 77 * <ol> 78 * <li>The Intent's data URI, which represents a deeplink to the alarm. 79 * <li>The extra {@link #EXTRA_ALARM_SEARCH_MODE} to determine how to search for the alarm. 80 * </ol> 81 * </p><p> 82 * If neither of the above are given then: 83 * <ul> 84 * <li>If exactly one active alarm exists, it is dismissed. 85 * <li>If more than one active alarm exists, the user is prompted to choose the alarm to 86 * dismiss. 87 * </ul> 88 * </p><p> 89 * If the extra {@link #EXTRA_ALARM_SEARCH_MODE} is used, and the search results contain two or 90 * more matching alarms, then the implementation should show an UI with the results and allow 91 * the user to select the alarm to dismiss. If the implementation supports 92 * {@link android.content.Intent#CATEGORY_VOICE} and the activity is started in Voice 93 * Interaction mode (i.e. check {@link android.app.Activity#isVoiceInteraction}), then the 94 * implementation should additionally use {@link android.app.VoiceInteractor.PickOptionRequest} 95 * to start a voice interaction follow-on flow to help the user disambiguate the alarm by voice. 96 * </p><p> 97 * If the specified alarm is a single occurrence alarm, then dismissing it effectively disables 98 * the alarm; it will never ring again unless explicitly re-enabled. 99 * </p><p> 100 * If the specified alarm is a repeating alarm, then dismissing it only prevents the upcoming 101 * instance from ringing. The alarm remains enabled so that it will still ring on the date and 102 * time of the next instance (i.e. the instance after the upcoming one). 103 * </p> 104 * 105 * @see #EXTRA_ALARM_SEARCH_MODE 106 */ 107 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 108 public static final String ACTION_DISMISS_ALARM = "android.intent.action.DISMISS_ALARM"; 109 110 /** 111 * Activity Action: Snooze a currently ringing alarm. 112 * <p> 113 * Snoozes the currently ringing alarm. The extra {@link #EXTRA_ALARM_SNOOZE_DURATION} can be 114 * optionally set to specify the snooze duration; if unset, the implementation should use a 115 * reasonable default, for example 10 minutes. The alarm should ring again after the snooze 116 * duration. 117 * </p><p> 118 * Note: setting the extra {@link #EXTRA_ALARM_SNOOZE_DURATION} does not change the default 119 * snooze duration; it's only applied to the currently ringing alarm. 120 * </p><p> 121 * If there is no currently ringing alarm, then this is a no-op. 122 * </p> 123 * 124 * @see #EXTRA_ALARM_SNOOZE_DURATION 125 */ 126 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 127 public static final String ACTION_SNOOZE_ALARM = "android.intent.action.SNOOZE_ALARM"; 128 129 /** 130 * Activity Action: Set a timer. 131 * <p> 132 * Activates an existing timer or creates a new one. 133 * </p><p> 134 * This action requests a timer to be started for a specific {@link #EXTRA_LENGTH length} of 135 * time. If no {@link #EXTRA_LENGTH length} is specified, the implementation should start an 136 * activity that is capable of setting a timer ({@link #EXTRA_SKIP_UI} is ignored in this case). 137 * If a {@link #EXTRA_LENGTH length} is specified, and {@link #EXTRA_SKIP_UI} is {@code true}, 138 * the implementation should remove this timer after it has been dismissed. If an identical, 139 * unused timer exists matching both parameters, an implementation may re-use it instead of 140 * creating a new one (in this case, the timer should not be removed after dismissal). 141 * 142 * This action always starts the timer. 143 * </p> 144 * 145 * <h3>Request parameters</h3> 146 * <ul> 147 * <li>{@link #EXTRA_LENGTH} <em>(optional)</em>: The length of the timer being set. 148 * <li>{@link #EXTRA_MESSAGE} <em>(optional)</em>: A custom message for the timer. 149 * <li>{@link #EXTRA_SKIP_UI} <em>(optional)</em>: Whether or not to display an activity for 150 * setting this timer. 151 * </ul> 152 */ 153 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 154 public static final String ACTION_SET_TIMER = "android.intent.action.SET_TIMER"; 155 156 /** 157 * Activity Action: Dismiss a timer. 158 * <p> 159 * The timer to dismiss should be specified using the Intent's data URI, which represents a 160 * deeplink to the timer. 161 * </p><p> 162 * If no data URI is provided, dismiss all expired timers. 163 * </p> 164 */ 165 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 166 public static final String ACTION_DISMISS_TIMER = "android.intent.action.DISMISS_TIMER"; 167 168 /** 169 * Activity Action: Show the timers. 170 * <p> 171 * This action opens the timers page. 172 * </p> 173 */ 174 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 175 public static final String ACTION_SHOW_TIMERS = "android.intent.action.SHOW_TIMERS"; 176 177 /** 178 * Activity Action: Show the alarms. 179 * <p> 180 * This action opens the alarms page. 181 * </p> 182 */ 183 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 184 public static final String ACTION_SHOW_ALARMS = "android.intent.action.SHOW_ALARMS"; 185 186 /** 187 * Bundle extra: Specify the type of search mode to look up an alarm. 188 * <p> 189 * For example, used by {@link #ACTION_DISMISS_ALARM} to identify the alarm to dismiss. 190 * </p><p> 191 * This extra is only used when the alarm is not already identified by a deeplink as 192 * specified in the Intent's data URI. 193 * </p><p> 194 * The value of this extra is a {@link String}, restricted to the following set of supported 195 * search modes: 196 * <ul> 197 * <li><i>Time</i> - {@link #ALARM_SEARCH_MODE_TIME}: Selects the alarm that is most 198 * closely matched by the search parameters {@link #EXTRA_HOUR}, {@link #EXTRA_MINUTES}, 199 * {@link #EXTRA_IS_PM}. 200 * <li><i>Next alarm</i> - {@link #ALARM_SEARCH_MODE_NEXT}: Selects the alarm that will 201 * ring next, or the alarm that is currently ringing, if any. 202 * <li><i>All alarms</i> - {@link #ALARM_SEARCH_MODE_ALL}: Selects all alarms. 203 * <li><i>Label</i> - {@link #ALARM_SEARCH_MODE_LABEL}: Search by alarm label. Should return 204 * alarms that contain the word or phrase in given label. 205 * </ul> 206 * </p> 207 * 208 * @see #ALARM_SEARCH_MODE_TIME 209 * @see #ALARM_SEARCH_MODE_NEXT 210 * @see #ALARM_SEARCH_MODE_ALL 211 * @see #ALARM_SEARCH_MODE_LABEL 212 * @see #ACTION_DISMISS_ALARM 213 */ 214 public static final String EXTRA_ALARM_SEARCH_MODE = "android.intent.extra.alarm.SEARCH_MODE"; 215 216 /** 217 * Search for the alarm that is most closely matched by the search parameters 218 * {@link #EXTRA_HOUR}, {@link #EXTRA_MINUTES}, {@link #EXTRA_IS_PM}. 219 * In this search mode, at least one of these additional extras are required. 220 * <ul> 221 * <li>{@link #EXTRA_HOUR} - The hour to search for the alarm. 222 * <li>{@link #EXTRA_MINUTES} - The minute to search for the alarm. 223 * <li>{@link #EXTRA_IS_PM} - Whether the hour is AM or PM. 224 * </ul> 225 * 226 * @see #EXTRA_ALARM_SEARCH_MODE 227 */ 228 public static final String ALARM_SEARCH_MODE_TIME = "android.time"; 229 230 /** 231 * Selects the alarm that will ring next, or the alarm that is currently ringing, if any. 232 * 233 * @see #EXTRA_ALARM_SEARCH_MODE 234 */ 235 public static final String ALARM_SEARCH_MODE_NEXT = "android.next"; 236 237 /** 238 * Selects all alarms. 239 * 240 * @see #EXTRA_ALARM_SEARCH_MODE 241 */ 242 public static final String ALARM_SEARCH_MODE_ALL = "android.all"; 243 244 /** 245 * Search by alarm label. Should return alarms that contain the word or phrase in given label. 246 * 247 * @see #EXTRA_ALARM_SEARCH_MODE 248 */ 249 public static final String ALARM_SEARCH_MODE_LABEL = "android.label"; 250 251 /** 252 * Bundle extra: The AM/PM of the alarm. 253 * <p> 254 * Used by {@link #ACTION_DISMISS_ALARM}. 255 * </p><p> 256 * This extra is optional and only used when {@link #EXTRA_ALARM_SEARCH_MODE} is set to 257 * {@link #ALARM_SEARCH_MODE_TIME}. In this search mode, the {@link #EXTRA_IS_PM} is 258 * used together with {@link #EXTRA_HOUR} and {@link #EXTRA_MINUTES}. The implementation should 259 * look up the alarm that is most closely matched by these search parameters. 260 * If {@link #EXTRA_IS_PM} is missing, then the AM/PM of the specified {@link #EXTRA_HOUR} is 261 * ambiguous and the implementation should ask for clarification from the user. 262 * </p><p> 263 * The value is a {@link Boolean}, where false=AM and true=PM. 264 * </p> 265 * 266 * @see #ACTION_DISMISS_ALARM 267 * @see #EXTRA_HOUR 268 * @see #EXTRA_MINUTES 269 */ 270 public static final String EXTRA_IS_PM = "android.intent.extra.alarm.IS_PM"; 271 272 273 /** 274 * Bundle extra: The snooze duration of the alarm in minutes. 275 * <p> 276 * Used by {@link #ACTION_SNOOZE_ALARM}. This extra is optional and the value is an 277 * {@link Integer} that specifies the duration in minutes for which to snooze the alarm. 278 * </p> 279 * 280 * @see #ACTION_SNOOZE_ALARM 281 */ 282 public static final String EXTRA_ALARM_SNOOZE_DURATION = 283 "android.intent.extra.alarm.SNOOZE_DURATION"; 284 285 /** 286 * Bundle extra: Weekdays for repeating alarm. 287 * <p> 288 * Used by {@link #ACTION_SET_ALARM}. 289 * </p><p> 290 * The value is an {@code ArrayList<Integer>}. Each item can be: 291 * </p> 292 * <ul> 293 * <li> {@link java.util.Calendar#SUNDAY}, 294 * <li> {@link java.util.Calendar#MONDAY}, 295 * <li> {@link java.util.Calendar#TUESDAY}, 296 * <li> {@link java.util.Calendar#WEDNESDAY}, 297 * <li> {@link java.util.Calendar#THURSDAY}, 298 * <li> {@link java.util.Calendar#FRIDAY}, 299 * <li> {@link java.util.Calendar#SATURDAY} 300 * </ul> 301 */ 302 public static final String EXTRA_DAYS = "android.intent.extra.alarm.DAYS"; 303 304 /** 305 * Bundle extra: The hour of the alarm. 306 * <p> 307 * Used by {@link #ACTION_SET_ALARM}. 308 * </p><p> 309 * This extra is optional. If not provided, an implementation should open an activity 310 * that allows a user to set an alarm with user provided time. 311 * </p><p> 312 * The value is an {@link Integer} and ranges from 0 to 23. 313 * </p> 314 * 315 * @see #ACTION_SET_ALARM 316 * @see #EXTRA_MINUTES 317 * @see #EXTRA_DAYS 318 */ 319 public static final String EXTRA_HOUR = "android.intent.extra.alarm.HOUR"; 320 321 /** 322 * Bundle extra: The length of the timer in seconds. 323 * <p> 324 * Used by {@link #ACTION_SET_TIMER}. 325 * </p><p> 326 * This extra is optional. If not provided, an implementation should open an activity 327 * that allows a user to set a timer with user provided length. 328 * </p><p> 329 * The value is an {@link Integer} and ranges from 1 to 86400 (24 hours). 330 * </p> 331 * 332 * @see #ACTION_SET_TIMER 333 */ 334 public static final String EXTRA_LENGTH = "android.intent.extra.alarm.LENGTH"; 335 336 /** 337 * Bundle extra: A custom message for the alarm or timer. 338 * <p> 339 * Used by {@link #ACTION_SET_ALARM} and {@link #ACTION_SET_TIMER}. 340 * </p><p> 341 * The value is a {@link String}. 342 * </p> 343 * 344 * @see #ACTION_SET_ALARM 345 * @see #ACTION_SET_TIMER 346 */ 347 public static final String EXTRA_MESSAGE = "android.intent.extra.alarm.MESSAGE"; 348 349 /** 350 * Bundle extra: The minutes of the alarm. 351 * <p> 352 * Used by {@link #ACTION_SET_ALARM}. 353 * </p><p> 354 * The value is an {@link Integer} and ranges from 0 to 59. If not provided, it defaults to 0. 355 * </p> 356 * 357 * @see #ACTION_SET_ALARM 358 * @see #EXTRA_HOUR 359 * @see #EXTRA_DAYS 360 */ 361 public static final String EXTRA_MINUTES = "android.intent.extra.alarm.MINUTES"; 362 363 /** 364 * Bundle extra: A ringtone to be played with this alarm. 365 * <p> 366 * Used by {@link #ACTION_SET_ALARM}. 367 * </p><p> 368 * This value is a {@link String} and can either be set to {@link #VALUE_RINGTONE_SILENT} or 369 * to a content URI of the media to be played. If not specified or the URI doesn't exist, 370 * {@code "content://settings/system/alarm_alert} will be used. 371 * </p> 372 * 373 * @see #ACTION_SET_ALARM 374 * @see #VALUE_RINGTONE_SILENT 375 * @see #EXTRA_VIBRATE 376 */ 377 public static final String EXTRA_RINGTONE = "android.intent.extra.alarm.RINGTONE"; 378 379 /** 380 * Bundle extra: Whether or not to display an activity after performing the action. 381 * <p> 382 * Used by {@link #ACTION_SET_ALARM} and {@link #ACTION_SET_TIMER}. 383 * </p><p> 384 * If true, the application is asked to bypass any intermediate UI. If false, the application 385 * may display intermediate UI like a confirmation dialog or settings. 386 * </p><p> 387 * The value is a {@link Boolean}. The default is {@code false}. 388 * </p> 389 * 390 * @see #ACTION_SET_ALARM 391 * @see #ACTION_SET_TIMER 392 */ 393 public static final String EXTRA_SKIP_UI = "android.intent.extra.alarm.SKIP_UI"; 394 395 /** 396 * Bundle extra: Whether or not to activate the device vibrator. 397 * <p> 398 * Used by {@link #ACTION_SET_ALARM}. 399 * </p><p> 400 * The value is a {@link Boolean}. The default is {@code true}. 401 * </p> 402 * 403 * @see #ACTION_SET_ALARM 404 * @see #EXTRA_RINGTONE 405 * @see #VALUE_RINGTONE_SILENT 406 */ 407 public static final String EXTRA_VIBRATE = "android.intent.extra.alarm.VIBRATE"; 408 409 /** 410 * Bundle extra value: Indicates no ringtone should be played. 411 * <p> 412 * Used by {@link #ACTION_SET_ALARM}, passed in through {@link #EXTRA_RINGTONE}. 413 * </p> 414 * 415 * @see #ACTION_SET_ALARM 416 * @see #EXTRA_RINGTONE 417 * @see #EXTRA_VIBRATE 418 */ 419 public static final String VALUE_RINGTONE_SILENT = "silent"; 420 } 421