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.
40 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
42 #define APP_CONTROL_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id"
45 * @brief Enumeration for Alarm Error.
46 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
49 ALARM_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
50 ALARM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
51 ALARM_ERROR_INVALID_TIME = TIZEN_ERROR_APPLICATION | 0x05, /**< Invalid time */
52 ALARM_ERROR_INVALID_DATE = TIZEN_ERROR_APPLICATION | 0x06, /**< Invalid date */
53 ALARM_ERROR_CONNECTION_FAIL = TIZEN_ERROR_APPLICATION | 0x07, /**< The alarm service connection failed */
54 ALARM_ERROR_NOT_PERMITTED_APP = TIZEN_ERROR_APPLICATION | 0x08, /**< Application is not permitted. (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
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.
62 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
65 ALARM_WEEK_FLAG_SUNDAY = 0x01, /**< Sunday */
66 ALARM_WEEK_FLAG_MONDAY = 0x02, /**< Monday */
67 ALARM_WEEK_FLAG_TUESDAY = 0x04, /**< Tuesday */
68 ALARM_WEEK_FLAG_WEDNESDAY = 0x08, /**< Wednesday */
69 ALARM_WEEK_FLAG_THURSDAY = 0x10, /**< Thursday */
70 ALARM_WEEK_FLAG_FRIDAY = 0x20, /**< Friday */
71 ALARM_WEEK_FLAG_SATURDAY = 0x40 /**< Saturday */
75 * @brief Called once for each scheduled alarm to get the alarm ID.
77 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
78 * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
79 * @param[in] user_data The user data passed from the foreach function
80 * @return @c true to continue with the next iteration of the loop,
81 * otherwise @c false to break out of the loop
82 * @pre alarm_foreach_registered_alarm() will invoke this callback to get all the registered alarm IDs.
83 * @see alarm_foreach_registered_alarm()
85 typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data);
88 * @brief Sets an alarm to be triggered after a specific time.
89 * @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.
90 * To cancel the alarm, call alarm_cancel() with @a alarm_id.
91 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
93 * @privilege %http://tizen.org/privilege/alarm.set
94 * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
95 * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
96 * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
97 * Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, this api does not support exact period and delay for minimizing the wakeups of the device. The system can adjust when the alarm expires.
98 * If you want to trigger an alarm exactly, see @see alarm_schedule_once_after_delay()
99 * Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif If @a app_control is specified with service-application, the application is only allowed to run on which has Background Category.
100 * Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
102 * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
103 * @param[in] delay The amount of time before the first execution (in seconds). Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, Although this is inexact, the alarm will not fire before this time
104 * @param[in] period The amount of time between subsequent alarms (in seconds). Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, This value does not guarantee the accuracy. The actual interval is calculated by the OS. The minimum value is 600sec
105 * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
106 * @return @c 0 on success,
107 * otherwise a negative error value
108 * @retval #ALARM_ERROR_NONE Successful
109 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
110 * @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid
111 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
112 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
113 * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted
114 * @see alarm_cancel()
115 * @see alarm_cancel_all()
116 * @see alarm_get_scheduled_date()
117 * @see alarm_get_scheduled_period()
118 * @see alarm_schedule_once_after_delay()
120 int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, int *alarm_id);
124 * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use alarm_schedule_once_at_date() instead]
125 * @brief Sets an alarm to be triggered at a specific time.
126 * @details The @a date describes the time of the first occurrence.
127 * If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time.
128 * If @a period is set to @c 0, the alarm will go off just once without repetition.
129 * To cancel the alarm, call alarm_cancel() with @a alarm_id.
130 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
132 * @privilege %http://tizen.org/privilege/alarm.set
133 * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
134 * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
135 * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
137 * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
138 * @param[in] date The first active alarm time
139 * @param[in] period The amount of time between subsequent alarms(in second)
140 * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
141 * @return @c 0 on success,
142 * otherwise a negative error value
143 * @retval #ALARM_ERROR_NONE Successful
144 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
145 * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
146 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
147 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
148 * @see alarm_cancel()
149 * @see alarm_cancel_all()
150 * @see alarm_get_scheduled_date()
151 * @see alarm_get_scheduled_period()
153 int alarm_schedule_at_date(app_control_h app_control, struct tm *date, int period, int *alarm_id);
156 * @brief Sets an alarm to be triggered after a specific time.
157 * @details The alarm will go off @a delay seconds later.
158 * To cancel the alarm, call alarm_cancel() with @a alarm_id.
159 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
161 * @privilege %http://tizen.org/privilege/alarm.set
162 * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
163 * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
164 * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
165 * If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
166 * The @a app_control only supports UI application with this api. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
167 * When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
169 * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
170 * @param[in] delay The amount of time before the execution (in seconds)
171 * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
172 * @return @c 0 on success,
173 * otherwise a negative error value
174 * @retval #ALARM_ERROR_NONE Successful
175 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
176 * @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid
177 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
178 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
179 * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
180 * @see alarm_cancel()
181 * @see alarm_cancel_all()
182 * @see alarm_get_scheduled_date()
184 int alarm_schedule_once_after_delay(app_control_h app_control, int delay, int *alarm_id);
188 * @brief Sets an alarm to be triggered at a specific time.
189 * @details The @a date describes the time of the first occurrence.
190 * To cancel the alarm, call alarm_cancel() with @a alarm_id.
191 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
193 * @privilege %http://tizen.org/privilege/alarm.set
194 * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
195 * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
196 * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
197 * If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
198 * The @a app_control only supports UI application with this api. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
199 * When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
201 * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
202 * @param[in] date The first active alarm time
203 * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
204 * @return @c 0 on success,
205 * otherwise a negative error value
206 * @retval #ALARM_ERROR_NONE Successful
207 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
208 * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
209 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
210 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
211 * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
212 * @see alarm_cancel()
213 * @see alarm_cancel_all()
214 * @see alarm_get_scheduled_date()
216 int alarm_schedule_once_at_date(app_control_h app_control, struct tm *date, int *alarm_id);
220 * @brief Sets an alarm to be triggered periodically, starting at a specific time.
221 * @details The @a date describes the time of the first occurrence.
222 * @a week_flag is the repeat value of the days of the week.
223 * If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time.
224 * To cancel the alarm, call alarm_cancel() with @a alarm_id.
225 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
227 * @privilege %http://tizen.org/privilege/alarm.set
228 * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
229 * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
230 * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
231 * Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, The @a app_control only supports UI application with this api. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
232 * When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
233 * Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
235 * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
236 * @param[in] date The first active alarm time
237 * @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
238 * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
239 * @return @c 0 on success,
240 * otherwise a negative error value
241 * @retval #ALARM_ERROR_NONE Successful
242 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
243 * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
244 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
245 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
246 * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
247 * @see alarm_cancel()
248 * @see alarm_cancel_all()
249 * @see alarm_get_scheduled_recurrence_week_flag()
250 * @see alarm_get_scheduled_date()
251 * @see #alarm_week_flag_e
253 int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct tm *date, int week_flag,int *alarm_id);
257 * @brief Gets the recurrence days of the week.
258 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
260 * @privilege %http://tizen.org/privilege/alarm.get
261 * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function,
262 * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence.
263 * If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
264 * If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
265 * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
266 * @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
267 * @return @c 0 on success,
268 * otherwise a negative error value
269 * @retval #ALARM_ERROR_NONE Successful
270 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
271 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
272 * @see alarm_schedule_with_recurrence_week_flag()
273 * @see #alarm_week_flag_e
275 int alarm_get_scheduled_recurrence_week_flag(int alarm_id, int *week_flag);
279 * @brief Cancels the alarm with the specific alarm ID.
280 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
282 * @privilege %http://tizen.org/privilege/alarm.set
283 * @param[in] alarm_id The alarm ID that is cancelled
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()
293 * @see alarm_cancel_all()
295 int alarm_cancel(int alarm_id);
299 * @brief Cancels all scheduled alarms that are registered by the application that calls this API.
300 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
302 * @privilege %http://tizen.org/privilege/alarm.set
303 * @return @c 0 on success,
304 * otherwise a negative error value
305 * @retval #ALARM_ERROR_NONE Successful
306 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
307 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
308 * @see alarm_schedule_at_date()
309 * @see alarm_schedule_after_delay()
310 * @see alarm_schedule_with_recurrence_week_flag()
311 * @see alarm_cancel()
313 int alarm_cancel_all(void);
317 * @brief Retrieves the IDs of all registered alarms by invoking a callback once for each scheduled alarm.
318 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
320 * @privilege %http://tizen.org/privilege/alarm.get
321 * @param[in] callback The callback function to invoke
322 * @param[in] user_data The user data to be passed to the callback function
323 * @return @c 0 on success,
324 * otherwise a negative error value
325 * @retval #ALARM_ERROR_NONE Successful
326 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
327 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
328 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
329 * @post This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm.
330 * @see alarm_registered_alarm_cb()
332 int alarm_foreach_registered_alarm(alarm_registered_alarm_cb callback, void *user_data);
336 * @brief Gets the scheduled time from the given alarm ID in C standard time struct.
337 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
339 * @privilege %http://tizen.org/privilege/alarm.get
340 * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
341 * @param[out] date The time value of the next alarm event
342 * @return @c 0 on success,
343 * otherwise a negative error value
344 * @retval #ALARM_ERROR_NONE Successful
345 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
346 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
347 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
348 * @see alarm_schedule_at_date()
349 * @see alarm_schedule_after_delay()
350 * @see alarm_schedule_with_recurrence_week_flag()
352 int alarm_get_scheduled_date(int alarm_id, struct tm *date);
356 * @brief Gets the period of time between the recurrent alarms.
357 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
359 * @privilege %http://tizen.org/privilege/alarm.get
360 * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_at_date() or alarm_schedule_after_delay() function,
361 * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur.
362 * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
363 * @param[out] period The period of time between recurrent alarms in seconds
364 * @return @c 0 on success,
365 * otherwise a negative error value
366 * @retval #ALARM_ERROR_NONE Successful
367 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
368 * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
369 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
370 * @see alarm_schedule_at_date()
371 * @see alarm_schedule_after_delay()
372 * @see alarm_schedule_with_recurrence_week_flag()
374 int alarm_get_scheduled_period(int alarm_id, int *period);
378 * @brief Gets the current system time using C standard time struct.
379 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
380 * @param[out] date The current system time
381 * @return @c 0 on success,
382 * otherwise a negative error value
383 * @retval #ALARM_ERROR_NONE Successful
384 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
385 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
387 int alarm_get_current_time(struct tm *date);
391 * @brief Gets the app_control to be invoked when the the alarm is triggered.
392 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
394 * @privilege %http://tizen.org/privilege/alarm.get
395 * @remarks The @a app_control must be released using app_control_destroy().
396 * @param[in] alarm_id The alarm ID uniquely identifies an alarm
397 * @param[out] app_control The app_control handle to launch when the alarm is triggered
398 * @return @c 0 on success,
399 * otherwise a negative error value
400 * @retval #ALARM_ERROR_NONE Successful
401 * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
402 * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
403 * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
404 * @see alarm_schedule_at_date()
405 * @see alarm_schedule_after_delay()
406 * @see alarm_schedule_with_recurrence_week_flag()
408 int alarm_get_app_control(int alarm_id, app_control_h *app_control);
418 #endif /* __TIZEN_APPFW_ALARM_H__ */