sdk/sources/android-23/android/provider/AlarmClock.java

   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 public 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 }