diff options
Diffstat (limited to 'include/calendar.h')
| -rwxr-xr-x | include/calendar.h | 1852 |
1 files changed, 1312 insertions, 540 deletions
diff --git a/include/calendar.h b/include/calendar.h index cb12a45..74020d0 100755 --- a/include/calendar.h +++ b/include/calendar.h @@ -11,17 +11,17 @@ * 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. + * limitations under the License. */ - + #ifndef __TIZEN_SOCIAL_CALENDAR_CALENDAR_H__ #define __TIZEN_SOCIAL_CALENDAR_CALENDAR_H__ #include <tizen.h> #include <time.h> -#include <calendar_attendee.h> -#include <calendar_types.h> +#include "calendar_attendee.h" +#include "calendar_types.h" #ifdef __cplusplus @@ -36,9 +36,9 @@ extern "C" { /** * @brief Connects to the calendar service. * - * @details Opening connection is necessary to access the calendar database. + * @details Opening connection is necessary to access the calendar database. * All operations like inserting, updating, or deleting calendar require opened connection to work properly. - + * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_DB_FAILED No access to database @@ -61,27 +61,56 @@ int calendar_connect(void); int calendar_disconnect(void); /** - * @brief Retrieves all timezone information supported on a device. + * @brief Begins transaction to calendar database * - * @param[in] callback The callback function to invoke - * @param[in] user_data The user data to be passed to the callback function + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_DB_FAILED No access to database * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @post This function invokes calendar_foreach_timezone_cb(). + * @see calendar_connect() + * @see calendar_rollback_transaction() + * @see calendar_commit_transaction() + */ +int calendar_begin_transaction(void); + +/** + * @brief Rollbacks transaction to calendar database * - * @see calendar_foreach_timezone_cb() - * @see calendar_event_set_timezone() - * @see calendar_todo_set_timezone() + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + * @see calendar_begin_transaction() + * @see calendar_commit_transaction() */ -int calendar_foreach_timezone(calendar_foreach_timezone_cb callback, void *user_data); +int calendar_rollback_transaction(void); /** - * @brief Registers a callback function to be invoked when any database change occur. + * @brief Commits transaction to calendar database + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_DB_FAILED No access to database * - * @param[in] callback The callback function to invoke + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + * @see calendar_begin_transaction() + * @see calendar_rollback_transaction() + */ +int calendar_commit_transaction(void); + + +/** + * @brief Registers a callback function to be invoked when any database change occurs. + * + * @param[in] callback The callback function to invoke + * @param[in] type The notification type to subscribe * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. @@ -90,19 +119,26 @@ int calendar_foreach_timezone(calendar_foreach_timezone_cb callback, void *user_ * * @pre This function requires an open connection to the calendar service by calendar_connect(). * @post calendar_db_changed_cb() will be invoked. - * + * * @see calendar_db_changed_cb() - * @see calendar_unset_db_changed_cb() + * @see calendar_remove_db_changed_cb() + * @see calendar_book_insert_to_db() + * @see calendar_book_update_to_db() + * @see calendar_book_delete_from_db() * @see calendar_event_insert_to_db() * @see calendar_event_update_to_db() * @see calendar_event_delete_from_db() + * @see calendar_todo_insert_to_db() + * @see calendar_todo_update_to_db() + * @see calendar_todo_delete_from_db() */ -int calendar_set_db_changed_cb(calendar_db_changed_cb callback, void *user_data); +int calendar_add_db_changed_cb(calendar_db_changed_cb callback, calendar_db_changed_cb_type_e type, void *user_data); /** * @brief Unregisters the callback function. * * @param[in] callback The callback function to unregister + * @param[in] type The notification type to unregister callback * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -110,9 +146,23 @@ int calendar_set_db_changed_cb(calendar_db_changed_cb callback, void *user_data) * * @pre This function requires an open connection to the calendar service by calendar_connect(). * @see calendar_db_changed_cb() - * @see calendar_set_db_changed_cb() + * @see calendar_add_db_changed_cb() + */ +int calendar_remove_db_changed_cb(calendar_db_changed_cb callback, calendar_db_changed_cb_type_e type); + +/** + * @brief Gets the calendar database version. + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_DB_FAILED Database operation failure + * + * @see calendar_connect() + * @see calendar_query_event_by_version() + * @see calendar_query_todo_by_version() */ -int calendar_unset_db_changed_cb(calendar_db_changed_cb callback); +int calendar_get_db_version(int* calendar_db_version); /** * @} @@ -144,7 +194,7 @@ int calendar_event_create(calendar_event_h *event); /** * @brief Destroys the calendar event handle and releases all its resources. * - * @param[out] event The calendar event handle + * @param[out] event The calendar event handle * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -158,10 +208,10 @@ int calendar_event_destroy(calendar_event_h event); /** * @brief Adds a calendar event to the calendar database. * - * @param[in] event The calendar event handle - * @param[in] calendar_db_id The calendar database ID to which the event insert. \n - * 1 means the default calendar on the device - * @param[out] event_db_id The event db ID associated with the calendar event \n + * @param[in] event The calendar event handle + * @param[in] calendar_book_db_id The calendar book database ID to which the event insert. \n + * #DEFAULT_EVENT_CALENDAR_BOOK_DB_ID means the default event calendar book on the device + * @param[out] event_db_id The event database ID associated with the calendar event \n * If the function fails, it is -1. * * @return 0 on success, otherwise a negative error value. @@ -174,12 +224,12 @@ int calendar_event_destroy(calendar_event_h event); * @see calendar_event_update_to_db() * @see calendar_event_delete_from_db() */ -int calendar_event_insert_to_db(calendar_event_h event, int calendar_db_id, int *event_db_id); +int calendar_event_insert_to_db(calendar_event_h event, int calendar_book_db_id, int *event_db_id); /** * @brief Removes the calendar event from the calendar database. * - * @param[in] event_id The event ID to delete + * @param[in] event_db_id The database event ID to delete * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -191,13 +241,13 @@ int calendar_event_insert_to_db(calendar_event_h event, int calendar_db_id, int * @see calendar_event_insert_to_db() * @see calendar_event_update_to_db() */ -int calendar_event_delete_from_db(int event_id); +int calendar_event_delete_from_db(int event_db_id); /** * @brief Updates the calendar event in the calendar database. * @details calendar_event_get_db_id() is called internally to update in the calendar database to get the event ID in the calendar database. * - * @param[in] event The calendar event handle + * @param[in] event The calendar event handle * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -218,9 +268,9 @@ int calendar_event_update_to_db(calendar_event_h event); /** * @brief Gets the calendar event from the calendar database. * @details This function gets the new calendar event handle with the given event database ID from the calendar database. \n - * The new calendar event handle will be created. + * The new calendar event handle will be created. * - * @remarks The created calendar event handle must be released with calendar_event_destroy() by you. + * @remarks The created calendar event handle must be released with calendar_event_destroy() by you. * * * @param[in] event_id The event ID @@ -235,14 +285,14 @@ int calendar_event_update_to_db(calendar_event_h event); * * @see calendar_event_destroy() */ -int calendar_event_get_from_db(int event_id, calendar_event_h *event); +int calendar_event_get_from_db(int event_db_id, calendar_event_h *event); /** - * @brief Gets the database ID associated with the given calendar event handle. + * @brief Gets the database ID associated with the given calendar event handle. * * @param[in] event The calendar event handle * @param[out] event_db_id The event database ID fetched from the calendar event handle (default : 0) \n - * 0 means the event is not in calendar database. + * 0 means the event is not in calendar database. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -254,11 +304,11 @@ int calendar_event_get_from_db(int event_id, calendar_event_h *event); int calendar_event_get_db_id(calendar_event_h event, int *event_db_id); /** - * @brief Gets the calendar database ID associated with the given calendar event handle. + * @brief Gets The calendar book database ID associated with the given calendar event handle. * * @param[in] event The calendar event handle - * @param[out] calendar_db_id The calendar database ID fetched from the calendar event handle (default : 0) \n - * 0 means the event is not in calendar database. + * @param[out] calendar_book_db_id The calendar book database ID fetched from the calendar event handle (default : 0) \n + * 0 means the event is not in calendar database. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -266,14 +316,14 @@ int calendar_event_get_db_id(calendar_event_h event, int *event_db_id); * * @see calendar_event_insert_to_db() */ -int calendar_event_get_calendar_db_id(calendar_event_h event, int *calendar_db_id); +int calendar_event_get_calendar_book_db_id(calendar_event_h event, int *calendar_book_db_id); /** * @brief Gets the subject of the event from the calendar event handle . * * @remarks @a subject must be released with free() by you. * - * @param [in] event The calendar event handle + * @param [in] event The calendar event handle * @param [out] subject The subject of the event \n If the subject does not exist, it is NULL * * @return 0 on success, otherwise a negative error value. @@ -285,11 +335,10 @@ int calendar_event_get_calendar_db_id(calendar_event_h event, int *calendar_db_i */ int calendar_event_get_subject(calendar_event_h event, char **subject); - /** * @brief Sets the subject of the event in the calendar event handle. * - * @param [in] event The calendar event handle + * @param [in] event The calendar event handle * @param [in] subject The subject of the event * * @return 0 on success, otherwise a negative error value. @@ -300,13 +349,12 @@ int calendar_event_get_subject(calendar_event_h event, char **subject); */ int calendar_event_set_subject(calendar_event_h event, const char *subject); - /** * @brief Gets the description of the event from the calendar event handle. * - * @remarks @a description must be released with free() by you. + * @remarks @a description must be released with free() by you. * - * @param [in] event The calendar event handle + * @param [in] event The calendar event handle * @param [out] description The description of the event \n If the description does not exist, it is NULL * * @return 0 on success, otherwise a negative error value. @@ -317,11 +365,10 @@ int calendar_event_set_subject(calendar_event_h event, const char *subject); */ int calendar_event_get_description(calendar_event_h event, char **description); - /** * @brief Sets a description of the event in the calendar event handle. * - * @param [in] event The calendar event handle + * @param [in] event The calendar event handle * @param [in] description The description of the event * * @return 0 on success, otherwise a negative error value. @@ -332,11 +379,72 @@ int calendar_event_get_description(calendar_event_h event, char **description); */ int calendar_event_set_description(calendar_event_h event, const char *description); +/** + * @brief Gets the start time of the event from the calendar event handle. + * + * @param [in] event The calendar event handle + * @param [out] start_time The start date of the event \n + * The @a start_time is a unix timestamp since 00:00, Jan 1 1970 UTC. + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_NO_DATA Data not found + * + * @see calendar_event_set_start_time() + */ +int calendar_event_get_start_time(calendar_event_h event, long long int *start_time); + +/** + * @brief Sets a start time of the event in the calendar event handle. + * + * @param [in] event The calendar event handle + * @param [in] start_time The start date of the event \n + * The @a start_time is a unix timestamp since 00:00, Jan 1 1970 UTC. + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_get_start_time() + */ +int calendar_event_set_start_time(calendar_event_h event, long long int start_time); + +/** + * @brief Gets the end time of the event from the calendar event handle. + * + * @param [in] event The calendar event handle + * @param [out] end_time The end date of the event\n + * The @a end_time is a unix timestamp since 00:00, Jan 1 1970 UTC. + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_NO_DATA Data not found + * + * @see calendar_event_set_end_time() + */ +int calendar_event_get_end_time(calendar_event_h event, long long int *end_time); + +/** + * @brief Sets the end time of the event in the calendar event handle. + * + * @param[in] event The calendar event handle + * @param[in] end_time The end date of the event\n + * The @a end_time is a unix timestamp since 00:00, Jan 1 1970 UTC. + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_get_end_time() + */ +int calendar_event_set_end_time(calendar_event_h event, long long int end_time); /** * @brief Gets an all-day event property of the calendar event handle. * - * @param [in] event The calendar event handle + * @param [in] event The calendar event handle * @param [out] is_all_day_event @c true if the event lasts for an entire day, otherwise @c false \n * (default : @c false) * @@ -348,30 +456,54 @@ int calendar_event_set_description(calendar_event_h event, const char *descripti */ int calendar_event_get_is_all_day_event(calendar_event_h event, bool *is_all_day_event); - /** - * @brief Sets an all-day event property of the calendar event handle. + * @brief Sets an all-day event with date range * - * @param [in] event The calendar event handle - * @param [in] is_all_day_event The all-day event type \n - * @c true if the event will last for an entire day, otherwise @c false \n - * (default : @c false) + * @param [in] event The calendar event handle + * @param [in] start_year Year of start date + * @param [in] start_month Month of start date + * @param [in] start_day Day of start date + * @param [in] end_year Year of end date + * @param [in] end_month Month of end date + * @param [in] end_day Day of end date * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * * @see calendar_event_get_is_all_day_event() + * @see calendar_event_get_all_day_event() */ -int calendar_event_set_is_all_day_event(calendar_event_h event, bool is_all_day_event); +int calendar_event_set_all_day_event(calendar_event_h event, int start_year, int start_month, int start_day, + int end_year, int end_month, int end_day); +/** + * @brief Gets an all-day event date range + * + * @param [in] event The calendar event handle + * @param [out] start_year Year of start date + * @param [out] start_month Month of start date + * @param [out] start_day Day of start date + * @param [out] end_year Year of end date + * @param [out] end_month Month of end date + * @param [out] end_day Day of end date + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_get_is_all_day_event() + * @see calendar_event_set_all_day_event() + */ +int calendar_event_get_all_day_event(calendar_event_h event, int *start_year, int *start_month, int *start_day, + int *end_year, int *end_month, int *end_day); /** * @brief Gets the location of the event from the calendar event handle. * - * @remarks @a location must be released with free() by you. + * @remarks @a location must be released with free() by you. * - * @param [in] event The calendar event handle + * @param [in] event The calendar event handle * @param [out] location The location of the event \n If the location does not exist, it is NULL * * @return 0 on success, otherwise a negative error value. @@ -382,11 +514,10 @@ int calendar_event_set_is_all_day_event(calendar_event_h event, bool is_all_day_ */ int calendar_event_get_location(calendar_event_h event, char **location); - /** * @brief Sets a location of the event in the calendar event handle. * - * @param [in] event The calendar event handle + * @param [in] event The calendar event handle * @param [in] location The location of the event * * @return 0 on success, otherwise a negative error value. @@ -397,15 +528,14 @@ int calendar_event_get_location(calendar_event_h event, char **location); */ int calendar_event_set_location(calendar_event_h event, const char *location); - /** * @brief Gets the reminder of the event from the calendar event handle. * @details The function returns reminder type and interval of the event. - * * - * @param [in] event The calendar event handle - * @param [out] reminder_interval_type The reminder type - * @param [out] reminder_interval The interval + * + * @param [in] event The calendar event handle + * @param [out] reminder_interval_type The reminder type + * @param [out] reminder_interval The interval * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -415,13 +545,12 @@ int calendar_event_set_location(calendar_event_h event, const char *location); */ int calendar_event_get_reminder(calendar_event_h event, calendar_reminder_interval_type_e *reminder_interval_type, int *reminder_interval); - /** * @brief Sets a reminder of the event in the calendar event handle. * * @remarks If reminder is set, the alarm will remind the event with in-house calendar application. * - * @param [in] event The calendar event handle + * @param [in] event The calendar event handle * @param [in] reminder_interval_type The reminder interval type * @param [in] reminder_interval The reminder interval * @@ -434,556 +563,825 @@ int calendar_event_get_reminder(calendar_event_h event, calendar_reminder_interv int calendar_event_set_reminder(calendar_event_h event, calendar_reminder_interval_type_e reminder_interval_type, int reminder_interval); /** - * @brief Gets the recurrence frequency of the event from the calendar event handle. + * @brief Gets the sound file path from the event handle. + * + * @remarks @a sound_file_path must be released with free() by you. + * + * @param[in] event The calendar event handle + * @param[out] sound_file_path The sound file path \n + * If @a sound_file_path does not exist, it is NULL + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_set_reminder_sound_file_path() + */ +int calendar_event_get_reminder_sound_file_path(calendar_event_h event, char **sound_file_path); + +/** + * @brief Sets the sound file path to the event handle. * - * @param[in] event The calendar event handle - * @param[out] recurrence_frequency The recurrence type of the event + * @param[in] event The calendar event handle + * @param[in] sound_file_path The sound file path to set * * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_get_reminder_sound_file_path() + */ +int calendar_event_set_reminder_sound_file_path(calendar_event_h event, const char *sound_file_path); + +/** + * @brief Creates a attendee handle and make adds it to the calendar event. + * + * @remarks The created handle is not added to calendar database until calendar_event_insert_to_db() is called + * + * @param[in] event The calendar event handle + * @param[out] attendee A new attendee handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_remove_attendee() + * @see calendar_attendee_set_name() + * @see calendar_attendee_set_email() + * @see calendar_attendee_set_phone_number() + * @see calendar_event_get_attendee_iterator() + */ +int calendar_event_add_attendee(calendar_event_h event, calendar_attendee_h* attendee); + +/** + * @brief Creates a attendee handle with contact ID and adds it to the calendar event. + * + * @details Adds an existing contact as an attendee to an event. A new attendee record is created, and the name, email address and phone number are populated from the values in the contact record. + * @remarks The created handle is not added to calendar database until calendar_event_insert_to_db() is called + * + * + * @param[in] event The calendar event handle + * @param[in] contact_db_id The contact DB ID which is related to attendee + * @param[out] attendee A new attendee handle from contact ID in the contacts database + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @pre This function requires an open connection to Contacts Service by contacts_connect(). + * + * @see calendar_event_remove_attendee() + * @see calendar_attendee_set_name() + * @see calendar_attendee_set_email() + * @see calendar_attendee_set_phone_number() + * @see calendar_event_get_attendee_iterator() + * @see contact_get_db_id() + * @see contact_get_from_db() + * @see calendar_attendee_get_phone_number() + */ +int calendar_event_add_attendee_with_contact(calendar_event_h event, int contact_db_id, calendar_attendee_h* attendee); + +/** + * @brief Removes the attendee from the calendar event handle. + * + * + * @param[in] event The calendar event handle + * @param[in] attendee The attendee handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_add_attendee() + * @see calendar_event_get_attendee_iterator() + */ +int calendar_event_remove_attendee(calendar_event_h event, calendar_attendee_h attendee); + +/** + * @brief Gets the attendee iterator handle from the event handle. + * + * @param[in] event The calendar event handle + * @param[out] iterator The attendee iterator handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_attendee_iterator_has_next() + * @see calendar_attendee_iterator_next() + * + */ +int calendar_event_get_attendee_iterator(calendar_event_h event, calendar_attendee_iterator_h *iterator); + +/** + * @brief Gets the last modified time of the event handle. + * + * @param[in] event The calendar event handle + * @param[out] modified_time The last modified time of event \n + * The @a modified_time is a unix timestamp since 00:00, Jan 1 1970 UTC. + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_NO_DATA Data not found + * + * @see calendar_event_insert_to_db() + * @see calendar_event_update_to_db() + */ +int calendar_event_get_last_modified_time(calendar_event_h event, long long int *modified_time); + +/** + * @brief Gets the visibility for the given calendar event handle. + * + * @param[in] event The calendar event handle + * @param[out] visibility The visibility of the event \n (default : #CALENDAR_VISIBILITY_PUBLIC) + * + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_set_recurrence_frequency() - * @see calendar_event_set_recurrence_week_flag() - * @see calendar_event_get_recurrence_week_flag() - * @see calendar_event_add_recurrence_exception_date() + * @see calendar_event_set_visibility() */ -int calendar_event_get_recurrence_frequency(calendar_event_h event, calendar_recurrence_frequency_e *recurrence_frequency); +int calendar_event_get_visibility(calendar_event_h event, calendar_visibility_e *visibility); +/** + * @brief Sets the visibility for the given calendar event handle. + * + * @param[in] event The calendar event handle + * @param[in] visibility The visibility of the event + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_get_visibility() + */ +int calendar_event_set_visibility(calendar_event_h event, calendar_visibility_e visibility); /** - * @brief Sets a recurrence frequency of the event in the calendar event handle. + * @brief Gets the category for the given calendar event handle. + * @remarks @a categories must be released with free() by you. * - * @param [in] event The calendar event handle - * @param [in] recurrence_frequency The recurrence frequency of the event \n - * If you set it to #CALENDAR_RECURRENCE_WEEKLY, you have to set calendar_event_set_recurrence_week_flag(). + * @param[in] event The calendar event handle + * @param[out] categories The category of the event \n Multiple categories are seperated by "," * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_get_recurrence_frequency() - * @see calendar_event_set_recurrence_week_flag() - * @see calendar_event_get_recurrence_week_flag() - * @see calendar_event_add_recurrence_exception_date() + * @see calendar_event_set_categories() */ -int calendar_event_set_recurrence_frequency(calendar_event_h event, calendar_recurrence_frequency_e recurrence_frequency); +int calendar_event_get_categories(calendar_event_h event, char **categories); /** - * @brief Gets the recurrence frequency of the event in the calendar event handle. + * @brief Sets the category for the given calendar event handle. * - * @remarks This function is valid only if recurrence frequency of the event is #CALENDAR_RECURRENCE_WEEKLY. + * @param[in] event The calendar event handle + * @param[in] categories The category of the event \n Multiple categories are seperated by "," * - * @param[in] event The calendar event handle - * @param[out] week_flag The days of week flag of the event \n It supports "OR"ing combination of #calendar_week_flag_e. \n eg) #CALENDAR_WEEK_FLAG_TUE | #CALENDAR_WEEK_FLAG_FRI + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @return 0 on success, otherwise a negative error value. + * @see calendar_event_get_categories() + */ +int calendar_event_set_categories(calendar_event_h event, const char *categories); + +/** + * @brief Gets the status for the given calendar event handle. + * + * @param[in] event The calendar event handle + * @param[out] status The status of the event \n (default : #CALENDAR_EVENT_STATUS_NONE) + * + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_set_recurrence_week_flag() - * @see calendar_event_set_recurrence_frequency() - * @see calendar_event_get_recurrence_frequency() + * @see calendar_event_set_status() */ -int calendar_event_get_recurrence_week_flag(calendar_event_h event, int *week_flag); +int calendar_event_get_status(calendar_event_h event, calendar_event_status_e *status); /** - * @brief Sets the days of week flag to the calendar event handle. + * @brief Sets a status for the given calendar event handle. + * + * @param[in] event The calendar event handle + * @param[in] status The status of the event + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @remarks This function is valid only if recurrence frequency of the event is #CALENDAR_RECURRENCE_WEEKLY. + * @see calendar_event_get_status() + */ +int calendar_event_set_status(calendar_event_h event, calendar_event_status_e status); + +/** + * @brief Gets the busy status for the given calendar event handle. * - * @param[in] event The calendar event handle - * @param[in] week_flag The days of week flag of the event \n It supports "OR"ing combination of #calendar_week_flag_e. \n eg) #CALENDAR_WEEK_FLAG_TUE | #CALENDAR_WEEK_FLAG_FRI + * @param[in] event The calendar event handle + * @param[out] busy_status The busy status of the event \n (default : #CALENDAR_EVENT_BUSY_STATUS_FREE) * - * @return 0 on success, otherwise a negative error value. + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_get_recurrence_week_flag() - * @see calendar_event_set_recurrence_frequency() - * @see calendar_event_get_recurrence_frequency() + * @see calendar_event_set_busy_status() + */ +int calendar_event_get_busy_status(calendar_event_h event, calendar_event_busy_status_e *busy_status); + +/** + * @brief Sets a busy status for the given calendar event handle. * + * @param[in] event The calendar event handle + * @param[in] busy_status The busy status of the event + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_get_busy_status() */ -int calendar_event_set_recurrence_week_flag(calendar_event_h event, int week_flag); +int calendar_event_set_busy_status(calendar_event_h event, calendar_event_busy_status_e busy_status); /** - * @brief Gets the recurrence ending time of the event from the calendar event handle. - * @details If recurrence frequency of the event is activated, then @a recurrence_until_date indicates recurrence ending time. + * @brief Gets the priority for the given calendar event handle. + * + * @param[in] event The calendar event handle + * @param[out] priority The priority of the event \n (default : #CALENDAR_EVENT_PRIORITY_LOW) + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_set_priority() + */ +int calendar_event_get_priority(calendar_event_h event, calendar_event_priority_e *priority); + +/** + * @brief Sets a priority for the given calendar event handle. + * + * @param[in] todo The calendar event handle + * @param[in] priority The priority of the event + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_get_priority() + */ +int calendar_event_set_priority(calendar_event_h event, calendar_event_priority_e priority); + +/** + * @brief Gets the UID of the event from the calendar event handle. + * + * @remarks @a uid must be released with free() by you. * - * @param [in] event The calendar event handle - * @param [out] recurrence_until_date The ending time of the recurrence event + * @param [in] event The calendar event handle + * @param [out] uid The UID of the event \n If the uid does not exist, it is NULL * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_NO_DATA Data not found * - * @see calendar_event_set_recurrence_until_date() + * @see calendar_event_set_uid() */ -int calendar_event_get_recurrence_until_date(calendar_event_h event, struct tm *recurrence_until_date); - +int calendar_event_get_uid(calendar_event_h event, char **uid); /** - * @brief Sets a recurrence end time of the event in the calendar event handle. + * @brief Sets a UID of the event in the calendar event handle. * - * @param [in] event The calendar event handle - * @param [in] recurrence_until_date The end time of the recurrence event + * @param [in] event The calendar event handle + * @param [in] uid The UID of the event * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @pre @a event has a recurrence frequency property using calendar_event_set_recurrence_frequency(). - * - * @see calendar_event_get_recurrence_until_date() + * @see calendar_event_get_uid() */ -int calendar_event_set_recurrence_until_date(calendar_event_h event, struct tm recurrence_until_date); +int calendar_event_set_uid(calendar_event_h event, const char *uid); /** - * @brief Adds a recurrence exception date to the calendar event handle. + * @brief Gets the timezone details for the given calendar event handle. * - * @param[in] event The calendar event handle - * @param[in] year The year of date \n It has to be more than 1900 - * @param[in] month The month of date [1-12] - * @param[in] day The day of date [1-31] + * @remark @a timezone_name must be released with free() by you. + * + * @param[in] event The calendar event handle + * @param[out] timezone_name The time zone name * * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_set_recurrence_frequency() - * @see calendar_event_get_recurrence_exception_iterator() + * @see calendar_foreach_timezone() + * @see calendar_event_set_timezone() */ -int calendar_event_add_recurrence_exception_date(calendar_event_h event, int year, int month, int day); - +int calendar_event_get_timezone(calendar_event_h event, char** timezone_name); /** - * @brief Gets the recurrence exception iterator handle from the event handle. + * @brief Sets a timezone for the given calendar event handle. * - * @param[in] event The calendar event handle - * @param[out] iterator The recurrence exception iterator handle \n If the iterator does not exist, it is NULL + * @param[in] event The calendar event handle + * @param[in] timezone_name The time zone name * * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_recurrence_exception_has_next() - * @see calendar_recurrence_exception_next() + * @see calendar_foreach_timezone() + * @see calendar_event_get_timezone() */ -int calendar_event_get_recurrence_exception_iterator(calendar_event_h event, calendar_recurrence_exception_iterator_h *iterator); +int calendar_event_set_timezone(calendar_event_h event, const char* timezone_name); /** - * @brief Checks whether there is a next recurrence exception handle on the list. + * @brief Gets events as array from vCalendar * - * @param [in] iterator The recurrence exception iterator handle + * @remarks @a event_array must be released with calendar_event_free_event_array() by you. * - * @return @c true If the next element exists or @c false If the next element doesn't exist + * @param[in] vcalendar_stream The vCalendar stream to convert + * @param[out] event_array The event array + * @param[out] length The length of the event array * - * @see calendar_event_get_recurrence_exception_iterator() - * @see calendar_recurrence_exception_next() + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory + * + * @see calendar_event_free_event_array() + * @see calendar_event_get_vcalendar_from_db() */ -bool calendar_recurrence_exception_has_next(calendar_recurrence_exception_iterator_h iterator); +int calendar_event_get_event_array_from_vcalendar(const char *vcalendar_stream, calendar_event_h **event_array, int *length); /** - * @brief Moves recurrence exception list iterator to the next position and gets recurrence exception date. - * @details If the next element for the current recurrence exception list exists, then the iterator is moved to - * the next position on the list and the recurrence exception handle for this position is returned. - * When the iterator reaches the last element of the list, all further calls will return - * #CALENDAR_ERROR_ITERATOR_END and @a recurrence exception will remain unchanged. + * @brief Gets vCalendar with event database ID from the calendar database * - * @param [in] iterator The recurrent exception iterator handle - * @param [out] year The year of date \n It is supposed to be more than 1900 - * @param [out] month The month of date [1-12] - * @param [out] day The day of date [1-31] + * @remarks @a vcalendar_stream must be released with free() by you. * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_ITERATOR_END Iterator is on the last position + * @param[in] event_db_id_array The event database ID array + * @param[in] length Length of event database ID array + * @param[out] vcalendar_stream The vCalendar stream to convert + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_get_recurrence_exception_iterator() - * @see calendar_recurrence_exception_has_next() + * @see calendar_connect() + * @see calendar_event_get_event_array_from_vcalendar() */ -int calendar_recurrence_exception_next(calendar_recurrence_exception_iterator_h *iterator, int* year, int* month, int* day); +int calendar_event_get_vcalendar_from_db(int *event_db_id_array, int length, char **vcalendar_stream); /** - * @brief Gets the start time of the event from the calendar event handle. + * @brief Gets information whether an event is recurrence or not. * - * @param [in] event The calendar event handle - * @param [out] start_time The start date of the event + * @param [in] event The calendar event handle + * @param [out] is_recurrence @c true if the event is recurrence event, otherwise @c false \n + * (default : @c false) * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_NO_DATA Data not found * - * @see calendar_event_set_start_time() + * @see calendar_event_set_recurrence_frequency() */ -int calendar_event_get_start_time(calendar_event_h event, struct tm *start_time); +int calendar_event_get_is_recurrence(calendar_event_h event, bool *is_recurrence); +/** + * @brief Gets the recurrence frequency of the event from the calendar event handle. + * + * @param[in] event The calendar event handle + * @param[out] recurrence_frequency The recurrence frequency of the event + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_set_recurrence_frequency() + * @see calendar_event_set_recurrence_byday() + * @see calendar_event_get_recurrence_byday() + */ +int calendar_event_get_recurrence_frequency(calendar_event_h event, calendar_recurrence_frequency_e *recurrence_frequency); /** - * @brief Sets a start time of the event in the calendar event handle. + * @brief Sets a recurrence frequency of the event to the calendar event handle. * - * @param [in] event The calendar event handle - * @param [in] start_time The start date of the event + * @param [in] event The calendar event handle + * @param [in] recurrence_frequency The recurrence frequency of the event \n + * If you set it to #CALENDAR_RECURRENCE_WEEKLY, you have to set calendar_event_set_recurrence_byday(). * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_get_start_time() + * @see calendar_event_get_recurrence_frequency() + * @see calendar_event_set_recurrence_byday() + * @see calendar_event_get_recurrence_byday() */ -int calendar_event_set_start_time(calendar_event_h event, struct tm start_time); +int calendar_event_set_recurrence_frequency(calendar_event_h event, calendar_recurrence_frequency_e recurrence_frequency); +/** + * @brief Gets the recurrence interval of the event from the calendar event handle. + * + * @param[in] event The calendar event handle + * @param[out] recurrence_interval The recurrence interval of the event + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_set_recurrence_interval() + * @see calendar_event_get_recurrence_frequency() + */ +int calendar_event_get_recurrence_interval(calendar_event_h event, int *recurrence_interval); /** - * @brief Gets the end time of the event from the calendar event handle. + * @brief Sets a recurrence interval of the event in the calendar event handle. * - * @param [in] event The calendar event handle - * @param [out] end_time The end date of the event + * @param [in] event The calendar event handle + * @param [in] recurrence_interval The recurrence interval of the event * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_NO_DATA Data not found * - * @see calendar_event_set_end_time() + * @see calendar_event_get_recurrence_interval() + * @see calendar_event_set_recurrence_frequency() */ -int calendar_event_get_end_time(calendar_event_h event, struct tm *end_time); - +int calendar_event_set_recurrence_interval(calendar_event_h event, int recurrence_interval); /** - * @brief Sets the end time of the event in the calendar event handle. + * @brief Gets the recurrence count of the event from the calendar event handle. * - * @param[in] event The calendar event handle - * @param[in] end_time The end date of the event + * @param[in] event The calendar event handle + * @param[out] recurrence_count The recurrence type of the event * - * @return 0 on success, otherwise a negative error value. + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_get_end_time() + * @see calendar_event_set_recurrence_count() + * @see calendar_event_get_recurrence_frequency() */ -int calendar_event_set_end_time(calendar_event_h event, struct tm end_time); +int calendar_event_get_recurrence_count(calendar_event_h event, int *recurrence_count); /** - * @brief Gets the total number of events from the calendar database. - * @pre This function requires an open connection to the calendar service by calendar_connect(). + * @brief Sets a recurrence count of the event to the calendar event handle. * - * @param[out] count The total number of events + * @param [in] event The calendar event handle + * @param [in] recurrence_count The recurrence count of the event * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_connect() + * @see calendar_event_get_recurrence_count() + * @see calendar_event_set_recurrence_frequency() */ -int calendar_event_get_total_count_from_db(int *count); +int calendar_event_set_recurrence_count(calendar_event_h event, int recurrence_count); /** - * @brief Creates a attendee handle and make adds it to the calendar event. + * @brief Gets the recurrence ending time of the event from the calendar event handle. + * @details If recurrence frequency of the event is activated, then @a recurrence_until_date indicates recurrence ending time. * - * @remarks The created handle is not added to calendar database until calendar_event_insert_to_db() is called + * @param [in] event The calendar event handle + * @param [out] recurrence_until_date The ending time of the recurrence event \n + * The @a recurrence_until_date is a unix timestamp since 00:00, Jan 1 1970 UTC. * - * @param[in] event The calendar event handle - * @param[out] attendee A new attendee handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_NO_DATA Data not found * - * @see calendar_event_remove_attendee() - * @see calendar_attendee_set_name() - * @see calendar_attendee_set_email() - * @see calendar_attendee_set_phone_number() - * @see calendar_event_get_attendee_iterator() + * @see calendar_event_set_recurrence_until_date() */ -int calendar_event_add_attendee(calendar_event_h event, calendar_attendee_h* attendee); +int calendar_event_get_recurrence_until_date(calendar_event_h event, long long int *recurrence_until_date); /** - * @brief Creates a attendee handle with contact ID and adds it to the calendar event. - * - * @details Adds an existing contact as an attendee to an event. A new attendee record is created, and the name, email address and phone number are populated from the values in the contact record. - * @remarks The created handle is not added to calendar database until calendar_event_insert_to_db() is called + * @brief Sets a recurrence end time of the event in the calendar event handle. * + * @param [in] event The calendar event handle + * @param [in] recurrence_until_date The end time of the recurrence event \n + * The @a recurrence_until_date is a unix timestamp since 00:00, Jan 1 1970 UTC. * - * @param[in] event The calendar event handle - * @param[in] contact_db_id The contact DB ID which is related to attendee - * @param[out] attendee A new attendee handle from contact ID in the contacts database * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @pre This function requires an open connection to Contacts Service by contacts_connect(). + * @pre @a event has a recurrence frequency property using calendar_event_set_recurrence_frequency(). * - * @see calendar_event_remove_attendee() - * @see calendar_attendee_set_name() - * @see calendar_attendee_set_email() - * @see calendar_attendee_set_phone_number() - * @see calendar_event_get_attendee_iterator() - * @see contact_get_db_id() - * @see contact_get_from_db() - * @see calendar_attendee_get_phone_number() + * @see calendar_event_get_recurrence_until_date() */ -int calendar_event_add_attendee_with_contact(calendar_event_h event, int contact_db_id, calendar_attendee_h* attendee); +int calendar_event_set_recurrence_until_date(calendar_event_h event, long long int recurrence_until_date); /** - * @brief Removes the attendee from the calendar event handle. - * + * @brief Gets the recurrence ending date for all day event + * @details If recurrence frequency of the event is activated, then @a recurrence_until_date indicates recurrence ending time. * - * @param[in] event The calendar event handle - * @param[in] attendee The attendee handle + * @param [in] event The calendar event handle + * @param [out] until_year Year of until date + * @param [out] until_month Month of until date + * @param [out] until_day Day of until date * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_NO_DATA Data not found * - * @see calendar_event_add_attendee() - * @see calendar_event_get_attendee_iterator() + * @see calendar_event_set_all_day_recurrence_until_date() */ -int calendar_event_remove_attendee(calendar_event_h event, calendar_attendee_h attendee); +int calendar_event_get_all_day_recurrence_until_date(calendar_event_h event, int *until_year, int *until_month, int *until_day); /** - * @brief Gets the attendee iterator handle from the event handle. + * @brief Sets a recurrence end date for all day event * - * @param[in] event The calendar event handle - * @param[out] iterator The attendee iterator handle + * @param [in] event The calendar event handle + * @param [in] until_year Year of until date + * @param [in] until_month Month of until date + * @param [in] until_day Day of until date * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_attendee_iterator_has_next() - * @see calendar_attendee_iterator_next() + * @pre @a event has a recurrence frequency property using calendar_event_set_recurrence_frequency(). * + * @see calendar_event_get_all_day_recurrence_until_date() */ -int calendar_event_get_attendee_iterator(calendar_event_h event, calendar_attendee_iterator_h *iterator); +int calendar_event_set_all_day_recurrence_until_date(calendar_event_h event, int until_year, int until_month, int until_day); /** - * @brief Gets the last modified time of the event handle. + * @brief Gets the recurrence frequency of the event from the calendar event handle. + * @details This rule is "BYDAY" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @param[in] event The calendar event handle - * @param[out] modified_time The last modified time of event + * @remarks @a byday must be released with free() by you. * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_NO_DATA Data not found + * @param[in] event The calendar event handle + * @param[out] byday The "BYDAY" of the reccurrence event \n combination of [[-]1~5]MO, TU, WE, TH, FR, SA, SU with "," * - * @see calendar_event_insert_to_db() - * @see calendar_event_update_to_db() + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_set_recurrence_byday() + * @see calendar_event_set_recurrence_frequency() + * @see calendar_event_get_recurrence_frequency() */ -int calendar_event_get_last_modified_time(calendar_event_h event, struct tm *modified_time); +int calendar_event_get_recurrence_byday(calendar_event_h event, char **byday); /** - * @brief Gets the visibility for the given calendar event handle. + * @brief Sets the days of week flag to the calendar event handle. + * @details This rule is "BYDAY" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @param[in] event The calendar event handle - * @param[out] visibility The visibility of the event \n (default : #CALENDAR_VISIBILITY_PUBLIC) + * @param[in] event The calendar event handle + * @param[in] byday The "BYDAY" of the reccurrence event \n combination of [[-]1~5]MO, TU, WE, TH, FR, SA, SU with "," * - * @return 0 on success, otherwise a negative error value. + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_set_visibility() + * @see calendar_event_get_recurrence_byday() + * @see calendar_event_set_recurrence_frequency() + * @see calendar_event_get_recurrence_frequency() */ -int calendar_event_get_visibility(calendar_event_h event, calendar_visibility_e *visibility); +int calendar_event_set_recurrence_byday(calendar_event_h event, const char* byday); /** - * @brief Sets a visibility for the given calendar event handle. + * @brief Gets the recurrence position flag of the event from the calendar event handle. + * @details This rule is "BYSETPOS" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @param[in] event The calendar event handle - * @param[in] visibility The visibility of the event + * @remarks @a bysetpos must be released with free() by you. * - * @return 0 on success, otherwise a negative error value. + * @param[in] event The calendar event handle + * @param[out] bysetpos The "BYSETPOS" of the reccurrence event \n combination of 1 to 366 or -366 to -1 with "," + * + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_get_visibility() + * @see calendar_event_set_recurrence_bysetpos() */ -int calendar_event_set_visibility(calendar_event_h event, calendar_visibility_e visibility); +int calendar_event_get_recurrence_bysetpos(calendar_event_h event, char **bysetpos); /** - * @brief Gets the timezone details for the given calendar event handle. + * @brief Sets a recurrence position flag of the event to the calendar event handle. + * @details This rule is "BYSETPOS" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @remark @a timezone_name must be released with free() by you. + * @param[in] event The calendar event handle + * @param[in] bysetpos The "BYSETPOS" of the reccurrence event \n combination of 1 to 366 or -366 to -1 with "," * - * @param[in] event The calendar event handle - * @param[out] timezone_name The time zone name + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @see calendar_event_get_recurrence_bysetpos() + */ +int calendar_event_set_recurrence_bysetpos(calendar_event_h event, const char* bysetpos); + +/** + * @brief Gets a recurrence BYMONTHDAY of the event to the calendar event handle. + * @details This rule is "BYMONTHDAY" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @see calendar_foreach_timezone() - * @see calendar_event_set_timezone() + * @remarks @a bymonthday must be released with free() by you. + * + * @param[in] event The calendar event handle + * @param[out] bymonthday The BYMONTHDAY of the reccurrence event \n combination of 1 to 31 or -31 to -1 with "," + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter */ -int calendar_event_get_timezone(calendar_event_h event, char** timezone_name); +int calendar_event_get_recurrence_bymonthday(calendar_event_h event, char **bymonthday); /** - * @brief Sets a timezone for the given calendar event handle. + * @brief Sets a recurrence BYMONTHDAY of the event to the calendar event handle. + * @details This rule is "BYMONTHDAY" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @param[in] event The calendar event handle - * @param[in] timezone_name The time zone name + * @param[in] event The calendar event handle + * @param[in] bymonthday The BYMONTHDAY of the reccurrence event \n combination of 1 to 31 or -31 to -1 with "," * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + */ +int calendar_event_set_recurrence_bymonthday(calendar_event_h event, const char* bymonthday); + +/** + * @brief Gets a recurrence BYMONTH of the event to the calendar event handle. + * @details This rule is "BYMONTH" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @see calendar_foreach_timezone() - * @see calendar_event_get_timezone() + * @remarks @a bymonth must be released with free() by you. + * + * @param[in] event The calendar event handle + * @param[out] bymonth The BYMONTH of the reccurrence event \n combination of 1 to 12 with "," + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter */ -int calendar_event_set_timezone(calendar_event_h event, const char* timezone_name); +int calendar_event_get_recurrence_bymonth(calendar_event_h event, char** bymonth); /** - * @brief Gets an event from vCalendar and returns a new event handle. + * @brief Sets a recurrence BYMONTH of the event to the calendar event handle. + * @details This rule is "BYMONTH" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @remarks The new event handle must be released with calendar_event_destroy() by you. + * @param[in] event The calendar event handle + * @param[in] bymonth The BYMONTH of the reccurrence event \n combination of 1 to 12 with "," * - * @param[in] vcalendar_stream The vCalendar stream to convert - * @param[out] event The event handle + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + */ +int calendar_event_set_recurrence_bymonth(calendar_event_h event, const char* bymonth); + +/** + * @brief Gets the first day of the week. * - * @return 0 on success, otherwise a negative error value. + * @param[in] event The calendar event handle + * @param[out] week_start The first day of the week for the recurrence + * + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory * - * @see calendar_event_destroy() - * @see calendar_event_get_vcalendar_from_event() + * @see calendar_event_set_recurrence_week_start() */ -int calendar_event_get_from_vcalendar(const char *vcalendar_stream, calendar_event_h *event); +int calendar_event_get_recurrence_week_start(calendar_event_h event, calendar_week_flag_e *week_start); /** - * @brief Gets vCalendar from the event handle. - * - * @remarks @a vcalendar_stream must be released with free() by you. + * @brief Sets the first day of the week * - * @param[in] event The event handle - * @param[out] vcalendar_stream The vCalendar stream to convert + * @param[in] event The calendar event handle + * @param[in] week_start The first day of the week for the recurrence * - * @return 0 on success, otherwise a negative error value. + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_event_get_from_vcalendar() + * @see calendar_event_get_recurrence_week_start() */ -int calendar_event_get_vcalendar_from_event(calendar_event_h event, char **vcalendar_stream); +int calendar_event_set_recurrence_week_start(calendar_event_h event, calendar_week_flag_e week_start); /** - * @brief Retrieves all calendar events from all of calendars by invoking the given callback function iteratively. + * @brief Removes the recurrence event instance from the calendar database. * - * @param[in] callback The callback function to invoke - * @param[in] user_data The user data to be passed to the callback function + * @param[in] event_db_id The event database ID to delete + * @param[in] start_time The recurrence instance start time to delete * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_DB_FAILED No access to database * - * @pre This function requires an open connection to the calendar service by calendar_connect(). - * - * @post This function invokes calendar_foreach_query_event_cb(). + * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @see calendar_foreach_query_event_cb() + * @see calendar_connect() + * @see calendar_event_get_recurrence_exdate() */ -int calendar_foreach_event_from_db(calendar_foreach_query_event_cb callback, void *user_data); +int calendar_event_delete_recurrence_instance_from_db(int event_db_id, long long int start_time); /** - * @brief Retrieves all calendar events with the given calendar database ID. + * @brief Removes the recurrence all day event instance from the calendar database. * - * @param[in] callback The callback function to invoke - * @param[in] calendar_db_id The calendar database ID to filter \n - * 1 means the default calendar on the device - * @param[in] user_data The user data to be passed to the callback function + * @param[in] event_db_id The event database ID to delete + * @param[in] year The year of recurrence all instance + * @param[in] month The month of recurrence all instance + * @param[in] day The day of recurrence all instance * - * @return 0 on success, otherwise a negative error value. - * @retval #CALENDAR_ERROR_NONE Successful - * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_DB_FAILED No access to database * - * @pre This function requires an open connection to the calendar service by calendar_connect(). + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + * @see calendar_event_get_recurrence_exdate() + */ +int calendar_event_delete_recurrence_all_day_instance_from_db(int event_db_id, int year, int month, int day); + +/** + * @brief Gets a recurrence EXDATE of the event to the calendar event handle. + * @details This rule is "EXDATE" rule in RFC 5545 iCalendar http://http://www.ietf.org/rfc/rfc2445.txt * - * @post This function invokes calendar_foreach_query_event_cb(). + * @remarks @a exdate must be released with free() by you. * - * @see calendar_foreach_query_event_cb() - * @see calendar_foreach_event_from_db() - * @see calendar_query_event_by_description() - * @see calendar_query_event_by_location() - * @see calendar_query_event_by_period() + * @param[in] event The calendar event handle + * @param[out] exdate The EXDATE of the reccurrence event + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_delete_recurrence_instance_from_db() + * @see calendar_event_delete_recurrence_all_day_instance_from_db() */ -int calendar_query_event_by_calendar(calendar_foreach_query_event_cb callback, int calendar_db_id, void *user_data); +int calendar_event_get_recurrence_exdate(calendar_event_h event, char** exdate); /** - * @brief Retrieves all calendar events with the given subject. + * @brief Frees event array * - * @param[in] callback The callback function to invoke - * @param[in] calendar_db_id The calendar database ID to filter \n - * 1 means the default calendar on the device - * @param[in] subject_to_find The description to filter - * @param[in] user_data The user data to be passed to the callback function + * @param[out] event_array The event array * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_DB_FAILED No access to database * - * @pre This function requires an open connection to the calendar service by calendar_connect(). + * @see calendar_event_search_event_by_calendar_book() + */ +int calendar_event_free_event_array(calendar_event_h *event_array); + +/** + * @brief Frees modified event array * - * @post This function invokes calendar_foreach_query_event_cb(). + * @param[out] modified_event_array The modified event array * - * @see calendar_event_get_subject() - * @see calendar_event_set_subject() - * @see calendar_foreach_query_event_cb() - * @see calendar_query_event_by_calendar() - * @see calendar_query_event_by_description() - * @see calendar_query_event_by_location() - * @see calendar_query_event_by_period() + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_event_search_event_by_version() */ -int calendar_query_event_by_subject(calendar_foreach_query_event_cb callback, int calendar_db_id, const char *subject_to_find, void *user_data); +int calendar_event_free_modified_event_array(pcalendar_modified_event_s *modified_event_array); /** - * @brief Retrieves all calendar events with the given description. + * @brief Retrieves all events as array from calendar book * - * @param[in] callback The callback function to invoke - * @param[in] calendar_db_id The calendar database ID to filter \n - * 1 means the default calendar on the device - * @param[in] description_to_find The description to filter - * @param[in] user_data The user data to be passed to the callback function + * @remarks @a event_array must be released with calendar_event_free_event_array() by you. + * + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_EVENT_CALENDAR_BOOK_DB_ID means the default event calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[out] event_array The event array + * @param[out] length The length of the event array * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * @retval #CALENDAR_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @post This function invokes calendar_foreach_query_event_cb(). - * - * @see calendar_event_get_description() - * @see calendar_event_set_description() - * @see calendar_foreach_query_event_cb() - * @see calendar_query_event_by_calendar() - * @see calendar_query_event_by_subject() - * @see calendar_query_event_by_location() - * @see calendar_query_event_by_period() - * @see calendar_foreach_query_event_cb() + * @see calendar_connect() + * @see calendar_event_free_event_array() */ -int calendar_query_event_by_description(calendar_foreach_query_event_cb callback, int calendar_db_id, const char *description_to_find, void *user_data); +int calendar_event_search_event_by_calendar_book(int calendar_book_db_id, calendar_event_h **event_array, int *length); /** - * @brief Retrieves all calendar events with the given location. + * @brief Retrieves extend event instances within specified time range. + * + * @remarks @a event_array must be released with calendar_event_free_event_array() by you. * - * @param[in] callback The callback function to invoke - * @param[in] calendar_db_id The calendar database ID to filter \n - * 1 means the default calendar on the device - * @param[in] location_to_find The location to filter - * @param[in] user_data The user data to be passed to the callback function + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_EVENT_CALENDAR_BOOK_DB_ID means the default event calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[in] period_start_time The start of the time range\n + * The @a start_time is a unix timestamp since 00:00, Jan 1 1970 UTC. + * @param[in] period_end_time The end of the time range\n + * The @a end_time is a unix timestamp since 00:00, Jan 1 1970 UTC. + * @param[out] event_array The event array + * @param[out] length The length of the event array * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -992,27 +1390,29 @@ int calendar_query_event_by_description(calendar_foreach_query_event_cb callback * * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @post This function invokes calendar_foreach_query_event_cb(). - * - * @see calendar_event_get_location() - * @see calendar_event_set_location() - * @see calendar_foreach_query_event_cb() - * @see calendar_query_event_by_calendar() - * @see calendar_query_event_by_subject() - * @see calendar_query_event_by_description() - * @see calendar_query_event_by_period() + * @see calendar_connect() + * @see calendar_event_free_event_array() */ -int calendar_query_event_by_location(calendar_foreach_query_event_cb callback, int calendar_db_id, const char *location_to_find, void *user_data); +int calendar_event_search_extend_instance_by_period(int calendar_book_db_id, + long long int period_start_time, long long int period_end_time, + calendar_event_h **event_array, int *length); /** - * @brief Retrieves all calendar events between the given start_time and end_time. + * @brief Retrieves all day extend event instances within specified time range. * - * @param[in] callback The callback function to invoke - * @param[in] calendar_db_id The calendar database ID to filter \n - * 1 means the default calendar on the device - * @param[in] start_time The start date - * @param[in] end_time The end date - * @param[in] user_data The user data to be passed to the callback function + * @remarks @a event_array must be released with calendar_event_free_event_array() by you. + * + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_EVENT_CALENDAR_BOOK_DB_ID means the default event calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[in] period_start_year The start year of the time range + * @param[in] period_start_month The start month of the time range + * @param[in] period_start_day The start day of the time range + * @param[in] period_end_year The end year of the time range + * @param[in] period_end_month The end month of the time range + * @param[in] period_end_day The end day of the time range + * @param[out] event_array The event array + * @param[out] length The length of the event array * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1021,45 +1421,38 @@ int calendar_query_event_by_location(calendar_foreach_query_event_cb callback, i * * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @post This function invokes calendar_foreach_query_event_cb(). - * - * @see calendar_event_get_start_time() - * @see calendar_event_set_start_time() - * @see calendar_event_get_end_time() - * @see calendar_event_set_end_time() - * @see calendar_foreach_query_event_cb() - * @see calendar_query_event_by_calendar() - * @see calendar_query_event_by_subject() - * @see calendar_query_event_by_description() - * @see calendar_query_event_by_location() - * @see calendar_foreach_query_event_cb() - * + * @see calendar_connect() + * @see calendar_event_free_event_array() */ -int calendar_query_event_by_period(calendar_foreach_query_event_cb callback, int calendar_db_id, struct tm start_time, struct tm end_time, void *user_data); +int calendar_event_search_all_day_extend_instance_by_period(int calendar_book_db_id, + int period_start_year, int period_start_month, int period_start_day, + int period_end_year, int period_end_month, int period_end_day, + calendar_event_h **event_array, int *length); /** - * @brief Retrieves all calendar events that have been modified since the given time. - * @details This function will find all changed event since the given time + * @brief Retrieves all modified events information as array that have been modified since the given version. + * + * @remarks @a modified_event_array must be released with calendar_event_free_modified_event_array() by you. * - * @param[in] callback The callback function to invoke - * @param[in] calendar_db_id The calendar database ID to filter \n - * 1 means the default calendar on the device - * @param[in] time The time to find events which are changed since when - * @param[in] user_data The user data to be passed to the callback function + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_EVENT_CALENDAR_BOOK_DB_ID means the default event calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[in] calendar_db_version The calendar database version + * @param[out] modified_event_array The modified event information array + * @param[out] length The length of the event array * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * @retval #CALENDAR_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @post This function invokes calendar_foreach_query_event_cb(). - * - * @see calendar_event_get_last_modified_time() - * @see calendar_foreach_query_event_cb() + * @see calendar_connect() + * @see calendar_event_free_modified_event_array() */ -int calendar_query_event_by_time_last_modified(calendar_foreach_query_event_cb callback, int calendar_db_id, struct tm time, void *user_data); +int calendar_event_search_event_by_version(int calendar_book_db_id, int calendar_db_version, pcalendar_modified_event_s **modified_event_array, int *length); /** * @} @@ -1090,9 +1483,9 @@ int calendar_query_event_by_time_last_modified(calendar_foreach_query_event_cb c int calendar_todo_create(calendar_todo_h *todo); /** - * @brief Destroys the calendar to-do handle + * @brief Destroys the calendar to-do handle * - * @param[in] todo The calendar to-do handle + * @param[in] todo The calendar to-do handle * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1106,9 +1499,9 @@ int calendar_todo_destroy(calendar_todo_h todo); /** * @brief Adds the given to-do item to the calendar database. * - * @param[in] todo The calendar to-do handle - * @param[in] calendar_db_id The calendar database ID to which the event insert. \n - * 1 means the default calendar on the device + * @param[in] todo The calendar to-do handle + * @param[in] calendar_book_db_id The calendar book database ID to which the to-do insert. \n + * #DEFAULT_TODO_CALENDAR_BOOK_DB_ID means the default to-do calendar book on the device * @param[out] todo_db_id The to-do ID to be assigned to the to-do item * * @return 0 on success, otherwise a negative error value. @@ -1120,7 +1513,7 @@ int calendar_todo_destroy(calendar_todo_h todo); * @see calendar_todo_update_to_db() * */ -int calendar_todo_insert_to_db(calendar_todo_h todo, int calendar_db_id, int *todo_db_id); +int calendar_todo_insert_to_db(calendar_todo_h todo, int calendar_book_db_id, int *todo_db_id); /** * @brief Removes the to-do item from the calendar database. @@ -1142,7 +1535,7 @@ int calendar_todo_delete_from_db(int todo_id); * @brief Updates the to-do item on the calendar database. * @details calendar_todo_get_db_id() is called internally to update the to-do item in the calendar database. * - * @param[in] todo The calendar to-do handle + * @param[in] todo The calendar to-do handle * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1160,13 +1553,13 @@ int calendar_todo_update_to_db(calendar_todo_h todo); /** * @brief Gets the to-do item handle associated with the given to-do DB ID. - * @details This function gets the new to-do handle with the given to-do database ID from the calendar database. - * A new calendar to-do handle will be created. + * @details This function gets the new to-do handle with the given to-do database ID from the calendar database. + * A new calendar to-do handle will be created. * - * @remarks The new to-do handle must be released with calendar_todo_destroy() by you. + * @remarks The new to-do handle must be released with calendar_todo_destroy() by you. * * @param[in] todo_id The to-do Database ID - * @param[out] todo The calendar to-do handle + * @param[out] todo The calendar to-do handle * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1181,7 +1574,7 @@ int calendar_todo_update_to_db(calendar_todo_h todo); int calendar_todo_get_from_db(int todo_id, calendar_todo_h *todo); /** - * @brief Gets the database ID for the given calendar to-do handle. + * @brief Gets the database ID for the given calendar to-do handle. * * @param[in] todo The calendar to-do handle * @param[out] todo_db_id The database ID of the to-do item (default : 0) \n @@ -1197,11 +1590,11 @@ int calendar_todo_get_from_db(int todo_id, calendar_todo_h *todo); int calendar_todo_get_db_id(calendar_todo_h todo, int *todo_db_id); /** - * @brief Gets the calendar database ID associated with the given calendar to-do handle. + * @brief Gets The calendar book database ID associated with the given calendar to-do handle. * * @param[in] todo The calendar to-do handle - * @param[out] calendar_db_id The calendar database ID fetched from the calendar to-do handle (default : 0) \n - * 0 means the to-do is not in calendar database. + * @param[out] calendar_book_db_id The calendar book database ID fetched from the calendar to-do handle (default : 0) \n + * 0 means the to-do is not in calendar database. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1209,14 +1602,14 @@ int calendar_todo_get_db_id(calendar_todo_h todo, int *todo_db_id); * * @see calendar_todo_insert_to_db() */ -int calendar_todo_get_calendar_db_id(calendar_todo_h todo, int *calendar_db_id); +int calendar_todo_get_calendar_book_db_id(calendar_todo_h todo, int *calendar_book_db_id); /** * @brief Gets the subject of the to-do from the calendar to-do handle. * - * @remarks @a subject must be released with free() by you. + * @remarks @a subject must be released with free() by you. * - * @param [in] todo The calendar to-do handle + * @param [in] todo The calendar to-do handle * @param [out] subject The subject of the to-do \n If the subject does not exist, it is NULL * * @return 0 on success, otherwise a negative error value. @@ -1230,7 +1623,7 @@ int calendar_todo_get_subject(calendar_todo_h todo, char **subject); /** * @brief Sets a subject of the to-do handle. * - * @param [in] todo The calendar to-do handle + * @param [in] todo The calendar to-do handle * @param [in] subject The subject of the to-do * * @return 0 on success, otherwise a negative error value. @@ -1244,9 +1637,9 @@ int calendar_todo_set_subject(calendar_todo_h todo, const char *subject); /** * @brief Gets description of the to-do from the calendar to-do handle. * - * @remarks @a description must be released with free() by you. + * @remarks @a description must be released with free() by you. * - * @param [in] todo The calendar to-do handle + * @param [in] todo The calendar to-do handle * @param [out] description The description of the to-do \n If the description does not exist, it is NULL * * @return 0 on success, otherwise a negative error value. @@ -1260,7 +1653,7 @@ int calendar_todo_get_description(calendar_todo_h todo, char **description); /** * @brief Sets a description of the to-do in the calendar to-do handle. * - * @param [in] todo The calendar to-do handle + * @param [in] todo The calendar to-do handle * @param [in] description The description of the to-do * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1272,7 +1665,7 @@ int calendar_todo_get_description(calendar_todo_h todo, char **description); int calendar_todo_set_description(calendar_todo_h todo, const char *description); /** - * @brief Gets the priority for the given calendar to-do handle. + * @brief Gets the priority for the given calendar to-do handle. * * @param[in] todo The calendar to-do handle * @param[out] priority The priority of the to-do @@ -1286,7 +1679,7 @@ int calendar_todo_set_description(calendar_todo_h todo, const char *description) int calendar_todo_get_priority(calendar_todo_h todo, calendar_todo_priority_e *priority); /** - * @brief Sets a priority for the given calendar to-do handle. + * @brief Sets a priority for the given calendar to-do handle. * * @param[in] todo The calendar to-do handle * @param[in] priority The priority of the to-do @@ -1300,7 +1693,7 @@ int calendar_todo_get_priority(calendar_todo_h todo, calendar_todo_priority_e *p int calendar_todo_set_priority(calendar_todo_h todo, calendar_todo_priority_e priority); /** - * @brief Gets the status for the given calendar to-do handle. + * @brief Gets the status for the given calendar to-do handle. * * @param[in] todo The calendar to-do handle * @param[out] status The status of the to-do @@ -1309,12 +1702,12 @@ int calendar_todo_set_priority(calendar_todo_h todo, calendar_todo_priority_e pr * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_todo_set_status() + * @see calendar_todo_set_status() */ int calendar_todo_get_status(calendar_todo_h todo, calendar_todo_status_e *status); /** - * @brief Sets a status for the given calendar to-do handle. + * @brief Sets a status for the given calendar to-do handle. * * @param[in] todo The calendar to-do handle * @param[in] status The status of the to-do @@ -1328,7 +1721,7 @@ int calendar_todo_get_status(calendar_todo_h todo, calendar_todo_status_e *statu int calendar_todo_set_status(calendar_todo_h todo, calendar_todo_status_e status); /** - * @brief Gets the visibility for the given calendar to-do handle. + * @brief Gets the visibility for the given calendar to-do handle. * * @param[in] todo The calendar to-do handle * @param[out] visibility The visibility of the to-do \n (default : #CALENDAR_VISIBILITY_PUBLIC) @@ -1342,7 +1735,7 @@ int calendar_todo_set_status(calendar_todo_h todo, calendar_todo_status_e status int calendar_todo_get_visibility(calendar_todo_h todo, calendar_visibility_e *visibility); /** - * @brief Sets a visibility for the given calendar to-do handle. + * @brief Sets a visibility for the given calendar to-do handle. * * @param[in] todo The calendar to-do handle * @param[in] visibility The visibility of the to-do @@ -1358,9 +1751,9 @@ int calendar_todo_set_visibility(calendar_todo_h todo, calendar_visibility_e vis /** * @brief Gets the location of the to-do from the calendar to-do handle. * - * @remarks @a location must be released with free() by you. + * @remarks @a location must be released with free() by you. * - * @param [in] todo The calendar to-do handle + * @param [in] todo The calendar to-do handle * @param [out] location The location of the to-do \n If the location does not exist, it is NULL * * @return 0 on success, otherwise a negative error value. @@ -1375,7 +1768,7 @@ int calendar_todo_get_location(calendar_todo_h todo, char **location); /** * @brief Sets a location of the to-do in the calendar to-do handle. * - * @param [in] todo The calendar to-do handle + * @param [in] todo The calendar to-do handle * @param [in] location The location of the to-do * * @return 0 on success, otherwise a negative error value. @@ -1389,8 +1782,9 @@ int calendar_todo_set_location(calendar_todo_h todo, const char *location); /** * @brief Gets the last modified time of the to-do item. * - * @param[in] todo The calendar to-do handle - * @param[out] modified_time The last modified time + * @param[in] todo The calendar to-do handle + * @param[out] modified_time The last modified time\n + * The @a modified_time is a unix timestamp since 00:00, Jan 1 1970 UTC. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1401,9 +1795,9 @@ int calendar_todo_set_location(calendar_todo_h todo, const char *location); * @see calendar_todo_update_to_db() * */ -int calendar_todo_get_last_modified_time(calendar_todo_h todo, struct tm *modified_time); +int calendar_todo_get_last_modified_time(calendar_todo_h todo, long long int *modified_time); /** - * @brief Gets the timezone details for the given calendar to-do handle. + * @brief Gets the timezone details for the given calendar to-do handle. * @remarks @a timezone_name must be released with free() by you. * * @param[in] todo The calendar to-do handle @@ -1416,10 +1810,10 @@ int calendar_todo_get_last_modified_time(calendar_todo_h todo, struct tm *modifi * @see calendar_todo_set_timezone() * @see calendar_foreach_timezone() */ -int calendar_todo_get_timezone(calendar_todo_h todo, char** timezone_name); +int calendar_todo_get_timezone(calendar_todo_h todo, char** timezone_name); /** - * @brief Sets the timezone for the given calendar to-do handle. + * @brief Sets the timezone for the given calendar to-do handle. * * @param[in] todo The calendar to-do handle * @param[in] timezone_name The timezone name eg. Europe/Paris @@ -1431,13 +1825,14 @@ int calendar_todo_get_timezone(calendar_todo_h todo, char** timezone_name); * @see calendar_todo_get_timezone() * @see calendar_foreach_timezone() */ -int calendar_todo_set_timezone(calendar_todo_h todo, const char* timezone_name); +int calendar_todo_set_timezone(calendar_todo_h todo, const char* timezone_name); /** * @brief Gets the start time of the to-do from the calendar to-do handle. * - * @param [in] todo The calendar to-do handle - * @param [out] start_time The start date of the to-do + * @param [in] todo The calendar to-do handle + * @param [out] start_time The start date of the to-do\n + * The @a start_time is a unix timestamp since 00:00, Jan 1 1970 UTC. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1446,29 +1841,42 @@ int calendar_todo_set_timezone(calendar_todo_h todo, const char* timezone_name); * * @see calendar_todo_set_start_time() */ -int calendar_todo_get_start_time(calendar_todo_h todo, struct tm *start_time); +int calendar_todo_get_start_time(calendar_todo_h todo, long long int *start_time); /** - * @brief Sets a start time of the to-do in the calendar to-do handle. + * @brief Sets a start time of the to-do in the calendar to-do handle. * - * @param [in] todo The calendar todo handle - * @param [in] start_time The start date of the todo + * @param [in] todo The calendar todo handle + * @param [in] start_time The start date of the todo\n + * The @a start_time is a unix timestamp since 00:00, Jan 1 1970 UTC. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * * @see calendar_todo_get_start_time() - * */ -int calendar_todo_set_start_time(calendar_todo_h todo, struct tm start_time); +int calendar_todo_set_start_time(calendar_todo_h todo, long long int start_time); +/** + * @brief Unsets a start time of the to-do in the calendar to-do handle. + * + * @param [in] todo The calendar todo handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_todo_set_start_time() + */ +int calendar_todo_unset_start_time(calendar_todo_h todo); /** * @brief Gets the due time of the to-do from the calendar to-do handle. * - * @param [in] todo The calendar to-do handle - * @param [out] due_time The due date of the to-do + * @param [in] todo The calendar to-do handle + * @param [out] due_time The due date of the to-do\n + * The @a due_time is a unix timestamp since 00:00, Jan 1 1970 UTC. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1476,15 +1884,15 @@ int calendar_todo_set_start_time(calendar_todo_h todo, struct tm start_time); * @retval #CALENDAR_ERROR_NO_DATA Data not found * * @see calendar_todo_set_due_time() - * */ -int calendar_todo_get_due_time(calendar_todo_h todo, struct tm *due_time); +int calendar_todo_get_due_time(calendar_todo_h todo, long long int *due_time); /** * @brief Sets a due time of the to-do in the calendar to-do handle. * - * @param[in] todo The calendar to-do handle - * @param[in] due_time The due date of the to-do + * @param[in] todo The calendar to-do handle + * @param[in] due_time The due date of the to-do\n + * The @a due_time is a unix timestamp since 00:00, Jan 1 1970 UTC. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1492,47 +1900,182 @@ int calendar_todo_get_due_time(calendar_todo_h todo, struct tm *due_time); * * @see calendar_todo_get_due_time() */ -int calendar_todo_set_due_time(calendar_todo_h todo, struct tm due_time); +int calendar_todo_set_due_time(calendar_todo_h todo, long long int due_time); /** - * @brief Retrieves all to-do items by invoking the given callback function iteratively. + * @brief Unsets a due time of the to-do in the calendar to-do handle. * - * @param[in] callback The callback function to invoke - * @param[in] user_data The user data to be passed to the callback function + * @param[in] todo The calendar to-do handle * - * @return 0 on success, otherwise a negative error value. + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_todo_set_due_time() + */ +int calendar_todo_unset_due_time(calendar_todo_h todo); + +/** + * @brief Gets the total number of to-dos from the calendar book. + * + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_TODO_CALENDAR_BOOK_DB_ID means the default to-do calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[in] todo_priority The to-do priority(#calendar_todo_priority_e) to filter \n + * Supports "OR"ing of #calendar_todo_priority_e + * @param[in] todo_status The to-do status(#calendar_todo_status_e) to filter \n + * Supports "OR"ing of #calendar_todo_status_e + * @param[out] count The total number of to-dos + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + */ +int calendar_todo_get_total_count_from_db(int calendar_book_db_id, int todo_priority, int todo_status, int *count); + +/** + * @brief Gets the total number of to-dos within specified time range from the calendar book. + * + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_TODO_CALENDAR_BOOK_DB_ID means the default to-do calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[in] start_duedate_range The start of the time range\n + * The @a start_duedate_range is a unix timestamp since 00:00, Jan 1 1970 UTC. + * @param[in] end_duedate_range The end of the time range\n + * The @a end_duedate_range is a unix timestamp since 00:00, Jan 1 1970 UTC. + * @param[in] todo_priority The to-do priority(#calendar_todo_priority_e) to filter \n + * Supports "OR"ing of #calendar_todo_priority_e + * @param[in] todo_status The to-do status(#calendar_todo_status_e) to filter \n + * Supports "OR"ing of #calendar_todo_status_e + * @param[out] count The total number of to-dos + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CALENDAR_ERROR_DB_FAILED No access to database * * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @post This function invokes calendar_foreach_query_todo_cb(). + * @see calendar_connect() + */ +int calendar_todo_get_total_count_by_duedate_range(int calendar_book_db_id, long long int start_duedate_range, long long int end_duedate_range, int todo_priority, int todo_status, int *count); + +/** + * @brief Frees to-do array + * + * @param[out] todo_array The to-do array * - * @see calendar_foreach_query_todo_cb() + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_todo_search_todo_by_calendar_book() */ -int calendar_foreach_todo_from_db(calendar_foreach_query_todo_cb callback, void *user_data); +int calendar_todo_free_todo_array(calendar_todo_h *todo_array); /** - * @brief Retrieves all to-do items with the given calendar database ID by invoking the given callback function iteratively. + * @brief Frees modified to-do array * - * @param[in] callback The callback function to invoke - * @param[in] calendar_db_id The calendar database ID to filter \n - * 1 means the default calendar on the device - * @param[in] user_data The user data to be passed to the callback function + * @param[out] modified_todo_array The modified to-do array + * @param[out] length The length of the array * - * @return 0 on success, otherwise a negative error value. + * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * + * @see calendar_todo_search_todo_by_version() + */ +int calendar_todo_free_modified_todo_array(pcalendar_modified_todo_s *modified_todo_array); + +/** + * @brief Retrieves all to-dos as array from calendar book + * + * @remarks @a todo_array must be released with calendar_todo_free_todo_array() by you. + * + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_TODO_CALENDAR_BOOK_DB_ID means the default to-do calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[in] todo_priority The to-do priority(#calendar_todo_priority_e) to filter \n + * Supports "OR"ing of #calendar_todo_priority_e + * @param[in] todo_status The to-do status(#calendar_todo_status_e) to filter \n + * Supports "OR"ing of #calendar_todo_status_e + * @param[out] todo_array The to-do array + * @param[out] length The length of the to-do array + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @post This function invokes calendar_foreach_query_todo_cb(). + * @see calendar_connect() + * @see calendar_todo_free_todo_array() + */ +int calendar_todo_search_todo_by_calendar_book(int calendar_book_db_id, int todo_priority, int todo_status, calendar_todo_h **todo_array, int *length); + +/** + * @brief Retrieves all calendar to-dos as array within specified time range. + * + * @remarks @a todo_array must be released with calendar_todo_free_todo_array() by you. + * + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_TODO_CALENDAR_BOOK_DB_ID means the default to-do calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[in] start_duedate_range The start of the time range\n + * The @a start_duedate_range is a unix timestamp since 00:00, Jan 1 1970 UTC. + * @param[in] end_duedate_range The end of the time range\n + * The @a end_duedate_range is a unix timestamp since 00:00, Jan 1 1970 UTC. + * @param[in] todo_priority The to-do priority(#calendar_todo_priority_e) to filter \n + * Supports "OR"ing of #calendar_todo_priority_e + * @param[in] todo_status The to-do status(#calendar_todo_status_e) to filter \n + * Supports "OR"ing of #calendar_todo_status_e + * @param[out] todo_array The to-do array + * @param[out] length The length of the todo array + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_DB_FAILED Database operation failure + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @see calendar_foreach_query_todo_cb() + * @see calendar_connect() + * @see calendar_todo_free_todo_array() */ -int calendar_query_todo_by_calendar(calendar_foreach_query_todo_cb callback, int calendar_db_id, void *user_data); +int calendar_todo_search_todo_by_duedate_range(int calendar_book_db_id, long long int start_duedate_range, long long int end_duedate_range, int todo_priority, int todo_status, calendar_todo_h **todo_array, int *length); + +/** + * @brief Retrieves all modified to-dos information as array that have been modified since the given version. + * + * @remarks @a modified_todo_array must be released with calendar_todo_free_modified_todo_array() by you. + * + * @param[in] calendar_book_db_id The calendar book database ID to filter \n + * #DEFAULT_TODO_CALENDAR_BOOK_DB_ID means the default to-do calendar book on the device \n + * #CALENDAR_BOOK_FILTER_ALL means all calendar books on the device + * @param[in] calendar_db_version The calendar database version + * @param[out] modified_todo_array The modified to-do information array + * @param[out] length The length of the to-do array + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_DB_FAILED Database operation failure + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + * @see calendar_todo_free_modified_todo_array() + */ +int calendar_todo_search_todo_by_version(int calendar_book_db_id, int calendar_db_version, pcalendar_modified_todo_s **modified_todo_array, int *length); /** * @} @@ -1544,14 +2087,44 @@ int calendar_query_todo_by_calendar(calendar_foreach_query_todo_cb callback, int */ /** - * @brief Gets the calendar from the calendar database. - * @details This function gets the new calendar handle with the given calendar database ID from the calendar database. \n - * The new calendar handle will be created. + * @brief Creates a handle to the calendar book. + * @remarks The calendar book handle must be released with calendar_book_destroy() by you. + * @remarks The created handle is not added to calendar database until calendar_insert_to_db() is called + * + * @param[out] calendar_book A new handle to calendar book + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory + * + * @see calendar_book_destroy() + * + */ +int calendar_book_create(calendar_book_h *calendar_book); + +/** + * @brief Destroys the calendar book handle and releases all its resources. * - * @remarks The created calendar handle must be released with calendar_destroy() by you. + * @param[out] calendar_book The calendar book handle * - * @param[in] calendar_db_id The calendar database ID - * @param[out] calendar The calendar handle associated with the calendar database ID + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_get_from_db() + */ +int calendar_book_destroy(calendar_book_h calendar_book); + +/** + * @brief Gets the calendar book from the calendar database. + * @details This function gets the new calendar book handle with the given calendar book database ID from the calendar database. \n + * The new calendar book handle will be created. + * + * @remarks The created calendar book handle must be released with calendar_book_destroy() by you. + * + * @param[in] calendar_book_db_id The calendar book database ID + * @param[out] calendar_book The calendar book handle associated with The calendar book database ID * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1560,110 +2133,289 @@ int calendar_query_todo_by_calendar(calendar_foreach_query_todo_cb callback, int * * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @see calendar_destroy() + * @see calendar_book_destroy() + */ +int calendar_book_get_from_db(int calendar_book_db_id, calendar_book_h *calendar_book); + +/** + * @brief Adds a calendar book to the calendar database. + * + * @param[in] calendar_book The calendar book handle + * @param[out] calendar_book_db_id The calendar book database ID associated with the calendar book \n + * If the function fails, it is -1. + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + * @see calendar_book_delete_from_db() + */ +int calendar_book_insert_to_db(calendar_book_h calendar_book, int *calendar_book_db_id); + +/** + * @brief Updates a calendar book to the calendar database. + * + * @param[in] calendar_book The calendar book handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_book_connect() */ -int calendar_get_from_db(int calendar_db_id, calendar_h *calendar); +int calendar_book_update_to_db(calendar_book_h calendar_book); /** - * @brief Destroys the calendar handle and releases all its resources. + * @brief Removes the calendar book from the calendar database. * - * @param[out] calendar The calendar handle + * @param[in] calendar_book_db_id The calendar book database ID to delete + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + */ +int calendar_book_delete_from_db(int calendar_book_db_id); + +/** + * @brief Removes the calendar books, events and to-dos from the calendar database. + * + * @param[in] account_db_id The account database ID to filter + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + */ +int calendar_book_delete_all_by_account(int account_db_id); + +/** + * @brief Gets the calendar book database ID associated with the given calendar book handle. + * + * @param[in] calendar_book The calendar book handle + * @param[out] calendar_book_db_id The calendar book database ID fetched from the calendar book handle * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_get_from_db() + * @see calendar_book_get_from_db() + */ +int calendar_book_get_db_id(calendar_book_h calendar_book, int *calendar_book_db_id); + +/** + * @brief Sets the calendar book type associated with the given calendar book handle. + * + * @param[in] calendar_book The calendar book handle + * @param[in] calendar_book_type The calendar book type. \n Supports "OR"ing of #calendar_book_type_e + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * + * @see calendar_book_get_type() */ -int calendar_destroy(calendar_h calendar); +int calendar_book_set_type(calendar_book_h calendar_book, int calendar_book_type); /** - * @brief Gets the database ID associated with the given calendar handle. + * @brief Gets the calendar book type associated with the given calendar book handle. * - * @param[in] calendar The calendar handle - * @param[out] calendar_db_id The calendar database ID fetched from the calendar handle + * @param[in] calendar_book The calendar book handle + * @param[out] calendar_book_type The calendar book type. \n Supports "OR"ing of #calendar_book_type_e * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter * - * @see calendar_get_from_db() + * @see calendar_book_set_type() */ -int calendar_get_db_id(calendar_h calendar, int *calendar_db_id); +int calendar_book_get_type(calendar_book_h calendar_book, int *calendar_book_type); /** - * @brief Gets the status whether the calendar is default calendar is or not in the device. + * @brief Gets the status whether the calendar book is default calendar book is or not in the device. * - * @param [in] calendar The calendar handle - * @param [out] is_default @c true if the calendar is the default calendar in the device @c false \n + * @param [in] calendar_book The calendar book handle + * @param [out] is_default @c true if the calendar is the default calendar book in the device @c false \n * (default : @c false) * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter */ -int calendar_get_is_default(calendar_h calendar, bool *is_default); +int calendar_book_get_is_default(calendar_book_h calendar_book, bool *is_default); /** - * @brief Gets the name of the calendar from the calendar handle. + * @brief Sets the name of the calendar from the calendar book handle. * - * @remarks @a calendar_name must be released with free() by you. + * @remarks @a calendar_name must be released with free() by you. * - * @param [in] calendar The calendar handle - * @param [out] calendar_name The name of the calendar \n If the name does not exist, it is NULL + * @param [in] calendar_book The calendar book handle + * @param [in] calendar_book_name The name of the calendar book * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_get_name() + */ +int calendar_book_set_name(calendar_book_h calendar_book, const char *calendar_book_name); + +/** + * @brief Gets the name of the calendar book from the calendar book handle. + * + * @remarks @a calendar_book_name must be released with free() by you. + * + * @param [in] calendar_book The calendar book handle + * @param [out] calendar_book_name The name of the calendar book \n If the name does not exist, it is NULL + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_set_name() + */ +int calendar_book_get_name(calendar_book_h calendar_book, char **calendar_book_name); + +/** + * @brief Sets the visible status of the calendar book handle. + * + * @param [in] calendar_book The calendar book handle + * @param [in] is_visible @c true if the calendar book is visible in the device, otherwise @c false \n + * (default : @c false) + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_get_is_visibile() */ -int calendar_get_name(calendar_h calendar, char **calendar_name); +int calendar_book_set_is_visible(calendar_book_h calendar_book, bool is_visible); /** - * @brief Gets the visible status of the calendar handle. + * @brief Gets the visible status of the calendar book handle. * - * @param [in] calendar The calendar handle - * @param [out] is_visible @c true if the calendar is visible in the device, otherwise @c false \n + * @param [in] calendar_book The calendar book handle + * @param [out] is_visible @c true if the calendar book is visible in the device, otherwise @c false \n * (default : @c false) * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_set_is_visibile() + */ +int calendar_book_get_is_visible(calendar_book_h calendar_book, bool *is_visible); + +/** + * @brief Sets the color of the calendar book from the calendar book handle. + * + * @param [in] calendar_book The calendar book handle + * @param [in] red The calendar book color which represents red among RGB + * @param [in] green The calendar book color which represents green among RGB + * @param [in] blue The calendar book color which represents blue among RGB + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_get_color() + * @see calendar_book_unset_color() + */ +int calendar_book_set_color(calendar_book_h calendar_book, unsigned char red, unsigned char green, unsigned char blue); + +/** + * @brief Unsets the color of the calendar book from the calendar book handle. + * + * @param [in] calendar_book The calendar book handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_set_color() */ -int calendar_get_is_visibile(calendar_h calendar, bool *is_visible); +int calendar_book_unset_color(calendar_book_h calendar_book); /** - * @brief Gets the color of the calendar from the calendar handle. + * @brief Gets the color of the calendar book from the calendar book handle. + * + * @remarks returns @a CALENDAR_ERROR_NO_DATA means calendar book color is not valid * - * @param [in] calendar The calendar handle - * @param [out] red The calendar color which represents red among RGB - * @param [out] green The calendar color which represents green among RGB - * @param [out] blue The calendar color which represents blue among RGB + * @param [in] calendar_book The calendar book handle + * @param [out] red The calendar book color which represents red among RGB + * @param [out] green The calendar book color which represents green among RGB + * @param [out] blue The calendar book color which represents blue among RGB * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_NO_DATA Data not found + * + * @see calendar_book_set_color() + */ +int calendar_book_get_color(calendar_book_h calendar_book, unsigned char *red, unsigned char *green, unsigned char *blue); + +/** + * @brief Sets the account database ID associated with the given calendar book handle. + * + * @param[in] calendar_book The calendar book handle + * @param[in] account_db_id The account database ID(default : 0) \n + * 0 means the calendar book is not related to any accounts. + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_get_account_db_id() */ -int calendar_get_color(calendar_h calendar, unsigned char *red, unsigned char *green, unsigned char *blue); +int calendar_book_set_account_db_id(calendar_book_h calendar_book, int account_db_id); /** - * @brief Gets the account database ID associated with the given calendar handle. + * @brief Gets the account database ID associated with the given calendar book handle. * - * @param[in] calendar The calendar handle + * @param[in] calendar_book The calendar book handle * @param[out] account_db_id The account database ID(default : 0) \n - * 0 means the calendar is not related to any accounts. + * 0 means the calendar book is not related to any accounts. * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_set_account_db_id() */ -int calendar_get_account_db_id(calendar_h calendar, int *account_db_id); +int calendar_book_get_account_db_id(calendar_book_h calendar_book, int *account_db_id); /** - * @brief Retrieves all calendars by invoking the given callback function iteratively. + * @brief Frees calendar book array * - * @param[in] callback The callback function to invoke - * @param[in] user_data The user data to be passed to the callback function + * @param[out] calendar_book_array The calendar book array + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see calendar_book_get_all_calendar_book() + */ +int calendar_book_free_calendar_book_array(calendar_book_h *calendar_book_array); + +/** + * @brief Retrieves all calendar books as array from database. + * + * @remarks @a calendar_book_array must be released with calendar_book_free_calendar_book_array() by you. + * + * @param[out] calendar_book_array The calendar book array + * @param[out] length The length of the calendar book array * * @return 0 on success, otherwise a negative error value. * @retval #CALENDAR_ERROR_NONE Successful @@ -1672,11 +2424,31 @@ int calendar_get_account_db_id(calendar_h calendar, int *account_db_id); * * @pre This function requires an open connection to the calendar service by calendar_connect(). * - * @post This function invokes calendar_foreach_query_event_cb(). + * @see calendar_connect() + * @see calendar_book_free_calendar_book_array() + */ +int calendar_book_get_all_calendar_book(calendar_book_h **calendar_book_array, int *length); + +/** + * @brief Retrieves calendar books as array with account database ID from database. + * + * @remarks @a calendar_book_array must be released with calendar_book_free_calendar_book_array() by you. * - * @see calendar_foreach_query_calendar_cb() + * @param[in] account_db_id The account database ID to filter + * @param[out] calendar_book_array The calendar book array + * @param[out] length The length of the calendar book array + * + * @return 0 on success, otherwise a negative error value. + * @retval #CALENDAR_ERROR_NONE Successful + * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CALENDAR_ERROR_DB_FAILED No access to database + * + * @pre This function requires an open connection to the calendar service by calendar_connect(). + * + * @see calendar_connect() + * @see calendar_book_free_calendar_book_array() */ -int calendar_foreach_calendar_from_db(calendar_foreach_query_calendar_cb callback, void *user_data); +int calendar_book_search_calendar_book_by_account(int account_db_id, calendar_book_h **calendar_book_array, int *length); /** * @} |