2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __TIZEN_APPFW_ALARM_H__
19 #define __TIZEN_APPFW_ALARM_H__
23 #include <app_control.h>
34 * @addtogroup CAPI_ALARM_MODULE
39 * @brief Definition to app_control extra data : the ID of the alarm registered.
42 #define APP_CONTROL_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id"
45 * @brief Enumeration for Alarm Error.
50 ALARM_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
51 ALARM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
52 ALARM_ERROR_INVALID_TIME = TIZEN_ERROR_APPLICATION | 0x05, /**< Invalid time */
53 ALARM_ERROR_INVALID_DATE = TIZEN_ERROR_APPLICATION | 0x06, /**< Invalid date */
54 ALARM_ERROR_CONNECTION_FAIL = TIZEN_ERROR_APPLICATION | 0x07, /**< The alarm service connection failed */
55 ALARM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
56 ALARM_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED /**< Permission denied */
61 * @brief Enumeration for Alarm Week Flag, the days of the week.
66 ALARM_WEEK_FLAG_SUNDAY = 0x01, /**< Sunday */
67 ALARM_WEEK_FLAG_MONDAY = 0x02, /**< Monday */
68 ALARM_WEEK_FLAG_TUESDAY = 0x04, /**< Tuesday */
69 ALARM_WEEK_FLAG_WEDNESDAY = 0x08, /**< Wednesday */
70 ALARM_WEEK_FLAG_THURSDAY = 0x10, /**< Thursday */
71 ALARM_WEEK_FLAG_FRIDAY = 0x20, /**< Friday */
72 ALARM_WEEK_FLAG_SATURDAY = 0x40 /**< Saturday */
76 * @brief Called once for each scheduled alarm to get the alarm ID.
79 * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
80 * @param[in] user_data The user data passed from the foreach function
81 * @return @c true to continue with the next iteration of the loop,
82 * otherwise @c false to break out of the loop
83 * @pre alarm_foreach_registered_alarm() will invoke this callback to get all the registered alarm IDs.
84 * @see alarm_foreach_registered_alarm()
86 typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data);
89 * @brief Sets an alarm to be triggered after a specific time.
90 * @details The alarm will first go off @a delay seconds later and then will go off every certain amount of time defined using @a period seconds.
91 * If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time.
92 * If @a period is set to @c 0, the alarm will go off just once without repetition.
93 * To cancel the alarm, call alarm_cancel() with @a alarm_id.
96 * @privilege %http://tizen.org/privilege/alarm.set
97 * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
99 * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
100 * @param[in] delay The amount of time before the first execution (in seconds)
101 * @param[in] period The amount of time between subsequent alarms (in seconds)
102 * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
103 * @return @c 0 on success,
104 * otherwise a negative error value
105 * @retval #ALARM_ERROR_NONE Successful
106 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
107 * @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid
108 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
109 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
110 * @see alarm_cancel()
111 * @see alarm_cancel_all()
112 * @see alarm_get_scheduled_date()
113 * @see alarm_get_scheduled_period()
115 int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, int *alarm_id);
119 * @brief Sets an alarm to be triggered at a specific time.
120 * @details The @a date describes the time of the first occurrence.
121 * If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time.
122 * If @a period is set to @c 0, the alarm will go off just once without repetition.
123 * To cancel the alarm, call alarm_cancel() with @a alarm_id.
126 * @privilege %http://tizen.org/privilege/alarm.set
127 * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
129 * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
130 * @param[in] date The first active alarm time
131 * @param[in] period The amount of time between subsequent alarms(in second)
132 * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
133 * @return @c 0 on success,
134 * otherwise a negative error value
135 * @retval #ALARM_ERROR_NONE Successful
136 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
137 * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
138 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
139 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
140 * @see alarm_cancel()
141 * @see alarm_cancel_all()
142 * @see alarm_get_scheduled_date()
143 * @see alarm_get_scheduled_period()
145 int alarm_schedule_at_date(app_control_h app_control, struct tm *date, int period, int *alarm_id);
149 * @brief Sets an alarm to be triggered periodically, starting at a specific time.
150 * @details The @a date describes the time of the first occurrence.
151 * @a week_flag is the repeat value of the days of the week.
152 * If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time.
153 * To cancel the alarm, call alarm_cancel() with @a alarm_id.
156 * @privilege %http://tizen.org/privilege/alarm.set
157 * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
159 * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
160 * @param[in] date The first active alarm time
161 * @param[in] week_flag The day of the week, @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY
162 * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
163 * @return @c 0 on success,
164 * otherwise a negative error value
165 * @retval #ALARM_ERROR_NONE Successful
166 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
167 * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
168 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
169 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
170 * @see alarm_cancel()
171 * @see alarm_cancel_all()
172 * @see alarm_get_scheduled_recurrence_week_flag()
173 * @see alarm_get_scheduled_date()
174 * @see #alarm_week_flag_e
176 int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct tm *date, int week_flag,int *alarm_id);
180 * @brief Gets the recurrence days of the week.
183 * @privilege %http://tizen.org/privilege/alarm.get
184 * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function,
185 * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence.
186 * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
187 * @param[out] week_flag The recurrence days of the week, @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY
188 * @return @c 0 on success,
189 * otherwise a negative error value
190 * @retval #ALARM_ERROR_NONE Successful
191 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
192 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
193 * @see alarm_schedule_with_recurrence_week_flag()
194 * @see #alarm_week_flag_e
196 int alarm_get_scheduled_recurrence_week_flag(int alarm_id, int *week_flag);
200 * @brief Cancels the alarm with the specific alarm ID.
203 * @privilege %http://tizen.org/privilege/alarm.set
204 * @param[in] alarm_id The alarm ID that is cancelled
205 * @return @c 0 on success,
206 * otherwise a negative error value
207 * @retval #ALARM_ERROR_NONE Successful
208 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
209 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
210 * @see alarm_schedule_at_date()
211 * @see alarm_schedule_after_delay()
212 * @see alarm_schedule_with_recurrence_week_flag()
213 * @see alarm_cancel_all()
215 int alarm_cancel(int alarm_id);
219 * @brief Cancels all scheduled alarms that are registered by the application that calls this API.
222 * @privilege %http://tizen.org/privilege/alarm.set
223 * @return @c 0 on success,
224 * otherwise a negative error value
225 * @retval #ALARM_ERROR_NONE Successful
226 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
227 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
228 * @see alarm_schedule_at_date()
229 * @see alarm_schedule_after_delay()
230 * @see alarm_schedule_with_recurrence_week_flag()
231 * @see alarm_cancel()
233 int alarm_cancel_all(void);
237 * @brief Retrieves the IDs of all registered alarms by invoking a callback once for each scheduled alarm.
240 * @privilege %http://tizen.org/privilege/alarm.get
241 * @param[in] callback The callback function to invoke
242 * @param[in] user_data The user data to be passed to the callback function
243 * @return @c 0 on success,
244 * otherwise a negative error value
245 * @retval #ALARM_ERROR_NONE Successful
246 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
247 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
248 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
249 * @post This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm.
250 * @see alarm_registered_alarm_cb()
252 int alarm_foreach_registered_alarm(alarm_registered_alarm_cb callback, void *user_data);
256 * @brief Gets the scheduled time from the given alarm ID in C standard time struct.
259 * @privilege %http://tizen.org/privilege/alarm.get
260 * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
261 * @param[out] date The time value of the next alarm event
262 * @return @c 0 on success,
263 * otherwise a negative error value
264 * @retval #ALARM_ERROR_NONE Successful
265 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
266 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
267 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
268 * @see alarm_schedule_at_date()
269 * @see alarm_schedule_after_delay()
270 * @see alarm_schedule_with_recurrence_week_flag()
272 int alarm_get_scheduled_date(int alarm_id, struct tm *date);
276 * @brief Gets the period of time between the recurrent alarms.
279 * @privilege %http://tizen.org/privilege/alarm.get
280 * @remarks If the given @a alarm_id is not obtained by using the alarm_get_scheduled_date() or alarm_schedule_after_delay() function,
281 * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur.
282 * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
283 * @param[out] period The period of time between recurrent alarms in seconds
284 * @return @c 0 on success,
285 * otherwise a negative error value
286 * @retval #ALARM_ERROR_NONE Successful
287 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
288 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
289 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
290 * @see alarm_schedule_at_date()
291 * @see alarm_schedule_after_delay()
292 * @see alarm_schedule_with_recurrence_week_flag()
294 int alarm_get_scheduled_period(int alarm_id, int *period);
298 * @brief Gets the current system time using C standard time struct.
300 * @param[out] date The current system time
301 * @return @c 0 on success,
302 * otherwise a negative error value
303 * @retval #ALARM_ERROR_NONE Successful
304 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
305 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
307 int alarm_get_current_time(struct tm *date);
311 * @brief Gets the app_control to be invoked when the the alarm is triggered.
314 * @privilege %http://tizen.org/privilege/alarm.get
315 * @remarks The @a app_control must be released using app_control_destroy().
316 * @param[in] alarm_id The alarm ID uniquely identifies an alarm
317 * @param[out] app_control The app_control handle to launch when the alarm is triggered
318 * @return @c 0 on success,
319 * otherwise a negative error value
320 * @retval #ALARM_ERROR_NONE Successful
321 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
322 * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
323 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
324 * @see alarm_schedule_at_date()
325 * @see alarm_schedule_after_delay()
326 * @see alarm_schedule_with_recurrence_week_flag()
328 int alarm_get_app_control(int alarm_id, app_control_h *app_control);
338 #endif /* __TIZEN_APPFW_ALARM_H__ */