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