/* * * Copyright 2012 Samsung Electronics Co., Ltd * * Licensed under the Flora License, Version 1.1 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://floralicense.org/license/ * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * */ /*! * @defgroup app_lib Application library * This is a framework for User interface */ /*! * @defgroup alarm_engine_group Alarm DB Library * @ingroup app_lib * Functions to APIs to access alarm DB. */ /** * @file alarm-engine.h * @ingroup alarm_engine_group * @brief This library provides APIs to access alarm DB. * @author Jiwon Lee , Jae-yong Lee * @date 2010-01-07 * @version 0.0.1 */ #ifndef __ALARM_ENGINE_H__ #define __ALARM_ENGINE_H__ #include #include //#include "sglib.h" #ifdef __cplusplus extern "C" { #endif /** * @def A_DBAPI * prefix */ #ifndef A_DBAPI #define A_DBAPI __attribute__ ((visibility("default"))) #endif /** * @def ALARM_BUF_LEN * Maxium length of Buffer */ #define ALARM_BUF_LEN (128) /** * @def DEFAULT_ALARM_DB_REPEAT * default value about repeat */ #define DEFAULT_ALARM_DB_REPEAT ALARM_DB_REPEAT_NEVER /** * @def DEFAULT_ALARM_DB_TYPE * default value about type */ #define DEFAULT_ALARM_DB_TYPE ALARM_DB_TYPE_MELODY /** * @def DEFAULT_ALARM_DB_SNOOZE_DURATION * default value about snooze duration */ #define DEFAULT_ALARM_DB_SNOOZE_DURATION ALARM_DB_SNOOZE_MIN_5 /** * @def DEFAULT_ALARM_DB_SNOOZE_REPEAT * default value about snooze repeat */ #define DEFAULT_ALARM_DB_SNOOZE_REPEAT ALARM_DB_SNOOZE_TIMES_3 /** * @def DEFAULT_ALARM_DB_VOLUME * default value about volume */ #define DEFAULT_ALARM_DB_VOLUME (4) /** * return value */ #define ALARM_DB_RESULT_SUCCESS 0 #define ALARM_DB_RESULT_FAILED -1 /** * @def ALARM_DB_MAGIC_VALUE * magic value for judge struct type */ #define ALARM_DB_MAGIC_VALUE (0x6E) #define MAGIC_VALUE_SET(p) (p) = ALARM_DB_MAGIC_VALUE; #define MAGIC_VALUE_CHECK(p) IS_EQUAL(p, ALARM_DB_MAGIC_VALUE) typedef enum _alarm_db_author_t alarm_db_author_t; typedef enum _alarm_db_repeat_t alarm_db_repeat_t; typedef enum _alarm_db_type_t alarm_db_type_t; typedef enum _alarm_db_snooze_duration_t alarm_db_snooze_duration_t; typedef enum _alarm_db_snooze_repeat_t alarm_db_snooze_repeat_t; typedef enum _alarm_db_auto_power_onoff_t alarm_db_auto_power_onoff_t; typedef enum _alarm_db_enabled_t alarm_db_enabled_t; typedef enum _alarm_db_missed_t alarm_db_missed_t; typedef struct alarm_data AData; typedef struct alarm_data_list ADList; /** * @enum _db_alarm_author_t * @brief This enumeration defines author */ enum _alarm_db_author_t { ALARM_DB_AUTHOR_ALARM = 0x00, //alarm ALARM_DB_AUTHOR_TIMER, //timer ALARM_DB_AUTHOR_POWEROFF_ALARM, //poweroff alarm, not support now }; /** * @enum _db_alarm_repeat_t * @brief This enumeration defines repeat value * @details user can use like this: ALARM_REPEAT_SUN|ALARM_REPEAT_TUE */ enum _alarm_db_repeat_t { ALARM_DB_REPEAT_NEVER = 0x00, //never repeat ALARM_DB_REPEAT_SUN = 0x01, //sunday ALARM_DB_REPEAT_MON = 0x02, //monday ALARM_DB_REPEAT_TUE = 0x04, //tuesday ALARM_DB_REPEAT_WED = 0x08, //wednesday ALARM_DB_REPEAT_THU = 0x10, //thursday ALARM_DB_REPEAT_FRI = 0x20, //friday ALARM_DB_REPEAT_SAT = 0x40, //saturday ALARM_DB_REPEAT_WEEKDAYS = 0x3E, //monday~friday ALARM_DB_REPEAT_EVERYDAY = 0x7F, //sunday~saturday ALARM_DB_REPEAT_WEEKENDS = 0x41, //sunday+saturday }; /** * @enum _alarm_db_type_t * @brief This enumeration defines type value */ enum _alarm_db_type_t { ALARM_DB_TYPE_MELODY = 0x00, /**< Melody */ ALARM_DB_TYPE_VIB, /**< Vibration */ ALARM_DB_TYPE_VIB_AND_MEL, /**< Vibration and Melody */ ALARM_DB_TYPE_MAX, }; /** * @enum _alarm_db_snooze_duration_t * @brief This enumeration defines duration type of alarm snoozing . */ enum _alarm_db_snooze_duration_t { ALARM_DB_SNOOZE_MIN_1 = 1, /**< Snooze Time : 1 minute */ ALARM_DB_SNOOZE_MIN_3 = 3, /**< Snooze Time : 3 minutes */ ALARM_DB_SNOOZE_MIN_5 = 5, /**< Snooze Time : 5 minutes */ ALARM_DB_SNOOZE_MIN_10 = 10, /**< Snooze Time : 10 minutes */ }; /** * @enum _alarm_db_snooze_repeat_t * @brief This enumeration defines repeat times type of alarm snoozing . */ enum _alarm_db_snooze_repeat_t { ALARM_DB_SNOOZE_TIMES_1 = 1, /**< Snooze Repeat : Once */ ALARM_DB_SNOOZE_TIMES_3 = 3, /**< Snooze Repeat : 3 times */ ALARM_DB_SNOOZE_TIMES_5 = 5, /**< Snooze Repeat : 5 times */ ALARM_DB_SNOOZE_TIMES_10 = 10, /**< Snooze Repeat : 10 times */ }; /** * @enum _alarm_db_auto_power_onoff_t * @brief This enumeration defines auto-power on/off . */ enum _alarm_db_auto_power_onoff_t { ALARM_DB_AUTOPOWER_OFF = 0x00, /**< Autopower OFF */ ALARM_DB_AUTOPOWER_ON = 0x01 /**< Autopower ON */ }; /** * @enum _alarm_db_enabled_t * @brief This enumeration defines alarm on/off . */ enum _alarm_db_enabled_t { ALARM_DB_ENABLE_OFF = 0x00, /**< Alarm OFF */ ALARM_DB_ENABLE_ON = 0x01 /**< Alarm ON */ }; /** * @enum _alarm_db_missed_t * @brief This enumeration defines alarm priority (For internal use). */ enum _alarm_db_missed_t { ALARM_DB_RESERVED_ALARM = 0x00, /**< Reserved alarm */ ALARM_DB_LOW_PRIORITY_ALARM = 0x01,/**< Low priority alarm */ ALARM_DB_MISSED_ALARM = 0x02, /**< Missed alarm */ ALARM_DB_RESERVED_SNOOZING_ALARM = 0x03, /**< Reseved Snoozing alarm */ ALARM_DB_MISSED_SNOOZING_ALARM = 0x04, /**< Missed snoozing alarm */ }; /** * @struct alarm_data * @brief This structure defines alarm information. */ struct alarm_data { int _magic; /**< magic value for check struct type, the value is equal to ALARM_DB_MAGIC_VALUE*/ int id; /**< index of alarm */ int alarm_mgr_id; /**< index from alarm-manager */ alarm_db_enabled_t enable; /**< connected with activation in alarm-manager*/ alarm_db_missed_t missed; /**< for checking missed alarm */ alarm_db_author_t author; /**< alarm author (alarm/timer/...) */ char name[ALARM_BUF_LEN]; /**< alarm name */ time_t stime; /**< start time */ time_t atime; /**< alert time */ time_t etime; /**< create or edit time */ time_t sdate; /**< start date */ time_t edate; /**< end date */ char timezone[ALARM_BUF_LEN]; /**< time zone id */ bool repeat_once; /**< repeat once */ bool repeat_every; /**< repeat everyday */ alarm_db_repeat_t repeat_weekly; /**< repeat weekly */ bool snooze_enable; /**< snooze enable */ alarm_db_snooze_duration_t snooze_min; /**< snooze time */ alarm_db_snooze_repeat_t snooze_times; /**< snooze repeat */ char count; /**< count of snoozing times */ alarm_db_type_t type; /**< alarm type */ char tone[ALARM_BUF_LEN]; /**< alarm tone file */ unsigned char volume; /**< volume level */ alarm_db_auto_power_onoff_t auto_power_on; /**< use autopower on */ }; /** * @struct alarm_data_list * @brief List for Alarm data */ struct alarm_data_list { struct alarm_data ad; /**< Alarm data */ struct alarm_data_list *prev; /**< Previous list */ struct alarm_data_list *next; /**< Next list */ }; /** * This function init alarm database, create db file to the @param dbfile if the dbfile is not null. * If the file path is NULL, the db file will be created to the default path. * * @brief Initialize Alarm-Database * * @param [in] dbfile the path of user defined. * * @return On success, 0 is returned. On error, -1 is returned * * @remarks The function must be called fristly before calling other functions of alarm-db. * * @exception * * @see alarmdb_fini * */ A_DBAPI int alarmdb_init(const char *dbfile); /** * This function fini alarm database, it will close db and free db resource * * @brief Finialize Alarm-Database * * @param none * * @return None * * @remarks The function must be called finally when the application don't need db * * @exception * * @see alarmdb_init * */ A_DBAPI void alarmdb_fini(void); /** * This function create a pointer to AData. * The function must be called after alarmdb_init() * * @brief Create alarm data structure, Ref: alarmdb_free_data() * * @param None * * @return This function returns a pointer of alarm_data on success or NULL on failure. * * @remarks * * @exception * * @see alarmdb_free_data * */ A_DBAPI AData *alarmdb_create_data(void); /** * This function gets the data of the alarm assosiated with alarm_id. * It will connect to db and search by id. * * * @brief Get a data from id * * @param [in] id the Database id of the alarm * * @return This function returns a pointer of alarm_data on success or NULL on failure. * * @remarks The function must be called after alarmdb_init(), and also given the correct id. * * @exception * * @see alarmdb_get_data_by_author alarmdb_get_data_list_by_author * */ A_DBAPI AData *alarmdb_get_data(int id); /** * This function gets the data of the alarm assosiated with alarm_id and auchor_id. * The function must be called after alarmdb_init(), and also given the correct author. * * @brief Get a data from id and author * * @param [in] id the Database id of the alarm * @param [in] author the author id of the alarm: * ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM * * @return This function returns a pointer of alarm_data on success or NULL on failure. * @remarks * * @exception * * @see alarmdb_get_data alarmdb_get_data_list_by_author * */ A_DBAPI AData *alarmdb_get_data_by_author(int id, char author); /** * This function free the data: AData. * The function must be called after alarmdb_create_data() * * @brief Free data struct * * @param [in] a pointer to AData* * * @return None * * @remarks When application don't need the alarm_data, must call the function to free the memory * * @exception * * @see alarmdb_create_data * */ A_DBAPI void alarmdb_free_data(AData *); /** * This function add the data: AData. * This function is usually called together with alarmmgr_create(); * * @brief Insert a data to DB * * @param [in] a pointer to AData* * * @return This function returns the id,saved db id (int), if success, the int value >-1, else return -1. * * @remarks * * @exception * * @see alarmdb_mod_data alarmdb_del_data * */ A_DBAPI int alarmdb_add_data(AData *); /** * This function modify the data: AData. * This function is usually called together with alarmmgr_update(); * * @brief Update a data to DB * * @param [in] a pointer to AData* * * @return This function returns the id,saved db id (int), if success, the int value >-1, else return -1. * * @remarks * * @exception * * @see alarmdb_add_data alarmdb_del_data * */ A_DBAPI int alarmdb_mod_data(AData *); /** * This function delete the data assosiated with alarm_id. * This function is usually called together with alarmmgr_delete(); * * @brief Delete a data to DB * * @param [in] id db field * * @return This function returns 0 on success or -1 on fail * * @remarks * * @exception * * @see alarmdb_add_data alarmdb_mod_data * */ A_DBAPI int alarmdb_del_data(int id); /** * This function update the alarm is enable/disable. * This function is usually called together with alarmmgr_update(); * * @brief Set enable/disable an alarm * * @param [in] id: id db field * [in] enable: true->enable, false->disable * * @return This function returns 0 on success or -1 on fail * * @remarks * * @exception * * @see alarmdb_get_num_of_enable * */ A_DBAPI int alarmdb_set_enable(int id, bool enable); /** * This function get the number of the enabled alarm. * This function is usually called together with vconf_set_int(VCONFKEY_ALARM_STATE, @return) * * @brief Get number of enabled alarm * * @param none * * @return This function returns the number of enable's alarm in db on success or -1 on fail * * @remarks * * @exception * * @see alarmdb_set_enable * */ A_DBAPI int alarmdb_get_num_of_enable(void); /** * This function set snooze on an alarm enable or disable * * @brief Set enable/disable snooze on an alarm * * @param [in] id: id db field * [in] enable: true->enable, false->disable * * @return This function returns 0 on success or -1 on fail * * @remarks * * @exception * * @see * */ A_DBAPI int alarmdb_set_snooze(int id, bool enable); /** * This function get the last alarm id * * * @brief Get last alarm id * * @param none * * @return This function returns the last alarm_id in db on success, -1 on fail * * @remarks * * @exception * * @see alarmdb_get_last_id_by_author * */ A_DBAPI int alarmdb_get_last_id(void); /** * This function gets the last alarm id assosiated with auchor_id. * * * @brief Get last alarm (generated by specific author) * * @param [in] author the author id of the alarm: * ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM * * @return This function returns the last alarm_id in db on success, -1 on fail * * @remarks * * @exception * * @see alarmdb_get_last_id * */ A_DBAPI int alarmdb_get_last_id_by_author(char author); /** * This function get the number of the enabled alarm. * * * @brief Get number of alarm (generated by specific author) * * @param [in] author the author id of the alarm: * ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM * * @return This function returns the number of alarm of the author in db on success , -1 on fail * * @remarks * * @exception * * @see * */ A_DBAPI int alarmdb_get_number_of_data_by_author(char author); /** * This function gets the data list of the alarm assosiated with auchor_id. * The function can be called after alarmdb_init(), and also given the correct author. * * @brief Get power on/off value (generated by specific author) * * @param [in] author the author id of the alarm: * ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM * * @return This function returns the state of alarm auto-power state, * enum alarm_auto_power_onoff_t: ALARM_DB_AUTOPOWER_OFF/ALARM_DB_AUTOPOWER_ON * @remarks * * @exception * * @see enum:alarm_auto_power_onoff_t * */ A_DBAPI int alarmdb_get_power_onoff_by_author(char author); /** * This function gets the data list of the alarm assosiated. * * * @brief Get all alarm list * * @param none * * @return This function returns a pointer of alarm_data_list on success or NULL on failure. * * @remarks * * @exception * * @see alarmdb_get_data_list_by_author * */ A_DBAPI ADList *alarmdb_get_data_list_all(void); /** * This function gets the data list of the alarm assosiated with auchor_id. * The function can be called after alarmdb_init(), and also given the correct author. * * @brief Get alarm list(generated by specific author) * * @param [in] author the author id of the alarm: * ALARM_DB_AUTHOR_ALARM/ALARM_DB_AUTHOR_TIMER/ALARM_DB_AUTHOR_POWEROFF_ALARM * * @return This function returns a pointer of alarm_data_list on success or NULL on failure. * @remarks * * @exception * * @see alarmdb_get_data_list_all * */ A_DBAPI ADList *alarmdb_get_data_list_by_author(char author); /** * This function free the data list of ADList * This function must be called when not being needed, if application call * alarmdb_get_data_list_by_author/alarmdb_get_data_list_all. * * @brief Free data list * * @param [in] pointer of alarm_data_list * * @return None * * @remarks * * @exception * * @see alarmdb_get_data_list_all alarmdb_get_data_list_by_author * */ A_DBAPI void alarmdb_free_data_list(ADList *); #ifdef __cplusplus } #endif #endif /* __ALARM_ENGINE_H__ */