path: root/include/alarm-engine.h

/*
*
* Copyright 2012  Samsung Electronics Co., Ltd
*
* Licensed under the Flora License, Version 1.0 (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 <jiwon11.lee@samsung.com>, Jae-yong Lee <jaeyong911.lee@samsung.com>
 * @date                2010-01-07
 * @version             0.0.1
 */

#ifndef __ALARM_ENGINE_H__
#define __ALARM_ENGINE_H__

#include <stdbool.h>
#include <time.h>

//#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__ */