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