4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Venkatesha Sarpangala <sarpangala.v@samsung.com>, Jayoun Lee <airjany@samsung.com>,
7 * Sewook Park <sewook7.park@samsung.com>, Jaeho Lee <jaeho81.lee@samsung.com>
9 * Licensed under the Apache License, Version 2.0 (the "License");
10 * you may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
13 * http://www.apache.org/licenses/LICENSE-2.0
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
27 @defgroup SLP_PG_ALARM_MANAGER Alarm
30 <h1 class="pg">Introduction</h1>
32 <h2 class="pg">Purpose of this document</h2>
33 The purpose of this document is to describe how applications can use Alarm Manager APIs for handling alarms. This document gives programming guidelines to application engineers.
35 <h2 class="pg">Scope</h2>
36 The scope of this document is limited to Alarm Manager API usage.
39 <h1 class="pg">Architecture</h1>
41 <h2 class="pg">Architecture overview</h2>
42 The Alarm Manager provides functionality for applications to create, delete and configure alarms. Applications register alarm information and the Alarm Manager manages the alarm information, generates timer and schedule alarms. When the timer expires, the Alarm Manager sends an event to the applications.
44 @image html SLP_Alarm_PG_overview.png
46 <h2 class="pg">SLP Features</h2>
47 - The Alarm Manager exposes a high level interface that is used by applications.
48 - The Alarm Manager and applications use D-Bus as its underlying IPC mechanism.
49 - The Alarm Manager uses DB to store the alarm information internally.
50 - The Alarm Manager uses system timers for setting expiration time.
53 <h1 class="pg">Alarm manager properties</h1>
55 <h2 class="pg">Time</h2>
56 There are two types of alarm. The alarm type is distinguished by the following APIs
57 - alarmmgr_add_alarm_with_localtime
58 - The alarm expires at a specified time. The localtime is set by the application in the alarm_entry_t parameter through alarmmgr_set_time().
60 - The alarm expires after a specified interval (in seconds).
62 <h2 class="pg">Repeat mode</h2>
64 - ONCE: In this mode, the alarm expires only once. After it expires, the alarm is removed from alarm server.
65 - REPEAT: In this mode, the alarm is expires repeatly.
66 - WEEKLY: In this mode, the alarm expires weekly on the days specified by the day_of_week parameter.
67 - MONTHLY: In this mode, the alarm expires once a month from the start date.
68 - ANNUALY: In this mode, the alarm expires once a year from the start date.
71 - ALARM_REPEAT_MODE_REPEAT : In this mode, the alarm is repeated at a interval specified in the interval parameter
72 - ALARM_REPEAT_MODE_WEEKLY : In this mode, the alarm is repeated at a weekly interval
78 ALARM_WDAY_SUNDAY=0x01,
79 ALARM_WDAY_MONDAY=0x02,
80 ALARM_WDAY_TUESDAY=0x04,
81 ALARM_WDAY_WEDNESDAY=0x08,
82 ALARM_WDAY_THURSDAY=0x10,
83 ALARM_WDAY_FRIDAY=0x20,
84 ALARM_WDAY_SATURDAY=0x40,
89 <h2 class="pg">Alarm type</h2>
90 - ALARM_TYPE_DEFAULT : The alarm information is saved using DB. After a device reboot, the alarm still exists.
91 - ALARM_TYPE_VOLATILE : The alarm information is not saved using DB. After a device reboot, the alarm no longer exists.
95 <h1 class="pg">Alarm manager features with sample code</h3>
97 <h2 class="pg">Add an Alarm to the server</h2>
98 An application can add an alarm to the alarm server by using below two ways.
100 1. by alarmmgr_add_alarm
102 int alarmmgr_add_alarm(int alarm_type,
103 time_t trigger_at_time,
105 const char* destination,
106 alarm_id_t* alarm_id);
108 As shown in the sample code below, alrmmgr_init is used to initalize the alarm library. alarmmgr_set_cb is called to set the callback for handling the alarm events. create_test function is called to create an alarm. In the create_test function the alarmmgr_add_alarm() function is called.
112 - Trigger_at_time is the interval after which the alarm is triggered.
113 - If the package that receives the events is different from the package to add an alarm, the application has to write the destination package name.
114 - If the interval is zero, the repeat_mode is ALARM_REPEAT_MODE_ONCE.
115 - If the interval is >0, the repeat_mode is ALARM_REPEAT_MODE_REPEAT.
124 int callback(alarm_id_t alarm_id,void* user_param)
130 printf("Alarm[%d] has expired at %s\n", alarm_id, ctime(¤t_time));
144 printf("current time: %s\n", ctime(¤t_time));
147 alarmmgr_add_alarm(ALARM_TYPE_DEFAULT, 60, 10, NULL,& alarm_id);
148 if(result != ALARMMGR_RESULT_SUCCESS)
149 printf("fail to alarmmgr_create : error_code : %d\n",result);
153 int main(int argc, char** argv)
161 mainloop = g_main_loop_new(NULL, FALSE);
163 result = alarmmgr_init("org.tizen.test");
165 if(result != ALARMMGR_RESULT_SUCCESS)
167 printf("fail to alarmmgr_init : error_code : %d\n",result);
171 result = alarmmgr_set_cb(callback,NULL);
173 if(result != ALARMMGR_RESULT_SUCCESS)
175 printf("fail to alarmmgr_set_cb : error_code : %d\n",result);
182 g_main_loop_run(mainloop);
186 2. by alarmmgr_add_alarm_with_localtime
188 alarm_entry_t* alarmmgr_create_alarm(void);
190 int alarmmgr_set_time(alarm_entry_t* alarm, alarm_date_t time);
192 int alarmmgr_set_repeat_mode(alarm_entry_t* alarm,
193 alarm_repeat_mode_t repeat_mode,
196 int alarmmgr_set_type(alarm_entry_t* alarm, int alarm_type);
198 int alarmmgr_add_alarm_with_localtime(alarm_entry_t* alarm,
199 const char* destination,
200 alarm_id_t* alarm_id);
201 int alarmmgr_remove_alarm(alarm_id_t alarm_id);
203 In this sample code, the application creates an alarm object using the alarmmgr_create_alarm function. Then the alarmmgr_set_*() functions are used to set the attributes of the alarm entry. Finally, the application adds an alarm to the alarm server using alarmmgr_add_alarm_with_localtime. If the application doesn't need the object (alarm entry), the application has to free the memory using the alarmmgr_remove_alarm() function.
206 - Time is localtime. For example, if the alarm is set to expire at 2010/10/3 15:00, even if the system time is changed or the timezone is changed, the alarm will expire at 2010/10/3 15:00.
207 - If the package that receives the events is different from the package to add an alarm, the application has to write the destination package name.
208 - ALARM_REPEAT_MODE_REPEAT : In this mode, the alarm is repeated at a interval specified in the interval parameter
209 - ALARM_REPEAT_MODE_WEEKLY : In this mode, the alarm is repeated at a weekly interval
218 int callback(alarm_id_t alarm_id,void* user_param)
224 printf("Alarm[%d] has expired at %s\n", alarm_id, ctime(¤t_time));
233 struct tm current_tm;
234 alarm_entry_t* alarm_info;
237 alarm_date_t test_time;
241 printf("current time: %s\n", ctime(¤t_time));
242 localtime_r(¤t_time, ¤t_tm);
244 alarm_info = alarmmgr_create_alarm();
250 test_time.hour = current_tm.tm_hour;
251 test_time.min = current_tm.tm_min+1;
255 alarmmgr_set_time(alarm_info,test_time);
256 alarmmgr_set_repeat_mode(alarm_info,ALARM_REPEAT_MODE_WEEKLY,ALARM_WDAY_MONDAY| \
257 ALARM_WDAY_TUESDAY|ALARM_WDAY_WEDNESDAY| \
258 ALARM_WDAY_THURSDAY|ALARM_WDAY_FRIDAY );
260 alarmmgr_set_type(alarm_info,ALARM_TYPE_VOLATILE);
261 alarmmgr_add_alarm_with_localtime(alarm_info,NULL,&alarm_id);
262 if(result != ALARMMGR_RESULT_SUCCESS)
263 printf("fail to alarmmgr_create : error_code : %d\n",result);
267 int main(int argc, char** argv)
275 mainloop = g_main_loop_new(NULL, FALSE);
277 result = alarmmgr_init("org.tizen.test");
279 if(result != ALARMMGR_RESULT_SUCCESS)
281 printf("fail to alarmmgr_init : error_code : %d\n",result);
285 result = alarmmgr_set_cb(callback,NULL);
287 if(result != ALARMMGR_RESULT_SUCCESS)
289 printf("fail to alarmmgr_set_cb : error_code : %d\n",result);
296 g_main_loop_run(mainloop);
300 <h2 class="pg">Get alarm info</h2>
301 The application can retrieve alarm information from the alarm server using the alarmmgr_get_info & alarmmgr_enum_alarm_ids APIs
310 int test_callback (alarm_id_t id, void* user_param)
312 alarm_entry_t* alarm;
313 alarm = alarmmgr_create_alarm();
314 int* n = (int*)user_param;
315 printf("[%d]alarm id : %d\n",*n,id);
317 alarmmgr_get_info(id, alarm); //the application use this object(alarm)
322 alarmmgr_enum_alarm_ids(test_callback,(void*)&n);