include/alarm-engine.h

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