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 AlarmManager
  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 Refer to Picture 1. for Overview.
  45
  46 <h1 class="pg">AlarmManager Overview</h1>
  47 \image html SLP_Alarm_PG_overview.png "Picture 1. AlarmManager Overview"
  48 \image rtf SLP_Alarm_PG_overview.png "Picture 1. AlarmManager Overview"
  49
  50 <h1 class="pg">AlarmManager Process view</h1>
  51
  52 <h2 class="pg">AlarmManager Process view</h2>
  53  Applications register alarm information using AlarmManager API's. Alarm Manager manages the alarm information in DB, generates timer and schedule alarms. When the timer expires, the Alarm Manager sends an event to the application. If auto-activation of application is enabled then, alarm manager launches the application using app-svc.
  54
  55 Refer to Picture 2. for AlarmManager Process view.
  56
  57 <h1 class="pg">AlarmManager Process view</h1>
  58 \image html SLP_Alarm_PG_processview.png "Picture 1. AlarmManager Process view"
  59 \image rtf SLP_Alarm_PG_processview.png "Picture 1. AlarmManager Process view"
  60
  61
  62 <h2 class="pg">SLP Features</h2>
  63 - The Alarm Manager exposes a high level interface that is used by applications.
  64 - The Alarm Manager and applications use D-Bus as its underlying IPC mechanism.
  65 - The Alarm Manager uses DB to store the alarm information internally.
  66 - The Alarm Manager uses system timers for setting expiration time.
  67
  68
  69 <h1 class="pg">Alarm manager properties</h1>
  70
  71 <h2 class="pg">Time</h2>
  72 There are two types of alarm. The alarm type is distinguished by the following APIs
  73 - alarmmgr_add_alarm_with_localtime
  74         - The alarm expires at a specified time. The localtime is set by the application in the alarm_entry_t parameter through alarmmgr_set_time().
  75 - alarmmgr_add_alarm
  76         - The alarm expires after a specified interval (in seconds).
  77
  78 <h2 class="pg">Repeat mode</h2>
  79 - Repeat mode
  80         - ONCE: In this mode, the alarm expires only once. After it expires, the alarm is removed from alarm server.
  81         - REPEAT: In this mode, the alarm is expires repeatly.
  82         - WEEKLY: In this mode, the alarm expires weekly on the days specified by the day_of_week parameter.
  83         - MONTHLY: In this mode, the alarm expires once a month from the start date.
  84         - ANNUALY: In this mode, the alarm expires once a year from the start date.
  85
  86 - Repeat value
  87         - ALARM_REPEAT_MODE_REPEAT : In this mode, the alarm is repeated at a interval specified in the interval parameter
  88         - ALARM_REPEAT_MODE_WEEKLY : In this mode, the alarm is repeated at a weekly interval
  89
  90
  91 @code
  92 typedef enum
  93 {
  94         ALARM_WDAY_SUNDAY=0x01,
  95         ALARM_WDAY_MONDAY=0x02,
  96         ALARM_WDAY_TUESDAY=0x04,
  97         ALARM_WDAY_WEDNESDAY=0x08,
  98         ALARM_WDAY_THURSDAY=0x10,
  99         ALARM_WDAY_FRIDAY=0x20,
 100         ALARM_WDAY_SATURDAY=0x40,
 101 }alarm_day_of_week_t;
 102 @endcode
 103
 104
 105 <h2 class="pg">Alarm type</h2>
 106 - ALARM_TYPE_DEFAULT : The alarm information is saved using DB. After a device reboot, the alarm still exists.
 107 - ALARM_TYPE_VOLATILE : The alarm information is not saved using DB. After a device reboot, the alarm no longer exists.
 108
 109
 110
 111 <h1 class="pg">Alarm manager features with sample code</h3>
 112
 113 <h2 class="pg">Add an Alarm to the server</h2>
 114 An application can add an alarm to the alarm server by using below two ways.
 115
 116 1.  by alarmmgr_add_alarm
 117 @code
 118 int alarmmgr_add_alarm(int alarm_type,
 119 time_t trigger_at_time,
 120 time_t interval,
 121 const char* destination,
 122 alarm_id_t* alarm_id);
 123 @endcode
 124 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.
 125
 126
 127         - Note:
 128                 - Trigger_at_time is the interval after which the alarm is triggered.
 129                 - 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.
 130                 - If the interval is zero, the repeat_mode is ALARM_REPEAT_MODE_ONCE.
 131                 - If the interval is >0, the repeat_mode is ALARM_REPEAT_MODE_REPEAT.
 132
 133 @code
 134 #include<stdio.h>
 135 #include<stdlib.h>
 136 #include<glib.h>
 137
 138 #include <alarm.h>
 139
 140 int callback(alarm_id_t alarm_id,void* user_param)
 141 {
 142         int error;
 143         time_t current_time;
 144         time(&current_time);
 145
 146         printf("Alarm[%d] has expired at %s\n", alarm_id, ctime(&current_time));
 147
 148         return 0;
 149
 150 }
 151
 152 void create_test()
 153 {
 154                 time_t current_time;
 155                 alarm_id_t alarm_id;
 156                 int result;
 157
 158                 time(&current_time);
 159
 160                 printf("current time: %s\n", ctime(&current_time));
 161
 162
 163                 alarmmgr_add_alarm(ALARM_TYPE_DEFAULT, 60, 10, NULL,& alarm_id);
 164                 if(result != ALARMMGR_RESULT_SUCCESS)
 165                         printf("fail to alarmmgr_create : error_code : %d\n",result);
 166
 167 }
 168
 169 int main(int argc, char** argv)
 170 {
 171         int error_code;
 172         GMainLoop *mainloop;
 173                 int result;
 174
 175         g_type_init();
 176
 177         mainloop = g_main_loop_new(NULL, FALSE);
 178
 179         result = alarmmgr_init("org.tizen.test");
 180
 181                 if(result != ALARMMGR_RESULT_SUCCESS)
 182                 {
 183                         printf("fail to alarmmgr_init : error_code : %d\n",result);
 184                 }
 185                 else{
 186
 187            result = alarmmgr_set_cb(callback,NULL);
 188
 189                   if(result != ALARMMGR_RESULT_SUCCESS)
 190                         {
 191                                 printf("fail to alarmmgr_set_cb : error_code : %d\n",result);
 192                         }
 193                         else{
 194                                 create_test();
 195                         }
 196                 }
 197
 198         g_main_loop_run(mainloop);
 199 }
 200 @endcode
 201
 202 2.  by alarmmgr_add_alarm_with_localtime
 203 @code
 204 alarm_entry_t* alarmmgr_create_alarm(void);
 205
 206 int alarmmgr_set_time(alarm_entry_t* alarm, alarm_date_t time);
 207
 208 int alarmmgr_set_repeat_mode(alarm_entry_t* alarm,
 209 alarm_repeat_mode_t repeat_mode,
 210 int repeat_value);
 211
 212 int alarmmgr_set_type(alarm_entry_t* alarm, int alarm_type);
 213
 214 int alarmmgr_add_alarm_with_localtime(alarm_entry_t* alarm,
 215 const char* destination,
 216 alarm_id_t* alarm_id);
 217  int alarmmgr_remove_alarm(alarm_id_t alarm_id);
 218 @endcode
 219 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.
 220
 221         - Note:
 222                 - 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.
 223                 - 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.
 224                 - ALARM_REPEAT_MODE_REPEAT : In this mode, the alarm is repeated at a interval specified in the interval parameter
 225                 - ALARM_REPEAT_MODE_WEEKLY : In this mode, the alarm is repeated at a weekly interval
 226
 227 @code
 228 #include<stdio.h>
 229 #include<stdlib.h>
 230 #include<glib.h>
 231
 232 #include <alarm.h>
 233
 234 int callback(alarm_id_t alarm_id,void* user_param)
 235 {
 236         int error;
 237         time_t current_time;
 238         time(&current_time);
 239
 240         printf("Alarm[%d] has expired at %s\n", alarm_id, ctime(&current_time));
 241
 242         return 0;
 243
 244 }
 245
 246 void create_test()
 247 {
 248         time_t current_time;
 249         struct tm current_tm;
 250         alarm_entry_t* alarm_info;
 251         alarm_id_t alarm_id;
 252         int result;
 253         alarm_date_t test_time;
 254
 255         time(&current_time);
 256
 257         printf("current time: %s\n", ctime(&current_time));
 258         localtime_r(&current_time, &current_tm);
 259
 260         alarm_info = alarmmgr_create_alarm();
 261
 262         test_time.year = 0;
 263                                 test_time.month = 0;
 264                                 test_time.day = 0;
 265
 266                                 test_time.hour = current_tm.tm_hour;
 267                                 test_time.min = current_tm.tm_min+1;
 268                                 test_time.sec = 0;
 269
 270
 271         alarmmgr_set_time(alarm_info,test_time);
 272         alarmmgr_set_repeat_mode(alarm_info,ALARM_REPEAT_MODE_WEEKLY,ALARM_WDAY_MONDAY| \
 273                                                                                                                                                         ALARM_WDAY_TUESDAY|ALARM_WDAY_WEDNESDAY| \
 274                                             ALARM_WDAY_THURSDAY|ALARM_WDAY_FRIDAY );
 275
 276         alarmmgr_set_type(alarm_info,ALARM_TYPE_VOLATILE);
 277         alarmmgr_add_alarm_with_localtime(alarm_info,NULL,&alarm_id);
 278         if(result != ALARMMGR_RESULT_SUCCESS)
 279                 printf("fail to alarmmgr_create : error_code : %d\n",result);
 280
 281 }
 282
 283 int main(int argc, char** argv)
 284 {
 285         int error_code;
 286         GMainLoop *mainloop;
 287                 int result;
 288
 289         g_type_init();
 290
 291         mainloop = g_main_loop_new(NULL, FALSE);
 292
 293         result = alarmmgr_init("org.tizen.test");
 294
 295                 if(result != ALARMMGR_RESULT_SUCCESS)
 296                 {
 297                         printf("fail to alarmmgr_init : error_code : %d\n",result);
 298                 }
 299                 else{
 300
 301            result = alarmmgr_set_cb(callback,NULL);
 302
 303                    if(result != ALARMMGR_RESULT_SUCCESS)
 304                         {
 305                                 printf("fail to alarmmgr_set_cb : error_code : %d\n",result);
 306                         }
 307                         else{
 308                                 create_test();
 309                         }
 310                 }
 311
 312         g_main_loop_run(mainloop);
 313 }
 314 @endcode
 315
 316 <h2 class="pg">Get alarm info</h2>
 317 The application can retrieve alarm information from the alarm server using the alarmmgr_get_info & alarmmgr_enum_alarm_ids APIs
 318
 319
 320 @code
 321 #include<stdio.h>
 322 #include<stdlib.h>
 323 #include<glib.h>
 324 #include "alarm.h"
 325
 326 int test_callback (alarm_id_t id, void* user_param)
 327 {
 328  alarm_entry_t* alarm;
 329 alarm = alarmmgr_create_alarm();
 330         int* n = (int*)user_param;
 331         printf("[%d]alarm id : %d\n",*n,id);
 332         (*n)++;
 333        alarmmgr_get_info(id, alarm);   //the application use this object(alarm)
 334 }
 335 sample_get_info()
 336 {
 337         int n=1;
 338         alarmmgr_enum_alarm_ids(test_callback,(void*)&n);
 339 }
 340 @endcode
 341
 342
 343  @}
 344 **/