include/alarm-engine.h

   1 /*
   2   * Copyright 2012  Samsung Electronics Co., Ltd
   3   *
   4   * Licensed under the Flora License, Version 1.0 (the "License");
   5   * you may not use this file except in compliance with the License.
   6   * You may obtain a copy of the License at
   7   *
   8   *     http://www.tizenopensource.org/license
   9   *
  10   * Unless required by applicable law or agreed to in writing, software
  11   * distributed under the License is distributed on an "AS IS" BASIS,
  12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13   * See the License for the specific language governing permissions and
  14   * limitations under the License.
  15   */
  16
  17 /*!
  18  * @defgroup app_lib Application library
  19  * This is a framework for User interface
  20  */
  21
  22 /*!
  23  * @defgroup alarm_engine_group Alarm DB Library
  24  * @ingroup app_lib
  25  * Functions to APIs to access alarm DB.
  26  */
  27
  28 /**
  29  * @file                alarm-engine.h
  30  * @ingroup             alarm_engine_group
  31  * @brief               This library provides APIs to access alarm DB.
  32  * @author              Jiwon Lee <jiwon11.lee@samsung.com>, Jae-yong Lee <jaeyong911.lee@samsung.com>
  33  * @date                2010-01-07
  34  * @version             0.0.1
  35  */
  36
  37 #ifndef __ALARM_ENGINE_H__
  38 #define __ALARM_ENGINE_H__
  39
  40 #include <stdbool.h>
  41 #include <time.h>
  42
  43 //#include "sglib.h"
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 /**
  50  * @def A_DBAPI
  51  * prefix
  52  */
  53 #ifndef A_DBAPI
  54 #define A_DBAPI __attribute__ ((visibility("default")))
  55 #endif
  56 /**
  57  * @def ALARM_BUF_LEN
  58  * Maxium length of Buffer
  59  */
  60 #define ALARM_BUF_LEN                   (128)
  61 /**
  62  * @def DEFAULT_ALARM_DB_REPEAT
  63  * default value about repeat
  64  */
  65 #define DEFAULT_ALARM_DB_REPEAT ALARM_DB_REPEAT_NEVER
  66 /**
  67  * @def DEFAULT_ALARM_DB_TYPE
  68  * default value about type
  69  */
  70 #define DEFAULT_ALARM_DB_TYPE ALARM_DB_TYPE_MELODY
  71 /**
  72  * @def DEFAULT_ALARM_DB_SNOOZE_DURATION
  73  * default value about snooze duration
  74  */
  75 #define DEFAULT_ALARM_DB_SNOOZE_DURATION ALARM_DB_SNOOZE_MIN_5
  76 /**
  77  * @def DEFAULT_ALARM_DB_SNOOZE_REPEAT
  78  * default value about snooze repeat
  79  */
  80 #define DEFAULT_ALARM_DB_SNOOZE_REPEAT ALARM_DB_SNOOZE_TIMES_3
  81 /**
  82  * @def DEFAULT_ALARM_DB_VOLUME
  83  * default value about volume
  84  */
  85 #define DEFAULT_ALARM_DB_VOLUME (4)
  86 /**
  87  * return value
  88  */
  89 #define    ALARM_DB_RESULT_SUCCESS  0
  90 #define    ALARM_DB_RESULT_FAILED  -1
  91 /**
  92  * @def ALARM_DB_MAGIC_VALUE
  93  * magic value for judge struct type
  94  */
  95 #define ALARM_DB_MAGIC_VALUE (0x6E)
  96 #define MAGIC_VALUE_SET(p) (p) = ALARM_DB_MAGIC_VALUE;
  97 #define MAGIC_VALUE_CHECK(p) IS_EQUAL(p, ALARM_DB_MAGIC_VALUE)
  98
  99         typedef enum _alarm_db_author_t alarm_db_author_t;
 100         typedef enum _alarm_db_repeat_t alarm_db_repeat_t;
 101         typedef enum _alarm_db_type_t alarm_db_type_t;
 102         typedef enum _alarm_db_snooze_duration_t alarm_db_snooze_duration_t;
 103         typedef enum _alarm_db_snooze_repeat_t alarm_db_snooze_repeat_t;
 104         typedef enum _alarm_db_auto_power_onoff_t alarm_db_auto_power_onoff_t;
 105         typedef enum _alarm_db_enabled_t alarm_db_enabled_t;
 106         typedef enum _alarm_db_missed_t alarm_db_missed_t;
 107         typedef struct alarm_data AData;
 108         typedef struct alarm_data_list ADList;
 109
 110 /**
 111 * @enum _db_alarm_author_t
 112 * @brief This enumeration defines author
 113 */
 114         enum _alarm_db_author_t {
 115                 ALARM_DB_AUTHOR_ALARM = 0x00,   //alarm
 116                 ALARM_DB_AUTHOR_TIMER,  //timer
 117                 ALARM_DB_AUTHOR_POWEROFF_ALARM, //poweroff alarm, not support now
 118         };
 119 /**
 120 * @enum _db_alarm_repeat_t
 121 * @brief This enumeration defines repeat value
 122 * @details user can use like this: ALARM_REPEAT_SUN|ALARM_REPEAT_TUE
 123 */
 124         enum _alarm_db_repeat_t {
 125                 ALARM_DB_REPEAT_NEVER = 0x00,   //never repeat
 126                 ALARM_DB_REPEAT_SUN = 0x01,     //sunday
 127                 ALARM_DB_REPEAT_MON = 0x02,     //monday
 128                 ALARM_DB_REPEAT_TUE = 0x04,     //tuesday
 129                 ALARM_DB_REPEAT_WED = 0x08,     //wednesday
 130                 ALARM_DB_REPEAT_THU = 0x10,     //thursday
 131                 ALARM_DB_REPEAT_FRI = 0x20,     //friday
 132                 ALARM_DB_REPEAT_SAT = 0x40,     //saturday
 133                 ALARM_DB_REPEAT_WEEKDAYS = 0x3E,        //monday~friday
 134                 ALARM_DB_REPEAT_EVERYDAY = 0x7F,        //sunday~saturday
 135                 ALARM_DB_REPEAT_WEEKENDS = 0x41,        //sunday+saturday
 136         };
 137 /**
 138 * @enum _alarm_db_type_t
 139 * @brief This enumeration defines type value
 140 */
 141         enum _alarm_db_type_t {
 142                 ALARM_DB_TYPE_MELODY = 0x00,
 143                                        /**< Melody */
 144                 ALARM_DB_TYPE_INC_MEL, /**< Raising Melody */
 145                 ALARM_DB_TYPE_VIB,     /**< Vibration */
 146                 ALARM_DB_TYPE_VIB_THEN_MEL,
 147                                        /**< Vibration then Melody */
 148                 ALARM_DB_TYPE_VIB_AND_MEL,
 149                                        /**< Vibration and Melody */
 150                 ALARM_DB_TYPE_VIB_AND_INC_MEL,
 151                                        /**< Vibration then Raising Melody */
 152                 ALARM_DB_TYPE_MAX,
 153         };
 154 /**
 155 * @enum _alarm_db_snooze_duration_t
 156 * @brief This enumeration defines duration type of alarm snoozing .
 157 */
 158         enum _alarm_db_snooze_duration_t {
 159                 ALARM_DB_SNOOZE_MIN_1 = 1,
 160                                        /**< Snooze Time : 1 minute */
 161                 ALARM_DB_SNOOZE_MIN_3 = 3,
 162                                        /**< Snooze Time : 3 minutes */
 163                 ALARM_DB_SNOOZE_MIN_5 = 5,
 164                                        /**< Snooze Time : 5 minutes */
 165                 ALARM_DB_SNOOZE_MIN_10 = 10,
 166                                        /**< Snooze Time : 10 minutes */
 167         };
 168 /**
 169 * @enum _alarm_db_snooze_repeat_t
 170 * @brief This enumeration defines repeat times type of alarm snoozing .
 171 */
 172         enum _alarm_db_snooze_repeat_t {
 173                 ALARM_DB_SNOOZE_TIMES_1 = 1,
 174                                        /**< Snooze Repeat : Once  */
 175                 ALARM_DB_SNOOZE_TIMES_3 = 3,
 176                                        /**< Snooze Repeat : 3 times  */
 177                 ALARM_DB_SNOOZE_TIMES_5 = 5,
 178                                        /**< Snooze Repeat : 5 times  */
 179                 ALARM_DB_SNOOZE_TIMES_10 = 10,
 180                                        /**< Snooze Repeat : 10 times */
 181         };
 182 /**
 183 * @enum _alarm_db_auto_power_onoff_t
 184 * @brief This enumeration defines auto-power on/off .
 185 */
 186         enum _alarm_db_auto_power_onoff_t {
 187                 ALARM_DB_AUTOPOWER_OFF = 0x00,
 188                                        /**< Autopower OFF */
 189                 ALARM_DB_AUTOPOWER_ON = 0x01
 190                                        /**< Autopower ON */
 191         };
 192 /**
 193 * @enum _alarm_db_enabled_t
 194 * @brief This enumeration defines alarm on/off .
 195 */
 196         enum _alarm_db_enabled_t {
 197                 ALARM_DB_ENABLE_OFF = 0x00,
 198                                        /**< Alarm OFF */
 199                 ALARM_DB_ENABLE_ON = 0x01
 200                                        /**< Alarm ON */
 201         };
 202     /**
 203 * @enum _alarm_db_missed_t
 204 * @brief This enumeration defines alarm priority (For internal use).
 205 */
 206         enum _alarm_db_missed_t {
 207                 ALARM_DB_RESERVED_ALARM = 0x00,    /**< Reserved alarm  */
 208                 ALARM_DB_LOW_PRIORITY_ALARM = 0x01,/**< Low priority alarm */
 209                 ALARM_DB_MISSED_ALARM = 0x02,      /**< Missed alarm */
 210                 ALARM_DB_RESERVED_SNOOZING_ALARM = 0x03,
 211                                                    /**< Reseved Snoozing alarm */
 212                 ALARM_DB_MISSED_SNOOZING_ALARM = 0x04,
 213                                                    /**< Missed snoozing alarm */
 214         };
 215
 216 /**
 217 * @struct alarm_data
 218 * @brief This structure defines alarm information.
 219 */
 220         struct alarm_data {
 221                 int _magic;                                             /**< magic value for check struct type,
 222                                                          the value is equal to ALARM_DB_MAGIC_VALUE*/
 223                 int id;                                                 /**< index of alarm */
 224                 int alarm_mgr_id;                                       /**< index from alarm-manager */
 225                 alarm_db_enabled_t enable;                              /**< connected with activation in alarm-manager*/
 226                 alarm_db_missed_t missed;                               /**< for checking missed alarm */
 227                 alarm_db_author_t author;                               /**< alarm author (alarm/timer/...) */
 228                 char name[ALARM_BUF_LEN];                               /**< alarm name */
 229                 time_t stime;                                           /**< start time */
 230                 time_t atime;                                           /**< alert time */
 231                 time_t etime;                                           /**< create or edit time */
 232                 time_t sdate;                                           /**< start date */
 233                 time_t edate;                                           /**< end date */
 234                 char timezone[ALARM_BUF_LEN];                           /**< time zone id */
 235                 bool repeat_once;                                       /**< repeat once */
 236                 bool repeat_every;                                      /**< repeat everyday */
 237                 alarm_db_repeat_t repeat_weekly;                        /**< repeat weekly */
 238                 bool snooze_enable;                                     /**< snooze enable */
 239                 alarm_db_snooze_duration_t snooze_min;                  /**< snooze time */
 240                 alarm_db_snooze_repeat_t snooze_times;                  /**< snooze repeat */
 241                 char count;                                             /**< count of snoozing times */
 242                 alarm_db_type_t type;                                   /**< alarm type */
 243                 char tone[ALARM_BUF_LEN];                               /**< alarm tone file */
 244                 unsigned char volume;                                   /**< volume level */
 245                 alarm_db_auto_power_onoff_t auto_power_on;              /**< use autopower on */
 246         };
 247 /**
 248  * @struct alarm_data_list
 249  * @brief List for Alarm data
 250  */
 251         struct alarm_data_list {
 252                 struct alarm_data ad;   /**< Alarm data */
 253                 struct alarm_data_list *prev;
 254                                         /**< Previous list */
 255                 struct alarm_data_list *next;
 256                                         /**< Next list */
 257         };
 258
 259 /**
 260  * This function init alarm database, create db file to the @param dbfile if the dbfile is not null.
 261  * If the file path is NULL, the db file will be created to the default path.
 262  *
 263  * @brief       Initialize Alarm-Database
 264  *
 265  * @param       [in]   dbfile    the path of user defined.
 266  *
 267  * @return     On success, 0 is returned. On error, -1 is returned
 268  *
 269  * @remarks  The function must be called fristly before calling other functions of alarm-db.
 270  *
 271  * @exception
 272  *
 273  * @see alarmdb_fini
 274  *
 275  */
 276         A_DBAPI int alarmdb_init(const char *dbfile);
 277
 278 /**
 279  * This function fini alarm database, it will close db and free db resource
 280  *
 281  * @brief       Finialize Alarm-Database
 282  *
 283  * @param       none
 284  *
 285  * @return     None
 286  *
 287  * @remarks  The function must be called finally when the application don't need db
 288  *
 289  * @exception
 290  *
 291  * @see alarmdb_init
 292  *
 293  */
 294         A_DBAPI void alarmdb_fini(void);
 295
 296 /**
 297  * This function create a pointer to AData.
 298  * The function must be called after alarmdb_init()
 299  *
 300  * @brief       Create alarm data structure, Ref:  alarmdb_free_data()
 301  *
 302  * @param     None
 303  *
 304  * @return      This function returns  a pointer of alarm_data on  success or NULL on failure.
 305  *
 306  * @remarks
 307  *
 308  * @exception
 309  *
 310  * @see alarmdb_free_data
 311  *
 312  */
 313         A_DBAPI AData *alarmdb_create_data(void);
 314
 315 /**
 316  * This function gets the data of the alarm assosiated with alarm_id.
 317  * It will connect to db and search by id.
 318  *
 319  *
 320  * @brief       Get a data from id
 321  *
 322  * @param       [in]    id        the Database id of the alarm
 323  *
 324  * @return     This function returns  a pointer of alarm_data on  success or NULL on failure.
 325  *
 326  * @remarks The function must be called after alarmdb_init(), and also  given the correct id.
 327  *
 328  * @exception
 329  *
 330  * @see alarmdb_get_data_by_author    alarmdb_get_data_list_by_author
 331  *
 332  */
 333         A_DBAPI AData *alarmdb_get_data(int id);
 334
 335 /**
 336  * This function gets the data of the alarm assosiated with alarm_id and auchor_id.
 337  * The function must be called after alarmdb_init(), and also  given the correct author.
 338  *
 339  * @brief       Get a data from id and author
 340  *
 341  * @param       [in]    id        the Database id of the alarm
 342  * @param       [in]   author    the author id of the alarm:
 343  *              ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM
 344  *
 345  * @return     This function returns  a pointer of alarm_data on  success or NULL on failure.
 346  * @remarks
 347  *
 348  * @exception
 349  *
 350  * @see alarmdb_get_data alarmdb_get_data_list_by_author
 351  *
 352  */
 353         A_DBAPI AData *alarmdb_get_data_by_author(int id, char author);
 354
 355 /**
 356  * This function free the data: AData.
 357  * The function must be called after alarmdb_create_data()
 358  *
 359  * @brief      Free data struct
 360  *
 361  * @param     [in] a pointer to  AData*
 362  *
 363  * @return      None
 364  *
 365  * @remarks When application don't need the alarm_data, must call the function to free the memory
 366  *
 367  * @exception
 368  *
 369  * @see alarmdb_create_data
 370  *
 371  */
 372         A_DBAPI void alarmdb_free_data(AData *);
 373
 374 /**
 375  * This function add the data: AData.
 376  * This function is usually called together with alarmmgr_create();
 377  *
 378  * @brief      Insert a data to DB
 379  *
 380  * @param     [in] a pointer to  AData*
 381  *
 382  * @return      This function returns  the id,saved db id (int), if success, the int value >-1, else return -1.
 383  *
 384  * @remarks
 385  *
 386  * @exception
 387  *
 388  * @see alarmdb_mod_data alarmdb_del_data
 389  *
 390  */
 391         A_DBAPI int alarmdb_add_data(AData *);
 392
 393 /**
 394  *  This function modify the data: AData.
 395  *  This function is usually called together with alarmmgr_update();
 396  *
 397  * @brief      Update a data to DB
 398  *
 399  * @param     [in] a pointer to  AData*
 400  *
 401  * @return      This function returns  the id,saved db id (int), if success, the int value >-1, else return -1.
 402  *
 403  * @remarks
 404  *
 405  * @exception
 406  *
 407  * @see alarmdb_add_data alarmdb_del_data
 408  *
 409  */
 410         A_DBAPI int alarmdb_mod_data(AData *);
 411
 412 /**
 413  *  This function delete the data assosiated with alarm_id.
 414  *  This function is usually called together with alarmmgr_delete();
 415  *
 416  * @brief      Delete a data to DB
 417  *
 418  * @param     [in] id db field
 419  *
 420  * @return      This function returns  0 on success or -1 on fail
 421  *
 422  * @remarks
 423  *
 424  * @exception
 425  *
 426  * @see alarmdb_add_data alarmdb_mod_data
 427  *
 428  */
 429         A_DBAPI int alarmdb_del_data(int id);
 430
 431 /**
 432  *  This function update the alarm is enable/disable.
 433  *  This function is usually called together with alarmmgr_update();
 434  *
 435  * @brief      Set enable/disable an alarm
 436  *
 437  * @param     [in] id: id db field
 438  *                     [in] enable: true->enable, false->disable
 439  *
 440  * @return     This function returns  0 on success or -1 on fail
 441  *
 442  * @remarks
 443  *
 444  * @exception
 445  *
 446  * @see alarmdb_get_num_of_enable
 447  *
 448  */
 449         A_DBAPI int alarmdb_set_enable(int id, bool enable);
 450
 451 /**
 452  *  This function get the number of the enabled alarm.
 453  *  This function is usually called together with vconf_set_int(VCONFKEY_ALARM_STATE, @return)
 454  *
 455  * @brief      Get number of enabled alarm
 456  *
 457  * @param     none
 458  *
 459  * @return     This function returns  the number of enable's alarm in db on success or -1 on fail
 460  *
 461  * @remarks
 462  *
 463  * @exception
 464  *
 465  * @see alarmdb_set_enable
 466  *
 467  */
 468         A_DBAPI int alarmdb_get_num_of_enable(void);
 469
 470 /**
 471  *  This function set snooze on an alarm enable or disable
 472  *
 473  * @brief      Set enable/disable snooze on an alarm
 474  *
 475  * @param     [in] id: id db field
 476  *                     [in] enable: true->enable, false->disable
 477  *
 478  * @return     This function returns  0 on success or -1 on fail
 479  *
 480  * @remarks
 481  *
 482  * @exception
 483  *
 484  * @see
 485  *
 486  */
 487         A_DBAPI int alarmdb_set_snooze(int id, bool enable);
 488
 489 /**
 490  *  This function get the last alarm id
 491  *
 492  *
 493  * @brief      Get last alarm id
 494  *
 495  * @param     none
 496  *
 497  * @return     This function returns  the last alarm_id in db on success, -1 on fail
 498  *
 499  * @remarks
 500  *
 501  * @exception
 502  *
 503  * @see alarmdb_get_last_id_by_author
 504  *
 505  */
 506         A_DBAPI int alarmdb_get_last_id(void);
 507
 508 /**
 509  *  This function gets the last alarm id  assosiated with auchor_id.
 510  *
 511  *
 512  * @brief      Get last alarm (generated by specific author)
 513  *
 514  * @param       [in]   author    the author id of the alarm:
 515  *              ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM
 516  *
 517  * @return    This function returns  the last alarm_id in db on success, -1 on fail
 518  *
 519  * @remarks
 520  *
 521  * @exception
 522  *
 523  * @see alarmdb_get_last_id
 524  *
 525  */
 526         A_DBAPI int alarmdb_get_last_id_by_author(char author);
 527
 528 /**
 529  *  This function get the number of the enabled alarm.
 530  *
 531  *
 532  * @brief      Get number of alarm (generated by specific author)
 533  *
 534  * @param     [in]   author    the author id of the alarm:
 535  *            ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM
 536  *
 537  * @return      This function returns  the number of alarm of the author in db on success ,  -1 on fail
 538  *
 539  * @remarks
 540  *
 541  * @exception
 542  *
 543  * @see
 544  *
 545  */
 546         A_DBAPI int alarmdb_get_number_of_data_by_author(char author);
 547
 548 /**
 549  * This function gets the data list of the alarm assosiated with auchor_id.
 550  * The function can be called after alarmdb_init(), and also  given the correct author.
 551  *
 552  * @brief       Get power on/off value (generated by specific author)
 553  *
 554  * @param       [in]   author    the author id of the alarm:
 555  *              ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM
 556  *
 557  * @return     This function returns  the state of alarm auto-power state,
 558  *                     enum alarm_auto_power_onoff_t: ALARM_DB_AUTOPOWER_OFF/ALARM_DB_AUTOPOWER_ON
 559  * @remarks
 560  *
 561  * @exception
 562  *
 563  * @see enum:alarm_auto_power_onoff_t
 564  *
 565  */
 566         A_DBAPI int alarmdb_get_power_onoff_by_author(char author);
 567
 568 /**
 569  *  This function gets the data list of the alarm assosiated.
 570  *
 571  *
 572  * @brief      Get all alarm list
 573  *
 574  * @param     none
 575  *
 576  * @return     This function returns  a pointer of alarm_data_list on  success or NULL on failure.
 577  *
 578  * @remarks
 579  *
 580  * @exception
 581  *
 582  * @see alarmdb_get_data_list_by_author
 583  *
 584  */
 585         A_DBAPI ADList *alarmdb_get_data_list_all(void);
 586
 587 /**
 588  * This function gets the data list of the alarm assosiated with auchor_id.
 589  * The function can be called after alarmdb_init(), and also  given the correct author.
 590  *
 591  * @brief         Get  alarm list(generated by specific author)
 592  *
 593  * @param       [in]   author    the author id of the alarm:
 594  *              ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM
 595  *
 596  * @return     This function returns  a pointer of alarm_data_list on  success or NULL on failure.
 597  * @remarks
 598  *
 599  * @exception
 600  *
 601  * @see alarmdb_get_data_list_all
 602  *
 603  */
 604         A_DBAPI ADList *alarmdb_get_data_list_by_author(char author);
 605
 606 /**
 607  *  This function free the data list of ADList
 608  *  This function must be called when not being needed, if application call
 609  *  alarmdb_get_data_list_by_author/alarmdb_get_data_list_all.
 610  *
 611  * @brief      Free data list
 612  *
 613  * @param     [in] pointer of alarm_data_list
 614  *
 615  * @return     None
 616  *
 617  * @remarks
 618  *
 619  * @exception
 620  *
 621  * @see alarmdb_get_data_list_all alarmdb_get_data_list_by_author
 622  *
 623  */
 624         A_DBAPI void alarmdb_free_data_list(ADList *);
 625
 626 #ifdef __cplusplus
 627 }
 628 #endif
 629 #endif                          /* __ALARM_ENGINE_H__ */