include/alarm.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 #ifndef ALARM_LIB_H
  27 #define ALARM_LIB_H
  28
  29 /**
  30  * @open
  31  * @addtogroup APPLICATION_FRAMEWORK
  32  * @{
  33  *
  34  * @defgroup Alarm Alarm
  35  * @version 0.4.2
  36  *
  37  *
  38  * Alarm  supports APIs that add, delete, and update an alarm.
  39  * @n An application can use alarm APIs by including @c alarm.h. The definitions
  40  * of APIs are defined as follows:
  41  *
  42  * @li @c #alarmmgr_init initialize alarm library
  43  * @li @c #alarmmgr_set_cb set the callback for an alarm event
  44  * @li @c #alarmmgr_create_alarm create an alarm entry
  45  * @li @c #alarmmgr_free_alarm free an alarm entry
  46  * @li @c #alarmmgr_set_time set a time will be expired
  47  * @li @c #alarmmgr_get_time get a time will be expired
  48  * @li @c #alarmmgr_set_repeat_mode set repeat mode
  49  * @li @c #alarmmgr_get_repeat_mode get repeat mode
  50  * @li @c #alarmmgr_set_type set type
  51  * @li @c #alarmmgr_get_type get type
  52  * @li @c #alarmmgr_add_alarm_with_localtime add an alarm with localtime
  53  * @li @c #alarmmgr_add_alarm add an alarm
  54  * @li @c #alarmmgr_remove_alarm remove an alarm from alarm server
  55  * @li @c #alarmmgr_enum_alarm_ids get the list of alarm ids
  56  * @li @c #alarmmgr_get_info get the information of an alarm
  57  *
  58  *
  59  * The following code shows how to initialize alarm library, how to register the alarm handler, and how to add an alarm. It first calls alarm_init to initialize the alarm library and sets the callback to handle an alarm event it received. In create_test fucnction, the application add an alarm which will be expired in one minute from it execute and will expire everyday at same time.
  60  *
  61  *
  62  * @code
  63 #include<stdio.h>
  64 #include<stdlib.h>
  65 #include<glib.h>
  66
  67 #include "alarm.h"
  68
  69 int callback(alarm_id_t alarm_id, void *user_param)
  70 {
  71         int error;
  72         time_t current_time;
  73         time(&current_time);
  74
  75         printf("Alarm[%d] has expired at %s\n", alarm_id, ctime(&current_time));
  76         return 0;
  77 }
  78
  79 void create_test()
  80 {
  81         time_t current_time;
  82         struct tm current_tm;
  83         alarm_entry_t* alarm_info;
  84         alarm_id_t alarm_id;
  85         int result;
  86         alarm_date_t test_time;
  87
  88         time(&current_time);
  89
  90         printf("current time: %s\n", ctime(&current_time));
  91         localtime_r(&current_time, &current_tm);
  92
  93         alarm_info = alarmmgr_create_alarm();
  94
  95         test_time.year = current_tm.tm_year+1900;
  96         test_time.month = current_tm.tm_mon+1;
  97         test_time.day = current_tm.tm_mday;
  98         test_time.hour = current_tm.tm_hour;
  99         test_time.min = current_tm.tm_min+1;
 100         test_time.sec = 0;
 101
 102         alarmmgr_set_time(alarm_info,test_time);
 103         alarmmgr_set_repeat_mode(alarm_info,ALARM_REPEAT_MODE_WEEKLY,
 104         ALARM_WDAY_MONDAY| \
 105         ALARM_WDAY_TUESDAY|ALARM_WDAY_WEDNESDAY| \
 106         ALARM_WDAY_THURSDAY|ALARM_WDAY_FRIDAY );
 107
 108         alarmmgr_set_type(alarm_info,ALARM_TYPE_VOLATILE);
 109         alarmmgr_add_alarm_with_localtime(alarm_info,NULL,&alarm_id);
 110
 111         if(result != ALARMMGR_RESULT_SUCCESS)
 112                 printf("fail to alarmmgr_create : error_code : %d\n",result);
 113
 114 }
 115
 116 int main(int argc, char** argv)
 117 {
 118         int error_code;
 119         GMainLoop *mainloop;
 120         int result;
 121         g_type_init();
 122
 123         mainloop = g_main_loop_new(NULL, FALSE);
 124         result = alarmmgr_init("org.tizen.test");
 125
 126         if(result != ALARMMGR_RESULT_SUCCESS) {
 127                 printf("fail to alarmmgr_init : error_code : %d\n",result);
 128         }
 129         else {
 130                 result = alarmmgr_set_cb(callback,NULL);
 131                 if(result != ALARMMGR_RESULT_SUCCESS) {
 132                         printf("fail to alarmmgr_set_cb : error_code :
 133                                                         %d\n",result);
 134                 }
 135                 else {
 136                         create_test();
 137                 }
 138         }
 139         g_main_loop_run(mainloop);
 140 }
 141
 142 * @endcode
 143 *
 144 */
 145
 146 /**
 147  * @addtogroup Alarm
 148  * @{
 149  */
 150
 151 #include<sys/types.h>
 152 #include<stdbool.h>
 153
 154 #ifdef __cplusplus
 155 extern "C" {
 156 #endif
 157
 158 /**
 159 * Type of an alarm id
 160 */
 161 typedef int alarm_id_t;
 162 /**
 163 * The prototype of alarm handler.
 164 * param [in]    alarm_id the id of expired alarm
 165 */
 166 typedef int (*alarm_cb_t) (alarm_id_t alarm_id, void *user_param);
 167
 168 typedef int (*alarm_enum_fn_t) (alarm_id_t alarm_id, void *user_param);
 169
 170 /**
 171 * This enumeration has day of a week of alarm
 172 */
 173 typedef enum {
 174         ALARM_WDAY_SUNDAY = 0x01, /**< enalbe alarm on Sunday*/
 175         ALARM_WDAY_MONDAY = 0x02, /**< enalbe alarm on Monday*/
 176         ALARM_WDAY_TUESDAY = 0x04, /**< enable alarm on Tuesday*/
 177         ALARM_WDAY_WEDNESDAY = 0x08, /**< enalbe alarm on Wednesday*/
 178         ALARM_WDAY_THURSDAY = 0x10, /**< enable alarm on Thursday*/
 179         ALARM_WDAY_FRIDAY = 0x20,  /**< enable alarm on Friday*/
 180         ALARM_WDAY_SATURDAY = 0x40,/**< enable alarm on Saturday*/
 181 } alarm_day_of_week_t;
 182
 183 /**
 184 * This enumeration has error codes of alarm
 185 */
 186         typedef enum {
 187                 ERR_ALARM_INVALID_PARAM = -10,
 188                                      /**<Invalid parameter*/
 189                 ERR_ALARM_INVALID_ID,   /**<Invalid id*/
 190                 ERR_ALARM_INVALID_REPEAT,
 191                                         /**<Invalid repeat mode*/
 192                 ERR_ALARM_INVALID_TIME, /**<Invalid time. */
 193                 ERR_ALARM_INVALID_DATE, /**<Invalid date. */
 194                 ERR_ALARM_NO_SERVICE_NAME,
 195                                     /**<there is no alarm service
 196                                         for this applicaation. */
 197                 ERR_ALARM_INVALID_TYPE,  /*Invalid type*/
 198                 ERR_ALARM_NO_PERMISSION, /*No permission*/
 199                 ERR_ALARM_SYSTEM_FAIL = -1,
 200                 ALARMMGR_RESULT_SUCCESS = 0,
 201         } alarm_error_t;
 202
 203 /**
 204 *  This enumeration has repeat mode of alarm
 205 */
 206 typedef enum {
 207         ALARM_REPEAT_MODE_ONCE = 0,     /**<once : the alarm will be expired
 208                                         only one time. */
 209         ALARM_REPEAT_MODE_REPEAT,       /**<repeat : the alarm will be expired
 210                                         repeatly*/
 211         ALARM_REPEAT_MODE_WEEKLY,       /**<weekly*/
 212         ALARM_REPEAT_MODE_MONTHLY,      /**< monthly*/
 213         ALARM_REPEAT_MODE_ANNUALLY,     /**< annually*/
 214         ALARM_REPEAT_MODE_MAX,
 215 } alarm_repeat_mode_t;
 216
 217
 218 #define ALARM_TYPE_DEFAULT      0x0     /*< non volatile */
 219 #define ALARM_TYPE_VOLATILE     0x02    /*< volatile */
 220
 221
 222 /**
 223 * This struct has date information
 224 */
 225 typedef struct {
 226         int year;               /**< specifies the year */
 227         int month;              /**< specifies the month */
 228         int day;                /**< specifies the day */
 229         int hour;               /**< specifies the hour */
 230         int min;                /**< specifies the minute*/
 231         int sec;                /**< specifies the second*/
 232 } alarm_date_t;
 233
 234
 235 typedef struct alarm_info_t alarm_entry_t;
 236
 237
 238 /**
 239  *
 240  * This function initializes alarm library. It connects to system bus and registers the application's service name.
 241  *
 242  * @param       [in]    pkg_name        a package of application
 243  *
 244  * @return On success, ALARMMGR_RESULT_SUCCESS is returned. On error, a negative number is returned
 245  *
 246  * @pre None.
 247  * @post None.
 248  * @see None.
 249  * @remark An application must call this function before using other alarm APIs.
 250  * @par Sample code:
 251  * @code
 252 #include <alarm.h>
 253
 254 ...
 255 {
 256         int ret_val = ALARMMGR_RESULT_SUCCESS;
 257         const char* pkg_name = "org.tizen.test";
 258
 259         g_type_init();
 260
 261         ret_val =alarmmgr_init(pkg_name) ;
 262         if(ret_val == ALARMMGR_RESULT_SUCCESS)
 263         {
 264                  //alarmmgr_init() is successful
 265         }
 266         else
 267         {
 268                  //alarmmgr_init () failed
 269         }
 270 }
 271  * @endcode
 272  * @limo
 273  */
 274 int alarmmgr_init(const char *pkg_name);
 275
 276 void alarmmgr_fini();
 277
 278
 279 /**
 280  * This function registers handler which handles an alarm event. An application should register the alarm handler
 281  * before it enters mainloop.
 282  *
 283  * @param       [in]    handler Callback function
 284  * @param       [in]    user_param      User Parameter
 285  *
 286  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 287  *
 288  * @pre alarmmgr_init().
 289  * @post None.
 290  * @see None.
 291  * @remark      An application can have only one alarm handler. If an application
 292  *          calls this function more than one times, the handler regitered during  the
 293  *          last call of this funiction will be called when an alarm event has occured.
 294  * @par Sample code:
 295  * @code
 296 #include <alarm.h>
 297 ...
 298
 299 // Call back function
 300 int callback(alarm_id_t alarm_id,void* user_param)
 301 {
 302         time_t current_time;
 303         time(&current_time);
 304
 305         printf("Alarm[%d] has expired at %s\n", alarm_id, ctime(&current_time));
 306
 307         return 0;
 308
 309 }
 310
 311 ...
 312 {
 313         int ret_val = ALARMMGR_RESULT_SUCCESS;
 314         void *user_param = NULL;
 315
 316         ret_val = alarmmgr_set_cb( callback, user_param);
 317         if(ret_val == ALARMMGR_RESULT_SUCCESS)
 318         {
 319                 //alarmmgr_set_cb() is successful
 320         }
 321         else
 322         {
 323                  //alarmmgr_set_cb () failed
 324         }
 325 }
 326
 327  * @endcode
 328  * @limo
 329  */
 330 int alarmmgr_set_cb(alarm_cb_t handler, void *user_param);
 331
 332
 333 /**
 334  * This function creates a new alarm entry, will not be known to the server until alarmmgr_add_alarm is called.
 335  *
 336  * @return      This function returns the pointer of alarm_entry_t
 337  *
 338  * @pre None.
 339  * @post None.
 340  * @see None.
 341  * @remark      After an application use this object, an application free this pointer through alarmmgr_free_alarm
 342  *
 343  * @par Sample code:
 344  * @code
 345 #include <alarm.h>
 346
 347 ...
 348 {
 349         alarm_entry_t* alarm;
 350
 351         alarm = alarmmgr_create_alarm() ;
 352         if(alarm != NULL)
 353         {
 354                  //alarmmgr_create_alarm() is successful
 355         }
 356         else
 357         {
 358                  //alarmmgr_create_alarm () failed
 359         }
 360 }
 361
 362
 363  * @endcode
 364  * @limo
 365  */
 366 alarm_entry_t *alarmmgr_create_alarm(void);
 367
 368
 369 /**
 370  * This function frees an alarm entry.
 371  *
 372  * @param       [in]    alarm   alarm entry
 373  *
 374  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 375  *
 376  * @pre None.
 377  * @post None.
 378  * @see None.
 379  * @remark      None.
 380  *
 381  * @par Sample code:
 382  * @code
 383 #include <alarm.h>
 384
 385 ...
 386  {
 387          int ret_val = ALARMMGR_RESULT_SUCCESS;
 388          alarm_entry_t* alarm;
 389
 390          alarm = alarmmgr_create_alarm() ;
 391          if(alarm == NULL)
 392          {
 393                   //alarmmgr_create_alarm () failed
 394          }
 395          else
 396                  {
 397
 398                          ret_val = alarmmgr_free_alarm( alarm) ;
 399                          if(ret_val == ALARMMGR_RESULT_SUCCESS)
 400                          {
 401                                   //alarmmgr_free_alarm() is successful
 402                          }
 403                          else
 404                          {
 405                                  //alarmmgr_free_alarm() failed
 406                          }
 407                  }
 408  }
 409
 410  * @endcode
 411  * @limo
 412  */
 413 int alarmmgr_free_alarm(alarm_entry_t *alarm);
 414
 415
 416 /**
 417  * This function sets time that alarm should be expried.
 418  *
 419  * @param       [in]    alarm   alarm entry
 420  * @param       [in]    time            time the alarm should first go off
 421  *
 422  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 423  *
 424  * @pre None.
 425  * @post None.
 426  * @see None.
 427  * @remark  None.
 428  *
 429  * @par Sample code:
 430  * @code
 431 #include <alarm.h>
 432
 433  ...
 434   {
 435           int ret_val = ALARMMGR_RESULT_SUCCESS;
 436           alarm_entry_t* alarm;
 437           time_t current_time;
 438           struct tm current_tm;
 439           alarm_date_t test_time;
 440
 441
 442          time(&current_time);
 443          localtime_r(&current_time, &current_tm);
 444
 445          alarm = alarmmgr_create_alarm();
 446           if(alarm == NULL)
 447           {
 448                    //alarmmgr_create_alarm () failed
 449           }
 450           else {
 451                 test_time.year = current_tm.tm_year;
 452                 test_time.month = current_tm.tm_mon;
 453                 test_time.day = current_tm.tm_mday;
 454
 455                 test_time.hour = current_tm.tm_hour;
 456                 test_time.min = current_tm.tm_min+1;
 457                 test_time.sec = 0;
 458
 459                 ret_val=alarmmgr_set_time(alarm,test_time);
 460                 if(ret_val == ALARMMGR_RESULT_SUCCESS)
 461                 {
 462                         //alarmmgr_set_time() is successful
 463                 }
 464                 else
 465                 {
 466                         //alarmmgr_set_time() failed
 467                 }
 468                           alarmmgr_free_alarm( alarm) ;
 469           }
 470  }
 471
 472  * @endcode
 473  * @limo
 474  */
 475 int alarmmgr_set_time(alarm_entry_t *alarm, alarm_date_t time);
 476
 477 /**
 478  * This function gives an application time that alarm should be expried.
 479  *
 480  * @param       [in]            alarm   alarm entry
 481  * @param       [out]   time            time the alarm should first go off
 482  *
 483  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 484  *
 485  * @pre None.
 486  * @post None.
 487  * @see None.
 488  * @remark      But an application does not need to specify year, month, and day field of alarm_info. If an application sets
 489  *                      those fields with zero, the function sets them with proper values.
 490  *
 491  * @par Sample code:
 492  * @code
 493 #include <alarm.h>
 494
 495  ...
 496  {
 497          int ret_val = ALARMMGR_RESULT_SUCCESS;
 498          alarm_entry_t* alarm;
 499
 500          time_t current_time;
 501                 struct tm current_tm;
 502          alarm_date_t test_time;
 503          alarm_date_t new_time;
 504
 505
 506                 time(&current_time);
 507                 localtime_r(&current_time, &current_tm);
 508
 509                 alarm = alarmmgr_create_alarm();
 510          if(alarm == NULL) {
 511                   //alarmmgr_create_alarm () failed
 512          }
 513          else {
 514                 test_time.year = current_tm.tm_year;
 515                 test_time.month = current_tm.tm_mon;
 516                 test_time.day = current_tm.tm_mday;
 517
 518                 test_time.hour = current_tm.tm_hour;
 519                 test_time.min = current_tm.tm_min+1;
 520                 test_time.sec = 0;
 521
 522                 ret_val = alarmmgr_set_time(alarm,test_time);
 523                 if(ret_val == ALARMMGR_RESULT_SUCCESS) {
 524                         //alarmmgr_set_time() is successful
 525                 }
 526                 else {
 527                         //alarmmgr_set_time() failed
 528                 }
 529
 530                 ret_val = alarmmgr_get_time(alarm, &new_time);
 531                 if(ret_val == ALARMMGR_RESULT_SUCCESS) {
 532                         //alarmmgr_get_time() is successful
 533                 }
 534                 else {
 535                         //alarmmgr_get_time() failed
 536                 }
 537                 alarmmgr_free_alarm( alarm) ;
 538         }
 539  }
 540
 541  * @endcode
 542  * @limo
 543  */
 544 int alarmmgr_get_time(const alarm_entry_t *alarm, alarm_date_t *time);
 545
 546 /**
 547  * This function sets an alarm repeat mode
 548  *
 549  * @param       [in]    alarm   alarm entry
 550  * @param       [in]    repeat_mode     one of ALARM_REPEAT_MODE_ONCE, ALARM_REPEAT_MODE_REPEAT,
 551  *                                                              ALARM_REPEAT_MODE_WEEKLY, ALARM_REPEAT_MODE_MONTHLY or ALARM_REPEAT_MODE_ANNUALLY.
 552  * @param       [in]    repeat_value    the ALARM_REPEAT_MODE_REPEAT mode : interval between subsequent repeats of the alarm.
 553  *                                                              the ALARM_REPEAT_MODE_WEEKLY mode : days of a week
 554  *                                                              (ALARM_WDAY_SUNDAY, ALARM_WDAY_MONDAY, ALARM_WDAY_TUESDAY,      ALARM_WDAY_WEDNESDAY,
 555  *                                                              ALARM_WDAY_THURSDAY,    ALARM_WDAY_FRIDAY, ALARM_WDAY_SATURDAY)
 556  *                                                              the others : this parameter is ignored.
 557  *
 558  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 559  *
 560  * @pre None.
 561  * @post None.
 562  * @see None.
 563  * @remark  None.
 564  *
 565  * @par Sample code:
 566  * @code
 567 #include <alarm.h>
 568
 569   ...
 570  {
 571          int ret_val = ALARMMGR_RESULT_SUCCESS;
 572          alarm_entry_t* alarm;
 573          alarm_repeat_mode_t repeat_mode =ALARM_REPEAT_MODE_WEEKLY;
 574          int interval = ALARM_WDAY_MONDAY; //| ALARM_WDAY_TUESDAY|
 575                 ALARM_WDAY_WEDNESDAY| ALARM_WDAY_THURSDAY|ALARM_WDAY_FRIDAY ;
 576
 577
 578          alarm = alarmmgr_create_alarm();
 579          if(alarm == NULL)
 580          {
 581                   //alarmmgr_create_alarm () failed
 582          }
 583          else
 584                  {
 585                            ret_val = alarmmgr_set_repeat_mode
 586                                         (alarm, repeat_mode,interval);
 587
 588                          if(ret_val == ALARMMGR_RESULT_SUCCESS)
 589                          {
 590                                   //alarmmgr_set_repeat_mode() is successful
 591                          }
 592                          else
 593                          {
 594                                  //alarmmgr_set_repeat_mode() failed
 595                          }
 596                          alarmmgr_free_alarm( alarm) ;
 597                  }
 598  }
 599
 600  * @endcode
 601  * @limo
 602  */
 603 int alarmmgr_set_repeat_mode(alarm_entry_t *alarm,
 604                                      alarm_repeat_mode_t repeat_mode,
 605                                      int repeat_value);
 606
 607 /**
 608  * This function gives an application an alarm mode
 609  *
 610  * @param       [in]            alarm   alarm entry
 611  * @param       [out]   repeat_mode     one of ALARM_REPEAT_MODE_ONCE, ALARM_REPEAT_MODE_REPEAT,
 612  *                                                                      ALARM_REPEAT_MODE_WEEKLY, ALARM_REPEAT_MODE_MONTHLY or ALARM_REPEAT_MODE_ANNUALLY.
 613  * @param       [out]   repeat_value    the ALARM_REPEAT_MODE_REPEAT mode : interval between subsequent repeats of the alarm.
 614  *                                                                      the ALARM_REPEAT_MODE_WEEKLY mode : days of a week
 615  *                                                                      (ALARM_WDAY_SUNDAY, ALARM_WDAY_MONDAY, ALARM_WDAY_TUESDAY,      ALARM_WDAY_WEDNESDAY,
 616  *                                                                      ALARM_WDAY_THURSDAY,    ALARM_WDAY_FRIDAY, ALARM_WDAY_SATURDAY)
 617  *                                                                      the others : this parameter is ignored.
 618  *
 619  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 620  *
 621  * @pre None.
 622  * @post None.
 623  * @see None.
 624  * @remark  None.
 625  *
 626  * @par Sample code:
 627  * @code
 628 #include <alarm.h>
 629
 630    ...
 631  {
 632          int ret_val = ALARMMGR_RESULT_SUCCESS;
 633          alarm_entry_t* alarm;
 634          alarm_repeat_mode_t repeat;
 635          int interval;
 636
 637          alarm = alarmmgr_create_alarm();
 638          if(alarm == NULL)
 639          {
 640                  //alarmmgr_create_alarm () failed
 641          }
 642          else {
 643                 ret_val =alarmmgr_get_repeat_mode
 644                                         (alarm, &repeat, &interval) ;
 645                          if(ret_val == ALARMMGR_RESULT_SUCCESS
 646                         && repeat == ALARM_REPEAT_MODE_ONCE) {
 647                                 //alarmmgr_get_repeat_mode() is successful
 648                         }
 649                         else {
 650                                 //alarmmgr_get_repeat_mode() failed
 651                         }
 652                         alarmmgr_free_alarm(alarm) ;
 653         }
 654  }
 655
 656  * @endcode
 657  * @limo
 658  */
 659 int alarmmgr_get_repeat_mode(const alarm_entry_t *alarm,
 660                                      alarm_repeat_mode_t *repeat_mode,
 661                                      int *repeat_value);
 662
 663 /**
 664  * This function sets an alarm mode
 665  *
 666  * @param       [in]    alarm   alarm entry
 667  * @param       [in]    alarm_type      one of ALARM_TYPE_DEFAULT : After the device reboot, the alarm still works.
 668  *                                                      ALARM_TYPE_VOLATILE : After the device reboot, the alarm does not work.
 669  *
 670  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 671  *
 672  * @pre None.
 673  * @post None.
 674  * @see None.
 675  * @remark  None.
 676  *
 677  * @par Sample code:
 678  * @code
 679 #include <alarm.h>
 680
 681    ...
 682  {
 683          int ret_val = ALARMMGR_RESULT_SUCCESS;
 684          alarm_entry_t* alarm;
 685          int alarm_type = ALARM_TYPE_VOLATILE;
 686
 687          alarm = alarmmgr_create_alarm();
 688          if(alarm == NULL)
 689          {
 690                   //alarmmgr_create_alarm () failed
 691          }
 692          else
 693                  {
 694                          ret_val = alarmmgr_set_type(alarm,  alarm_type);
 695                          if(ret_val == ALARMMGR_RESULT_SUCCESS)
 696                          {
 697                                   //alarmmgr_set_type() is successful
 698                          }
 699                          else
 700                          {
 701                                   //alarmmgr_set_type() failed
 702                          }
 703                          alarmmgr_free_alarm( alarm) ;
 704                  }
 705  }
 706
 707  * @endcode
 708  * @limo
 709  */
 710 int alarmmgr_set_type(alarm_entry_t *alarm, int alarm_type);
 711
 712 /**
 713  * This function gives an application an alarm mode
 714  *
 715  * @param       [in]            alarm   alarm entry
 716  * @param       [out]   alarm_type      one of ALARM_TYPE_DEFAULT, ALARM_TYPE_VOLATILE
 717  *
 718  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 719  *
 720  * @pre None.
 721  * @post None.
 722  * @see None.
 723  * @remark  None.
 724  *
 725  * @par Sample code:
 726  * @code
 727 #include <alarm.h>
 728
 729    ...
 730  {
 731         int ret_val = ALARMMGR_RESULT_SUCCESS;
 732         alarm_entry_t* alarm;
 733         int alarm_type;
 734
 735         alarm = alarmmgr_create_alarm();
 736         if(alarm == NULL) {
 737                 //alarmmgr_create_alarm () failed
 738         }
 739         else {
 740                 ret_val = alarmmgr_get_type(  alarm, &alarm_type);
 741                 if(ret_val == ALARMMGR_RESULT_SUCCESS && alarm_type
 742                                                 == ALARM_TYPE_DEFAULT ) {
 743                         //alarmmgr_get_type() is successful
 744                 }
 745                 else {
 746                         //alarmmgr_get_type() failed
 747                 }
 748                 alarmmgr_free_alarm( alarm) ;
 749         }
 750  }
 751
 752  * @endcode
 753  * @limo
 754  */
 755 int alarmmgr_get_type(const alarm_entry_t *alarm, int *alarm_type);
 756
 757 /**
 758  * This function adds an alarm entry to the server.
 759  * Server will remember this entry, and generate alarm events for it when necessary.
 760  * Server will call app-svc interface to sent notification to destination application. Destination information
 761  * should be available in the input bundle.
 762  * Alarm entries registered with the server cannot be changed.
 763  * Remove from server before changing.
 764  * Before the application calls alarmmgr_add_alarm_appsvc_with_localtime(), the application have to call alarmmgr_set_time().
 765  * The time set is localtime.
 766  * If the application does not call alarmmgr_set_repeat_mode, the default repeat_mode is ALARM_REPEAT_MODE_ONCE.
 767  * If the application does not call alarmmgr_set_type, the default alarm_type is ALARM_TYPE_DEFAULT.
 768  * The id of the new alarm will be copied to  alarm_id if the fuction successes to create an alarm.
 769  *
 770  * @param       [in]            alarm           the entry of an alarm to be created.
 771  * @param       [in]            bundle_data     bundle which contains information about the destination.
 772  * @param       [out]           alarm_id        the id of the alarm added.
 773  *
 774  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 775  *
 776  * @pre None.
 777  * @post None.
 778  * @see alarmmgr_add_alarm
 779  * @remark  None.
 780  *
 781  * @par Sample code:
 782  * @code
 783 #include <alarm.h>
 784
 785    ...
 786 {
 787     time_t current_time;
 788     struct tm current_tm;
 789     alarm_entry_t* alarm_info;
 790     alarm_id_t alarm_id;
 791     int result;
 792     alarm_date_t test_time;
 793
 794
 795         bundle *b=NULL;
 796
 797         b=bundle_create();
 798
 799         if (NULL == b)
 800         {
 801                 printf("Unable to create bundle!!!\n");
 802                 return;
 803         }
 804
 805         appsvc_set_operation(b,APPSVC_OPERATION_DEFAULT);
 806         appsvc_set_pkgname(b,"org.tizen.alarm-test");
 807
 808     time(&current_time);
 809
 810     printf("current time: %s\n", ctime(&current_time));
 811     localtime_r(&current_time, &current_tm);
 812
 813     alarm_info = alarmmgr_create_alarm();
 814
 815     test_time.year = current_tm.tm_year;
 816                         test_time.month = current_tm.tm_mon;
 817                         test_time.day = current_tm.tm_mday;
 818
 819                         test_time.hour = current_tm.tm_hour;
 820                         test_time.min = current_tm.tm_min+1;
 821                         test_time.sec = 5;
 822
 823
 824     alarmmgr_set_time(alarm_info,test_time);
 825     alarmmgr_set_repeat_mode(alarm_info,ALARM_REPEAT_MODE_WEEKLY,ALARM_WDAY_MONDAY| \
 826                 ALARM_WDAY_TUESDAY|ALARM_WDAY_WEDNESDAY| \
 827                 ALARM_WDAY_THURSDAY|ALARM_WDAY_FRIDAY );
 828
 829     alarmmgr_set_type(alarm_info, ALARM_TYPE_DEFAULT);
 830     //alarmmgr_set_type(alarm_info,ALARM_TYPE_VOLATILE);
 831     if ((result = alarmmgr_add_alarm_appsvc_with_localtime(alarm_info,(void *)b,&alarm_id)) < 0)
 832         {
 833                 printf("Alarm creation failed!!! Alrmgr error code is %d\n",result);
 834         }
 835         else
 836         {
 837                 printf("Alarm created succesfully with alarm id %d\n",alarm_id);
 838         }
 839
 840 }
 841  * @endcode
 842  * @limo
 843  */
 844 int alarmmgr_add_alarm_appsvc_with_localtime(alarm_entry_t *alarm,void *bundle_data, alarm_id_t *alarm_id);
 845
 846 /**
 847  * This function adds an alarm entry to the server.
 848  * Server will remember this entry, and generate alarm events for it when necessary.
 849  * Alarm entries registered with the server cannot be changed.
 850  * Remove from server before changing.
 851  * Before the application calls alarmmgr_add_alarm_with_localtime(), the application have to call alarmmgr_set_time().
 852  * The time set is localtime.
 853  * If the application does not call alarmmgr_set_repeat_mode, the default repeat_mode is ALARM_REPEAT_MODE_ONCE.
 854  * If the application does not call alarmmgr_set_type, the default alarm_type is ALARM_TYPE_DEFAULT.
 855  * The id of the new alarm will be copied to  alarm_id if the fuction successes to create an alarm.
 856  *
 857  * @param       [in]            alarm           the entry of an alarm to be created.
 858  * @param       [in]            destination     the packname of application that the alarm will be expired.
 859  * @param       [out]   alarm_id                the id of the alarm added.
 860  *
 861  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 862  *
 863  * @pre None.
 864  * @post None.
 865  * @see alarmmgr_add_alarm
 866  * @remark  None.
 867  *
 868  * @par Sample code:
 869  * @code
 870 #include <alarm.h>
 871
 872    ...
 873 {
 874         int ret_val = ALARMMGR_RESULT_SUCCESS;
 875         alarm_entry_t* alarm;
 876         const char* destination = NULL;
 877         alarm_id_t alarm_id;
 878
 879         time_t current_time;
 880         struct tm current_tm;
 881         alarm_date_t test_time;
 882
 883         const char* pkg_name = "org.tizen.test";
 884
 885         g_type_init();
 886
 887         ret_val =alarmmgr_init(pkg_name) ;
 888         if(ret_val != ALARMMGR_RESULT_SUCCESS) {
 889                 //alarmmgr_init () failed
 890                 return;
 891         }
 892
 893         time(&current_time);
 894
 895         printf("current time: %s\n", ctime(&current_time));
 896         localtime_r(&current_time, &current_tm);
 897
 898         alarm = alarmmgr_create_alarm();
 899
 900         test_time.year = 0;
 901         test_time.month = 0;test_time.day = 0;
 902
 903         test_time.hour = current_tm.tm_hour;
 904         test_time.min = current_tm.tm_min+1;
 905         test_time.sec = 0;
 906
 907
 908          alarmmgr_set_time(alarm,test_time);
 909          alarmmgr_set_repeat_mode(alarm,ALARM_REPEAT_MODE_WEEKLY, \
 910                                         ALARM_WDAY_MONDAY);
 911          alarmmgr_set_type(alarm,ALARM_TYPE_VOLATILE);
 912
 913
 914         ret_val=alarmmgr_add_alarm_with_localtime(alarm,destination,&alarm_id);
 915
 916          if(ret_val == ALARMMGR_RESULT_SUCCESS)
 917          {
 918                   //alarmmgr_add_alarm_with_localtime() is successful
 919          }
 920          else
 921          {
 922                   //alarmmgr_add_alarm_with_localtime() failed
 923          }
 924          alarmmgr_free_alarm( alarm) ;
 925  }
 926  * @endcode
 927  * @limo
 928  */
 929 int alarmmgr_add_alarm_with_localtime(alarm_entry_t *alarm,
 930                                               const char *destination,
 931                                               alarm_id_t *alarm_id);
 932
 933
 934 /**
 935  * This function adds an alarm entry to the server.
 936  * Server will remember this entry, and generate alarm events for it when necessary.
 937  * Server will call app-svc interface to sent notification to destination application. Destination information
 938  * should be available in the input bundle.
 939  * Alarm entries registered with the server cannot be changed.
 940  * Remove from server before changing.
 941  * After the trigger_at_time seconds from now, the alarm will be expired.
 942  * If the interval is zero, the repeat_mode is ALARM_REPEAT_MODE_ONCE.
 943  * If the interval is >0, the repeat_mode is ALARM_REPEAT_MODE_REPEAT.
 944  * The id of the new alarm will be copied to  alarm_id if the fuction successes to create an alarm.
 945  *
 946  * @param       [in]            alarm_type              one of ALARM_TYPE_DEFAULT, ALARM_TYPE_VOLATILE
 947  * @param       [in]            trigger_at_time time interval to be triggered from now(sec). an alarm also will be expired at triggering time.
 948  * @param       [in]            interval                Interval between subsequent repeats of the alarm
 949  * @param       [in]            bundle_data             bundle which contains information about the destination.
 950  * @param       [out]   alarm_id                        the id of the alarm added.
 951  *
 952  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
 953  *
 954  * @pre None.
 955  * @post None.
 956  * @see alarmmgr_add_alarm_with_localtime alarmmgr_remove_alarm
 957  * @remark  None.
 958  *
 959  * @par Sample code:
 960  * @code
 961 #include <alarm.h>
 962
 963  ...
 964  {
 965                 int result;
 966                 alarm_id_t alarm_id;
 967
 968                 bundle *b=NULL;
 969
 970                 b=bundle_create();
 971
 972                 if (NULL == b)
 973                 {
 974                         printf("Unable to create bundle!!!\n");
 975                         return;
 976                 }
 977
 978                 appsvc_set_pkgname(b,"org.tizen.alarm-test");
 979                 //appsvc_set_operation(b,APPSVC_OPERATION_SEND_TEXT);
 980                 appsvc_set_operation(b,APPSVC_OPERATION_DEFAULT);
 981
 982                 if ((result = alarmmgr_add_alarm_appsvc(ALARM_TYPE_DEFAULT, 10, 0, (void *)b ,&alarm_id)))
 983                         printf("Unable to add alarm. Alarmmgr alarm no is %d\n", result);
 984                 else
 985                         printf("Alarm added successfully. Alarm Id is %d\n", alarm_id);
 986                 return;
 987
 988  }
 989
 990  * @endcode
 991  * @limo
 992  */
 993 int alarmmgr_add_alarm_appsvc(int alarm_type, time_t trigger_at_time,
 994                                time_t interval, void *bundle_data,
 995                                alarm_id_t *alarm_id);
 996
 997
 998 /**
 999  * This function adds an alarm entry to the server.
1000  * Server will remember this entry, and generate alarm events for it when necessary.
1001  * Alarm entries registered with the server cannot be changed.
1002  * Remove from server before changing.
1003  * After the trigger_at_time seconds from now, the alarm will be expired.
1004  * If the interval is zero, the repeat_mode is ALARM_REPEAT_MODE_ONCE.
1005  * If the interval is >0, the repeat_mode is ALARM_REPEAT_MODE_REPEAT.
1006  * The id of the new alarm will be copied to  alarm_id if the fuction successes to create an alarm.
1007  *
1008  * @param       [in]            alarm_type              one of ALARM_TYPE_DEFAULT, ALARM_TYPE_VOLATILE
1009  * @param       [in]            trigger_at_time time interval to be triggered from now(sec). an alarm also will be expired at triggering time.
1010  * @param       [in]            interval                        Interval between subsequent repeats of the alarm
1011  * @param       [in]            destination             the packname of application that the alarm will be expired.
1012  * @param       [out]   alarm_id                        the id of the alarm added.
1013  *
1014  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
1015  *
1016  * @pre None.
1017  * @post None.
1018  * @see alarmmgr_add_alarm_with_localtime alarmmgr_remove_alarm
1019  * @remark  None.
1020  *
1021  * @par Sample code:
1022  * @code
1023 #include <alarm.h>
1024
1025  ...
1026  {
1027          int ret_val = ALARMMGR_RESULT_SUCCESS;
1028
1029          int alarm_type = ALARM_TYPE_VOLATILE;
1030          time_t trigger_at_time = 10;
1031          time_t interval = 10;
1032          const char* destination = NULL;
1033          alarm_id_t alarm_id;
1034
1035          const char* pkg_name = "org.tizen.test";
1036
1037          g_type_init();
1038
1039          ret_val =alarmmgr_init(pkg_name) ;
1040          if(ret_val != ALARMMGR_RESULT_SUCCESS)
1041          {
1042                   //alarmmgr_init () failed
1043                   return;
1044          }
1045
1046          ret_val = alarmmgr_add_alarm( alarm_type, trigger_at_time, interval,
1047                                         destination, &alarm_id);
1048          if(ret_val == ALARMMGR_RESULT_SUCCESS)
1049          {
1050                   //alarmmgr_add_alarm() is successful
1051          }
1052          else
1053          {
1054                    //alarmmgr_add_alarm() failed
1055          }
1056          alarmmgr_remove_alarm( alarm_id) ;
1057  }
1058
1059  * @endcode
1060  * @limo
1061  */
1062 int alarmmgr_add_alarm(int alarm_type, time_t trigger_at_time,
1063                                time_t interval, const char *destination,
1064                                alarm_id_t *alarm_id);
1065
1066 /**
1067  * This function deletes the alarm associated with the given alarm_id.
1068  *
1069  * @param       [in]    alarm_id        Specifies the ID of the alarm to be deleted.
1070  *
1071  * @return      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
1072  *
1073  * @pre None.
1074  * @post None.
1075  * @see alarmmgr_add_alarm_with_localtime alarmmgr_add_alarm
1076  * @remark  None.
1077  *
1078  * @par Sample code:
1079  * @code
1080 #include <alarm.h>
1081
1082  ...
1083  {
1084         int ret_val = ALARMMGR_RESULT_SUCCESS;
1085         int alarm_type = ALARM_TYPE_VOLATILE;
1086         time_t trigger_at_time = 10;
1087         time_t interval = 10;
1088         const char* destination = NULL;
1089         alarm_id_t alarm_id;
1090
1091         const char* pkg_name = "org.tizen.test";
1092
1093         g_type_init();
1094
1095         ret_val =alarmmgr_init(pkg_name) ;
1096         if(ret_val != ALARMMGR_RESULT_SUCCESS) {
1097                 //alarmmgr_init () failed
1098                 return;
1099         }
1100
1101         alarmmgr_add_alarm( alarm_type,  trigger_at_time, interval,
1102                                                 destination, &alarm_id);
1103
1104         ret_val =alarmmgr_remove_alarm( alarm_id) ;
1105         if(ret_val == ALARMMGR_RESULT_SUCCESS) {
1106                 /alarmmgr_remove_alarm() is successful
1107         }
1108         else {
1109                 //alarmmgr_remove_alarm() failed
1110         }
1111  }
1112
1113  * @endcode
1114  * @limo
1115  */
1116 int alarmmgr_remove_alarm(alarm_id_t alarm_id);
1117
1118 /**
1119  * This function gives a list of alarm ids that the application adds to the server.
1120  *
1121  * @param       [in]    fn                      a user callback function
1122  * @param       [in]    user_param      user parameter
1123  *
1124  * @return                      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
1125  *
1126  * @pre None.
1127  * @post None.
1128  * @see alarm_get_info
1129  * @remark  None.
1130  *
1131  * @par Sample code:
1132  * @code
1133 #include <alarm.h>
1134
1135  int callback_2(alarm_id_t id, void* user_param)
1136  {
1137          int* n = (int*)user_param;
1138          printf("[%d]alarm id : %d\n",*n,id);
1139          (*n)++;
1140          return 0;
1141  }
1142
1143 ...
1144  {
1145          int ret_val = ALARMMGR_RESULT_SUCCESS;
1146          int n = 1;
1147
1148          const char* pkg_name = "org.tizen.test";
1149
1150          g_type_init();
1151
1152          ret_val =alarmmgr_init(pkg_name) ;
1153          if(ret_val != ALARMMGR_RESULT_SUCCESS)
1154          {
1155                   //alarmmgr_init() failed
1156                   return;
1157          }
1158
1159          ret_val = alarmmgr_enum_alarm_ids( callback_2, (void*)&n) ;
1160          if(ret_val == ALARMMGR_RESULT_SUCCESS)
1161          {
1162                    //alarmmgr_enum_alarm_ids() is successful
1163          }
1164          else
1165          {
1166                  //alarmmgr_enum_alarm_ids() failed
1167          }
1168  }
1169
1170  * @endcode
1171  * @limo
1172  */
1173 int alarmmgr_enum_alarm_ids(alarm_enum_fn_t fn, void *user_param);
1174
1175
1176 /**
1177  * This function gets the information of the alarm assosiated with alarm_id to alarm_info. The application
1178  * must allocate alarm_info before calling this function.
1179  *
1180  * @param       [in]    alarm_id                the id of the alarm
1181  * @param       [out]   alarm   the buffer alarm informaiton will be copied to
1182  *
1183  * @return                      This function returns ALARMMGR_RESULT_SUCCESS on success or a negative number on failure.
1184  *
1185  * @pre None.
1186  * @post None.
1187  * @see alarmmgr_enum_alarm_ids
1188  * @remark  None.
1189  *
1190  * @par Sample code:
1191  * @code
1192 #include <alarm.h>
1193
1194 ...
1195  {
1196         int ret_val = ALARMMGR_RESULT_SUCCESS;
1197         int alarm_type = ALARM_TYPE_VOLATILE;
1198         time_t trigger_at_time = 10;
1199         time_t interval = ALARM_WDAY_SUNDAY;
1200         const char* destination = NULL;
1201         alarm_id_t alarm_id;
1202
1203         alarm_entry_t *alarm;
1204
1205         const char* pkg_name = "org.tizen.test_get_info1";
1206
1207         g_type_init();
1208
1209         ret_val =alarmmgr_init(pkg_name) ;
1210         if(ret_val != ALARMMGR_RESULT_SUCCESS) {
1211                 //alarmmgr_init() failed
1212                 return;
1213         }
1214         ret_val = alarmmgr_add_alarm( alarm_type,trigger_at_time,interval,
1215                         destination, &alarm_id);
1216
1217         if(ret_val != ALARMMGR_RESULT_SUCCESS) {
1218                 //alarmmgr_add_alarm() failed
1219                 return;
1220         }
1221         ret_val = alarmmgr_get_info(alarm_id, alarm);
1222         if(ret_val == ALARMMGR_RESULT_SUCCESS) {
1223                 //alarmmgr_get_info() is successful
1224         }
1225         else {
1226                 //alarmmgr_get_info() failed
1227         }
1228         alarmmgr_remove_alarm( alarm_id) ;
1229  }
1230  * @endcode
1231  * @limo
1232  */
1233 int alarmmgr_get_info(alarm_id_t alarm_id, alarm_entry_t *alarm);
1234
1235
1236 /**
1237  * This function retrieves bundle associated with alarm.
1238  * Server will remember this entry, and pass the bundle information upon alarm expiry.
1239  * Server will call app-svc interface to sent notification to destination application. Destination information
1240  * should be available in the input bundle.
1241  * @param       [in]            alarm_id                alarm id
1242  * @param       [out]           ALARMMGR_RESULT_SUCCESS on success or negative number on failure.
1243  *
1244  * @return      This function returns bundle on success or NULL on failure.
1245  *
1246  * @pre None.
1247  * @post None.
1248  * @see None
1249  * @remark  None.
1250  *
1251  * @par Sample code:
1252  * @code
1253 #include <alarm.h>
1254
1255  ...
1256
1257 alarm_id_t alarm_id;
1258
1259 register_alarm(){
1260         int result;
1261         bundle *b=NULL;
1262         b=bundle_create();
1263
1264         if (NULL == b)
1265         {
1266                 printf("Unable to create bundle!!!\n");
1267                 return;
1268         }
1269
1270         appsvc_set_pkgname(b,"org.tizen.alarm-test");
1271         appsvc_set_operation(b,APPSVC_OPERATION_DEFAULT);
1272
1273         if ((result = alarmmgr_add_alarm_appsvc(ALARM_TYPE_DEFAULT, 10, 0, (void *)b ,&alarm_id)))
1274                 printf("Unable to add alarm. Alarmmgr alarm no is %d\n", result);
1275         else
1276                 printf("Alarm added successfully. Alarm Id is %d\n", alarm_id);
1277 }
1278 int main(int argc,char **argv {
1279         register_alarm();
1280
1281         int return_code = 0;
1282         bundle *b = NULL;
1283         b = alarmmgr_get_alarm_appsvc_info(alarm_id, &return_code);
1284         if (b){
1285                 const char *pkgname = appsvc_get_pkgname(b);
1286                 if (pkgname){
1287                         printf("Package name is %s\n",pkgname);
1288                 }
1289         }
1290
1291         return 0;
1292
1293  }
1294  * @endcode
1295  * @limo
1296  */
1297 void *alarmmgr_get_alarm_appsvc_info(alarm_id_t alarm_id, int *return_code);
1298
1299 /**
1300  * @}
1301  */
1302
1303
1304 /**
1305  * @}
1306  */
1307
1308
1309 int alarmmgr_power_on(bool on_off);
1310
1311 #ifdef __cplusplus
1312 }
1313 #endif
1314
1315
1316 #endif/* ALARM_LIB_H*/