include/SLP_Alarm_PG.h

   1 /*
   2  *  alarm-manager
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   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>
   8  *
   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
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  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.
  20  *
  21  */
  22
  23
  24
  25 /**
  26  @ingroup SLP_PG
  27  @defgroup SLP_PG_ALARM_MANAGER Alarm
  28  @{
  29
  30 <h1 class="pg">Introduction</h1>
  31
  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.
  34
  35 <h2 class="pg">Scope</h2>
  36 The scope of this document is limited to Alarm Manager API usage.
  37
  38
  39 <h1 class="pg">Architecture</h1>
  40
  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.
  43
  44 @image html SLP_Alarm_PG_overview.png
  45
  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.
  51
  52
  53 <h1 class="pg">Alarm manager properties</h1>
  54
  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().
  59 - alarmmgr_add_alarm
  60         - The alarm expires after a specified interval (in seconds).
  61
  62 <h2 class="pg">Repeat mode</h2>
  63 - Repeat mode
  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.
  69
  70 - Repeat value
  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
  73
  74
  75 @code
  76 typedef enum
  77 {
  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,
  85 }alarm_day_of_week_t;
  86 @endcode
  87
  88
  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.
  92
  93
  94
  95 <h1 class="pg">Alarm manager features with sample code</h3>
  96
  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.
  99
 100 1.  by alarmmgr_add_alarm
 101 @code
 102 int alarmmgr_add_alarm(int alarm_type,
 103 time_t trigger_at_time,
 104 time_t interval,
 105 const char* destination,
 106 alarm_id_t* alarm_id);
 107 @endcode
 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.
 109
 110
 111         - Note:
 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.
 116
 117 @code
 118 #include<stdio.h>
 119 #include<stdlib.h>
 120 #include<glib.h>
 121
 122 #include <alarm.h>
 123
 124 int callback(alarm_id_t alarm_id,void* user_param)
 125 {
 126         int error;
 127         time_t current_time;
 128         time(&current_time);
 129
 130         printf("Alarm[%d] has expired at %s\n", alarm_id, ctime(&current_time));
 131
 132         return 0;
 133
 134 }
 135
 136 void create_test()
 137 {
 138                 time_t current_time;
 139                 alarm_id_t alarm_id;
 140                 int result;
 141
 142                 time(&current_time);
 143
 144                 printf("current time: %s\n", ctime(&current_time));
 145
 146
 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);
 150
 151 }
 152
 153 int main(int argc, char** argv)
 154 {
 155         int error_code;
 156         GMainLoop *mainloop;
 157                 int result;
 158
 159         g_type_init();
 160
 161         mainloop = g_main_loop_new(NULL, FALSE);
 162
 163         result = alarmmgr_init("org.tizen.test");
 164
 165                 if(result != ALARMMGR_RESULT_SUCCESS)
 166                 {
 167                         printf("fail to alarmmgr_init : error_code : %d\n",result);
 168                 }
 169                 else{
 170
 171            result = alarmmgr_set_cb(callback,NULL);
 172
 173                   if(result != ALARMMGR_RESULT_SUCCESS)
 174                         {
 175                                 printf("fail to alarmmgr_set_cb : error_code : %d\n",result);
 176                         }
 177                         else{
 178                                 create_test();
 179                         }
 180                 }
 181
 182         g_main_loop_run(mainloop);
 183 }
 184 @endcode
 185
 186 2.  by alarmmgr_add_alarm_with_localtime
 187 @code
 188 alarm_entry_t* alarmmgr_create_alarm(void);
 189
 190 int alarmmgr_set_time(alarm_entry_t* alarm, alarm_date_t time);
 191
 192 int alarmmgr_set_repeat_mode(alarm_entry_t* alarm,
 193 alarm_repeat_mode_t repeat_mode,
 194 int repeat_value);
 195
 196 int alarmmgr_set_type(alarm_entry_t* alarm, int alarm_type);
 197
 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);
 202 @endcode
 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.
 204
 205         - Note:
 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
 210
 211 @code
 212 #include<stdio.h>
 213 #include<stdlib.h>
 214 #include<glib.h>
 215
 216 #include <alarm.h>
 217
 218 int callback(alarm_id_t alarm_id,void* user_param)
 219 {
 220         int error;
 221         time_t current_time;
 222         time(&current_time);
 223
 224         printf("Alarm[%d] has expired at %s\n", alarm_id, ctime(&current_time));
 225
 226         return 0;
 227
 228 }
 229
 230 void create_test()
 231 {
 232         time_t current_time;
 233         struct tm current_tm;
 234         alarm_entry_t* alarm_info;
 235         alarm_id_t alarm_id;
 236         int result;
 237         alarm_date_t test_time;
 238
 239         time(&current_time);
 240
 241         printf("current time: %s\n", ctime(&current_time));
 242         localtime_r(&current_time, &current_tm);
 243
 244         alarm_info = alarmmgr_create_alarm();
 245
 246         test_time.year = 0;
 247                                 test_time.month = 0;
 248                                 test_time.day = 0;
 249
 250                                 test_time.hour = current_tm.tm_hour;
 251                                 test_time.min = current_tm.tm_min+1;
 252                                 test_time.sec = 0;
 253
 254
 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 );
 259
 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);
 264
 265 }
 266
 267 int main(int argc, char** argv)
 268 {
 269         int error_code;
 270         GMainLoop *mainloop;
 271                 int result;
 272
 273         g_type_init();
 274
 275         mainloop = g_main_loop_new(NULL, FALSE);
 276
 277         result = alarmmgr_init("org.tizen.test");
 278
 279                 if(result != ALARMMGR_RESULT_SUCCESS)
 280                 {
 281                         printf("fail to alarmmgr_init : error_code : %d\n",result);
 282                 }
 283                 else{
 284
 285            result = alarmmgr_set_cb(callback,NULL);
 286
 287                    if(result != ALARMMGR_RESULT_SUCCESS)
 288                         {
 289                                 printf("fail to alarmmgr_set_cb : error_code : %d\n",result);
 290                         }
 291                         else{
 292                                 create_test();
 293                         }
 294                 }
 295
 296         g_main_loop_run(mainloop);
 297 }
 298 @endcode
 299
 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
 302
 303
 304 @code
 305 #include<stdio.h>
 306 #include<stdlib.h>
 307 #include<glib.h>
 308 #include "alarm.h"
 309
 310 int test_callback (alarm_id_t id, void* user_param)
 311 {
 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);
 316         (*n)++;
 317        alarmmgr_get_info(id, alarm);   //the application use this object(alarm)
 318 }
 319 sample_get_info()
 320 {
 321         int n=1;
 322         alarmmgr_enum_alarm_ids(test_callback,(void*)&n);
 323 }
 324 @endcode
 325
 326
 327  @}
 328 **/