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