1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
/*
* Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the License);
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an AS IS BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __TIZEN_APPFW_ALARM_H__
#define __TIZEN_APPFW_ALARM_H__
#include <tizen.h>
#include <time.h>
#include <app_service.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @addtogroup CAPI_ALARM_MODULE
* @{
*/
/**
* @brief Service extra data : the id of the alarm registered
*/
#define SERVICE_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id"
/**
* @brief Enumerations of error codes for the alarm
*/
typedef enum
{
ALARM_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
ALARM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
ALARM_ERROR_INVALID_TIME = TIZEN_ERROR_APPLICATION_CLASS | 0x05, /**< Invalid time */
ALARM_ERROR_INVALID_DATE = TIZEN_ERROR_APPLICATION_CLASS | 0x06, /**< Invalid date */
ALARM_ERROR_CONNECTION_FAIL = TIZEN_ERROR_APPLICATION_CLASS | 0x07, /**< The alarm service connection failed */
ALARM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY /**< Out of memory */
} alarm_error_e;
/**
* @brief Enumerations of the days of the week.
*/
typedef enum
{
ALARM_WEEK_FLAG_SUNDAY = 0x01, /**< Sunday */
ALARM_WEEK_FLAG_MONDAY = 0x02, /**< Monday */
ALARM_WEEK_FLAG_TUESDAY = 0x04, /**< Tuesday */
ALARM_WEEK_FLAG_WEDNESDAY = 0x08, /**< Wednesday */
ALARM_WEEK_FLAG_THURSDAY = 0x10, /**< Thursday */
ALARM_WEEK_FLAG_FRIDAY = 0x20, /**< Friday */
ALARM_WEEK_FLAG_SATURDAY = 0x40 /**< Saturday */
} alarm_week_flag_e;
/**
* @brief Called once for each scheduled alarm to get the alarm ID.
*
* @param[in] alarm_id The alarm ID returned when the alarm is scheduled
* @param[in] user_data The user data passed from the foreach function
* @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
* @pre alarm_foreach_registered_alarm() will invoke this callback to get all registered alarm IDs.
* @see alarm_foreach_registered_alarm()
*/
typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data);
/**
* @brief Sets an alarm to be triggered after specific time.
* @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.
* If @a period is bigger than 0, the alarm will be scheduled after the @a period time.
* If @a period is set to 0, the alarm will go off just once without repetition.
* To cancel the alarm, call alarm_cancel() with @alarm_id
*
* @remarks If application is uninstalled after setting an alarm, the alarm is canceled automatically.
*
* @param[in] service The destination service to perform specific work when the alarm is triggered.
* @param[in] delay The amount of time before first execution(in second)
* @param[in] period The amount of time between subsequent alarms(in second)
* @param[out] alarm_id The alarm ID uniquely identifies an alarm
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid
* @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
* @see alarm_cancel()
* @see alarm_cancel_all()
* @see alarm_get_scheduled_date()
* @see alarm_get_scheduled_period()
*/
int alarm_schedule_after_delay(service_h service, int delay, int period, int *alarm_id);
/**
* @brief Sets an alarm to be triggered at a specific time.
* @details
* The @a date describes the time of first occurrence.
* If @a period is bigger than 0, the alarm will be scheduled after the @a period time.
* If @a period is set to 0, the alarm will go off just once without repetition.
* To cancel the alarm, call alarm_cancel() with alarm id
*
* @remarks If application is uninstalled after setting an alarm, the alarm is canceled automatically.
*
* @param[in] service The destination service to perform specific work when the alarm is triggered
* @param[in] date The first active alarm time
* @param[in] period The amount of time between subsequent alarms(in second)
* @param[out] alarm_id The alarm ID uniquely identifies an alarm
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
* @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
* @see alarm_cancel()
* @see alarm_cancel_all()
* @see alarm_get_scheduled_date()
* @see alarm_get_scheduled_period()
*/
int alarm_schedule_at_date(service_h service, struct tm *date, int period, int *alarm_id);
/**
* @brief Sets an alarm to be triggered at a specific time with recurrence repeat.
* @details
* The @a date describes the time of first occurrence.
* @a week_flag is the repeat value of days of the week. If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat at every Tuesday specific time.
* To cancel the alarm, call alarm_cancel() with the @alarm_id
* @remarks If application is uninstalled after setting an alarm, the alarm is canceled automatically.
*
* @param[in] service The destination service to perform specific work when the alarm is triggered.
* @param[in] date The first active alarm time
* @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.
* @param[out] alarm_id The alarm ID uniquely identifies an alarm
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
* @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
* @see alarm_cancel()
* @see alarm_cancel_all()
* @see alarm_get_scheduled_recurrence_week_flag()
* @see alarm_get_scheduled_recurrence_week_flag()
* @see alarm_get_scheduled_date()
* @see #alarm_week_flag_e
*/
int alarm_schedule_with_recurrence_week_flag(service_h service, struct tm *date, int week_flag,int *alarm_id);
/**
* @brief Gets the recurrence days of the week.
* @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function,
* an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence.
* @param[in] alarm_id The alarm ID returned when the alarm is scheduled
* @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.
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
* @see alarm_schedule_with_recurrence_week_flag()
* @see #alarm_week_flag_e
*/
int alarm_get_scheduled_recurrence_week_flag(int alarm_id, int *week_flag);
/**
* @brief Cancels the alarm with the specific alarm ID.
* @param[in] alarm_id The alarm ID that will be canceled
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
* @see alarm_schedule_at_date()
* @see alarm_schedule_after_delay()
* @see alarm_schedule_with_recurrence_week_flag()
* @see alarm_cancel_all()
*/
int alarm_cancel(int alarm_id);
/**
* @brief Cancels all alarms scheduled.
*
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
* @see alarm_schedule_at_date()
* @see alarm_schedule_after_delay()
* @see alarm_schedule_with_recurrence_week_flag()
* @see alarm_cancel()
*/
int alarm_cancel_all(void);
/**
* @brief Retrieves the IDs of all registered alarms by invoking callback once for each scheduled alarm.
*
* @param[in] callback The callback function to invoke
* @param[in] user_data The user data to be passed to the callback function
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
* @post This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm.
* @see alarm_registered_alarm_cb()
*/
int alarm_foreach_registered_alarm(alarm_registered_alarm_cb callback, void *user_data);
/**
* @brief Gets the scheduled time from the given alarm ID in C standard time struct.
*
* @param[in] alarm_id The alarm ID returned when the alarm is scheduled
* @param[out] date The time value of next alarm event
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
* @see alarm_schedule_at_date()
* @see alarm_schedule_after_delay()
* @see alarm_schedule_with_recurrence_week_flag()
*/
int alarm_get_scheduled_date(int alarm_id, struct tm *date);
/**
* @brief Gets the period of time between the recurrent alarms.
* @remarks If the given @a alarm_id is not obtained by using the alarm_get_scheduled_date() or alarm_schedule_after_delay() function,
* an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur.
* @param[in] alarm_id The alarm ID returned when the alarm is scheduled
* @param[out] period The period of time between recurrent alarms in seconds
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
* @see alarm_schedule_at_date()
* @see alarm_schedule_after_delay()
* @see alarm_schedule_with_recurrence_week_flag()
*/
int alarm_get_scheduled_period(int alarm_id, int *period);
/**
* @brief Gets the current system time using C standard time struct.
*
* @param[out] date The current system time
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
*/
int alarm_get_current_time(struct tm *date);
/**
* @brief Gets the service to be invoked when the the alarm is triggered
* @remarks The @a service must be released with service_destroy() by you.
* @param[in] alarm_id The alarm ID uniquely identifies an alarm
* @param[out] service The service handle to launch when the alarm is triggered
* @return 0 on success, otherwise a negative error value.
* @retval #ALARM_ERROR_NONE Successful
* @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
* @see alarm_schedule_at_date()
* @see alarm_schedule_after_delay()
* @see alarm_schedule_with_recurrence_week_flag()
*/
int alarm_get_service(int alarm_id, service_h *service);
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif /* __TIZEN_APPFW_ALARM_H__ */
|
