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 * 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 * Activity Action: Show the alarms. 94 * <p> 95 * This action opens the alarms page. 96 * </p> 97 */ 98 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 99 public static final String ACTION_SHOW_ALARMS = "android.intent.action.SHOW_ALARMS"; 100 101 /** 102 * Bundle extra: Weekdays for repeating alarm. 103 * <p> 104 * Used by {@link #ACTION_SET_ALARM}. 105 * </p><p> 106 * The value is an {@code ArrayList<Integer>}. Each item can be: 107 * </p> 108 * <ul> 109 * <li> {@link java.util.Calendar#SUNDAY}, 110 * <li> {@link java.util.Calendar#MONDAY}, 111 * <li> {@link java.util.Calendar#TUESDAY}, 112 * <li> {@link java.util.Calendar#WEDNESDAY}, 113 * <li> {@link java.util.Calendar#THURSDAY}, 114 * <li> {@link java.util.Calendar#FRIDAY}, 115 * <li> {@link java.util.Calendar#SATURDAY} 116 * </ul> 117 */ 118 public static final String EXTRA_DAYS = "android.intent.extra.alarm.DAYS"; 119 120 /** 121 * Bundle extra: The hour of the alarm. 122 * <p> 123 * Used by {@link #ACTION_SET_ALARM}. 124 * </p><p> 125 * This extra is optional. If not provided, an implementation should open an activity 126 * that allows a user to set an alarm with user provided time. 127 * </p><p> 128 * The value is an {@link Integer} and ranges from 0 to 23. 129 * </p> 130 * 131 * @see #ACTION_SET_ALARM 132 * @see #EXTRA_MINUTES 133 * @see #EXTRA_DAYS 134 */ 135 public static final String EXTRA_HOUR = "android.intent.extra.alarm.HOUR"; 136 137 /** 138 * Bundle extra: The length of the timer in seconds. 139 * <p> 140 * Used by {@link #ACTION_SET_TIMER}. 141 * </p><p> 142 * This extra is optional. If not provided, an implementation should open an activity 143 * that allows a user to set a timer with user provided length. 144 * </p><p> 145 * The value is an {@link Integer} and ranges from 1 to 86400 (24 hours). 146 * </p> 147 * 148 * @see #ACTION_SET_TIMER 149 */ 150 public static final String EXTRA_LENGTH = "android.intent.extra.alarm.LENGTH"; 151 152 /** 153 * Bundle extra: A custom message for the alarm or timer. 154 * <p> 155 * Used by {@link #ACTION_SET_ALARM} and {@link #ACTION_SET_TIMER}. 156 * </p><p> 157 * The value is a {@link String}. 158 * </p> 159 * 160 * @see #ACTION_SET_ALARM 161 * @see #ACTION_SET_TIMER 162 */ 163 public static final String EXTRA_MESSAGE = "android.intent.extra.alarm.MESSAGE"; 164 165 /** 166 * Bundle extra: The minutes of the alarm. 167 * <p> 168 * Used by {@link #ACTION_SET_ALARM}. 169 * </p><p> 170 * The value is an {@link Integer} and ranges from 0 to 59. If not provided, it defaults to 0. 171 * </p> 172 * 173 * @see #ACTION_SET_ALARM 174 * @see #EXTRA_HOUR 175 * @see #EXTRA_DAYS 176 */ 177 public static final String EXTRA_MINUTES = "android.intent.extra.alarm.MINUTES"; 178 179 /** 180 * Bundle extra: A ringtone to be played with this alarm. 181 * <p> 182 * Used by {@link #ACTION_SET_ALARM}. 183 * </p><p> 184 * This value is a {@link String} and can either be set to {@link #VALUE_RINGTONE_SILENT} or 185 * to a content URI of the media to be played. If not specified or the URI doesn't exist, 186 * {@code "content://settings/system/alarm_alert} will be used. 187 * </p> 188 * 189 * @see #ACTION_SET_ALARM 190 * @see #VALUE_RINGTONE_SILENT 191 * @see #EXTRA_VIBRATE 192 */ 193 public static final String EXTRA_RINGTONE = "android.intent.extra.alarm.RINGTONE"; 194 195 /** 196 * Bundle extra: Whether or not to display an activity after performing the action. 197 * <p> 198 * Used by {@link #ACTION_SET_ALARM} and {@link #ACTION_SET_TIMER}. 199 * </p><p> 200 * If true, the application is asked to bypass any intermediate UI. If false, the application 201 * may display intermediate UI like a confirmation dialog or settings. 202 * </p><p> 203 * The value is a {@link Boolean}. The default is {@code false}. 204 * </p> 205 * 206 * @see #ACTION_SET_ALARM 207 * @see #ACTION_SET_TIMER 208 */ 209 public static final String EXTRA_SKIP_UI = "android.intent.extra.alarm.SKIP_UI"; 210 211 /** 212 * Bundle extra: Whether or not to activate the device vibrator. 213 * <p> 214 * Used by {@link #ACTION_SET_ALARM}. 215 * </p><p> 216 * The value is a {@link Boolean}. The default is {@code true}. 217 * </p> 218 * 219 * @see #ACTION_SET_ALARM 220 * @see #EXTRA_RINGTONE 221 * @see #VALUE_RINGTONE_SILENT 222 */ 223 public static final String EXTRA_VIBRATE = "android.intent.extra.alarm.VIBRATE"; 224 225 /** 226 * Bundle extra value: Indicates no ringtone should be played. 227 * <p> 228 * Used by {@link #ACTION_SET_ALARM}, passed in through {@link #EXTRA_RINGTONE}. 229 * </p> 230 * 231 * @see #ACTION_SET_ALARM 232 * @see #EXTRA_RINGTONE 233 * @see #EXTRA_VIBRATE 234 */ 235 public static final String VALUE_RINGTONE_SILENT = "silent"; 236 } 237
