AlarmClock.java revision 21ea2d0387e07569b3448c1161a3276599b3fbba
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 an alarm already 40 * exists for this time, an implementation may use it rather than create a new one. If no time 41 * of day is specified, the implementation should start an activity that is capable of setting 42 * an alarm (SKIP_UI is ignored in this case). This action always enables the alarm. 43 * </p> 44 * <h3>Request parameters</h3> 45 * <ul> 46 * <li>{@link #EXTRA_HOUR} <em>(optional)</em>: The hour of the alarm being set. 47 * <li>{@link #EXTRA_MINUTES} <em>(optional)</em>: The minutes of the alarm being set. 48 * <li>{@link #EXTRA_DAYS} <em>(optional)</em>: Weekdays for repeating alarm. 49 * <li>{@link #EXTRA_MESSAGE} <em>(optional)</em>: A custom message for the alarm. 50 * <li>{@link #EXTRA_RINGTONE} <em>(optional)</em>: A ringtone to play with this alarm. 51 * <li>{@link #EXTRA_VIBRATE} <em>(optional)</em>: Whether or not to activate the device 52 * vibrator for this alarm. 53 * <li>{@link #EXTRA_SKIP_UI} <em>(optional)</em>: Whether or not to display an activity for 54 * setting this alarm. 55 * <li>{@link #EXTRA_DELETE_AFTER_USE} <em>(optional)</em>: Whether or not to delete this 56 * alarm after it is dismissed. 57 * </ul> 58 */ 59 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 60 public static final String ACTION_SET_ALARM = "android.intent.action.SET_ALARM"; 61 62 /** 63 * Activity Action: Set a timer. 64 * <p> 65 * Activates an existing timer or creates a new one. 66 * </p><p> 67 * This action requests a timer to be started for a specific {@link #EXTRA_LENGTH length} of 68 * time. If a timer already exists for this {@link #EXTRA_LENGTH length}, an implementation may 69 * use it rather than create a new one. If no {@link #EXTRA_LENGTH length} is specified, the 70 * implementation should start an activity that is capable of setting a timer 71 * ({@link #EXTRA_SKIP_UI} is ignored in this case). 72 * </p><p> 73 * An existing timer should only be used if it matches the provided extras and is not currently 74 * in use. 75 * </p> 76 * 77 * <h3>Request parameters</h3> 78 * <ul> 79 * <li>{@link #EXTRA_LENGTH} <em>(optional)</em>: The length of the timer being set. 80 * <li>{@link #EXTRA_MESSAGE} <em>(optional)</em>: A custom message for the timer. 81 * <li>{@link #EXTRA_SKIP_UI} <em>(optional)</em>: Whether or not to display an activity for 82 * setting this timer. 83 * <li>{@link #EXTRA_DELETE_AFTER_USE} <em>(optional)</em>: Whether or not to delete this 84 * timer after it is dismissed. 85 * </ul> 86 */ 87 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 88 public static final String ACTION_SET_TIMER = "android.intent.action.SET_TIMER"; 89 90 /** 91 * Bundle extra: Weekdays for repeating alarm. 92 * <p> 93 * Used by {@link #ACTION_SET_ALARM}. 94 * </p><p> 95 * The value is an {@code ArrayList<Integer>}. Each item can be: 96 * </p> 97 * <ul> 98 * <li> {@link java.util.Calendar#SUNDAY}, 99 * <li> {@link java.util.Calendar#MONDAY}, 100 * <li> {@link java.util.Calendar#TUESDAY}, 101 * <li> {@link java.util.Calendar#WEDNESDAY}, 102 * <li> {@link java.util.Calendar#THURSDAY}, 103 * <li> {@link java.util.Calendar#FRIDAY}, 104 * <li> {@link java.util.Calendar#SATURDAY} 105 * </ul> 106 * <p> 107 * Note: If this extra is provided, {@link #EXTRA_DELETE_AFTER_USE} is ignored. 108 * </p> 109 */ 110 public static final String EXTRA_DAYS = "android.intent.extra.alarm.DAYS"; 111 112 /** 113 * Bundle extra: Whether or not to delete this alarm/timer after it's dismissed. 114 * <p> 115 * Used by {@link #ACTION_SET_ALARM} and {@link #ACTION_SET_TIMER}. 116 * </p><p> 117 * If this value is true, the alarm/timer used by this action should be deleted after it's been 118 * dismissed. The alarm/timer should only be removed if was actually created by the action. If 119 * an existing alarm/timer was used, it should not be deleted after it's dismissed. 120 * </p><p> 121 * The value is a {@link Boolean}. 122 * </p> 123 * 124 * @see #ACTION_SET_ALARM 125 * @see #ACTION_SET_TIMER 126 */ 127 public static final String EXTRA_DELETE_AFTER_USE = "android.intent.extra.alarm.DELETE_AFTER_USE"; 128 129 /** 130 * Bundle extra: The hour of the alarm. 131 * <p> 132 * Used by {@link #ACTION_SET_ALARM}. 133 * </p><p> 134 * This extra is optional. If not provided, an implementation should open an activity 135 * that allows a user to set an alarm with user provided time. 136 * </p><p> 137 * The value is an {@link Integer} and ranges from 0 to 23. 138 * </p> 139 * 140 * @see #ACTION_SET_ALARM 141 * @see #EXTRA_MINUTES 142 * @see #EXTRA_DAYS 143 */ 144 public static final String EXTRA_HOUR = "android.intent.extra.alarm.HOUR"; 145 146 /** 147 * Bundle extra: The length of the timer in seconds. 148 * <p> 149 * Used by {@link #ACTION_SET_TIMER}. 150 * </p><p> 151 * This extra is optional. If not provided, an implementation should open an activity 152 * that allows a user to set a timer with user provided length. 153 * </p><p> 154 * The value is an {@link Integer} and ranges from 1 to 86400 (24 hours). 155 * </p> 156 * 157 * @see #ACTION_SET_TIMER 158 */ 159 public static final String EXTRA_LENGTH = "android.intent.extra.alarm.LENGTH"; 160 161 /** 162 * Bundle extra: A custom message for the alarm or timer. 163 * <p> 164 * Used by {@link #ACTION_SET_ALARM} and {@link #ACTION_SET_TIMER}. 165 * </p><p> 166 * The value is a {@link String}. 167 * </p> 168 * 169 * @see #ACTION_SET_ALARM 170 * @see #ACTION_SET_TIMER 171 */ 172 public static final String EXTRA_MESSAGE = "android.intent.extra.alarm.MESSAGE"; 173 174 /** 175 * Bundle extra: The minutes of the alarm. 176 * <p> 177 * Used by {@link #ACTION_SET_ALARM}. 178 * </p><p> 179 * The value is an {@link Integer} and ranges from 0 to 59. If not provided, it defaults to 0. 180 * </p> 181 * 182 * @see #ACTION_SET_ALARM 183 * @see #EXTRA_HOUR 184 * @see #EXTRA_DAYS 185 */ 186 public static final String EXTRA_MINUTES = "android.intent.extra.alarm.MINUTES"; 187 188 /** 189 * Bundle extra: A ringtone to be played with this alarm. 190 * <p> 191 * Used by {@link #ACTION_SET_ALARM}. 192 * </p><p> 193 * This value is a {@link String} and can either be set to {@link #VALUE_RINGTONE_SILENT} or 194 * to a content URI of the media to be played. If not specified or the URI doesn't exist, 195 * {@code "content://settings/system/alarm_alert} will be used. 196 * </p> 197 * 198 * @see #ACTION_SET_ALARM 199 * @see #VALUE_RINGTONE_SILENT 200 * @see #EXTRA_VIBRATE 201 */ 202 public static final String EXTRA_RINGTONE = "android.intent.extra.alarm.RINGTONE"; 203 204 /** 205 * Bundle extra: Whether or not to display an activity after performing the action. 206 * <p> 207 * Used by {@link #ACTION_SET_ALARM} and {@link #ACTION_SET_TIMER}. 208 * </p><p> 209 * If true, the application is asked to bypass any intermediate UI. If false, the application 210 * may display intermediate UI like a confirmation dialog or settings. 211 * </p><p> 212 * The value is a {@link Boolean}. The default is {@code false}. 213 * </p> 214 * 215 * @see #ACTION_SET_ALARM 216 * @see #ACTION_SET_TIMER 217 */ 218 public static final String EXTRA_SKIP_UI = "android.intent.extra.alarm.SKIP_UI"; 219 220 /** 221 * Bundle extra: Whether or not to activate the device vibrator. 222 * <p> 223 * Used by {@link #ACTION_SET_ALARM}. 224 * </p><p> 225 * The value is a {@link Boolean}. The default is {@code true}. 226 * </p> 227 * 228 * @see #ACTION_SET_ALARM 229 * @see #EXTRA_RINGTONE 230 * @see #VALUE_RINGTONE_SILENT 231 */ 232 public static final String EXTRA_VIBRATE = "android.intent.extra.alarm.VIBRATE"; 233 234 /** 235 * Bundle extra value: Indicates no ringtone should be played. 236 * <p> 237 * Used by {@link #ACTION_SET_ALARM}, passed in through {@link #EXTRA_RINGTONE}. 238 * </p> 239 * 240 * @see #ACTION_SET_ALARM 241 * @see #EXTRA_RINGTONE 242 * @see #EXTRA_VIBRATE 243 */ 244 public static final String VALUE_RINGTONE_SILENT = "silent"; 245} 246