include/calendar_list.h

   1 /*
   2  * Calendar Service
   3  *
   4  * Copyright (c) 2012 - 2015 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 #ifndef __TIZEN_SOCIAL_CALENDAR_LIST_H__
  21 #define __TIZEN_SOCIAL_CALENDAR_LIST_H__
  22
  23 #include <calendar_types.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @addtogroup CAPI_SOCIAL_CALENDAR_SVC_LIST_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Creates a calendar list handle.
  36  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  37  * @remarks You must release @a calendar_list using calendar_list_destroy().
  38  * @param[out] out_list The calendar list handle
  39  * @return @c 0 on success,
  40  *         otherwise a negative error value
  41  * @retval #CALENDAR_ERROR_NONE Successful
  42  * @retval #CALENDAR_ERROR_OUT_OF_MEMORY Out of memory
  43  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
  44  * @see calendar_list_destroy()
  45  */
  46 int calendar_list_create(calendar_list_h* out_list);
  47
  48
  49 /**
  50  * @brief Destroys a calendar list handle and releases all its resources.
  51  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  52  * @param[in] list The calendar list handle
  53  * @param[in] delete_record If @c true, child records are destroyed automatically,
  54  *                          otherwise @c false
  55  * @return @c 0 on success,
  56  *         otherwise a negative error value
  57  * @retval #CALENDAR_ERROR_NONE Successful
  58  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
  59  * @see calendar_list_create()
  60  */
  61 int calendar_list_destroy(calendar_list_h list, bool delete_record);
  62
  63
  64 /**
  65  * @brief Retrieves the number of calendar entities in a calendar list.
  66  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  67  * @param[in] list The calendar list handle
  68  * @param[out] count The count of the calendar entity
  69  * @return @c 0 on success,
  70  *         otherwise a negative error value
  71  * @retval #CALENDAR_ERROR_NONE Successful
  72  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
  73  * @see calendar_list_add()
  74  */
  75 int calendar_list_get_count(calendar_list_h list, int *count);
  76
  77
  78 /**
  79  * @brief Adds a record to the calendar list.
  80  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  81  * @param[in] list The calendar list handle
  82  * @param[in] record The record handle
  83  * @return @c 0 on success,
  84  *         otherwise a negative error value
  85  * @retval #CALENDAR_ERROR_NONE Successful
  86  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
  87  * @see calendar_list_remove()
  88  */
  89 int calendar_list_add(calendar_list_h list, calendar_record_h record);
  90
  91
  92 /**
  93  * @brief Removes a record from the calendar list.
  94  * @details If the record is the current record, then the current record is changed to the next record.\n
  95  *          If the record is the last record then the current record will be @c NULL.
  96  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  97  * @param[in] list The calendar list handle
  98  * @param[in] record The record handle
  99  * @return @c 0 on success,
 100  *         otherwise a negative error value
 101  * @retval #CALENDAR_ERROR_NONE Successful
 102  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
 103  * @retval #CALENDAR_ERROR_NO_DATA Requested data does not exist
 104  * @see calendar_list_add()
 105  */
 106 int calendar_list_remove(calendar_list_h list, calendar_record_h record);
 107
 108
 109 /**
 110  * @brief Retrieves a record from the calendar list.
 111  * @details The default current record is the first record.
 112  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 113  * @remarks You MUST NOT destroy the @a record handle.
 114  *          It is destroyed automatically when the @a list is destroyed.
 115  * @param[in] list The calendar list handle
 116  * @param[out] record The record handle
 117  * @return @c 0 on success,
 118  *         otherwise a negative error value
 119  * @retval #CALENDAR_ERROR_NONE Successful
 120  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
 121  * @retval #CALENDAR_ERROR_NO_DATA Requested data does not exist
 122  */
 123 int calendar_list_get_current_record_p(calendar_list_h list, calendar_record_h* record);
 124
 125
 126 /**
 127  * @brief Moves a calendar list to the previous position.
 128  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 129  * @param[in] list The calendar list handle
 130  * @return @c 0 on success,
 131  *         otherwise a negative error value
 132  * @retval #CALENDAR_ERROR_NONE Successful
 133  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
 134  * @retval #CALENDAR_ERROR_NO_DATA Requested data does not exist
 135  * @see calendar_list_next()
 136  */
 137 int calendar_list_prev(calendar_list_h list);
 138
 139
 140 /**
 141  * @brief Moves a calendar list to the next position.
 142  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 143  * @param[in] list The calendar list handle
 144  * @return @c 0 on success,
 145  *         otherwise a negative error value
 146  * @retval #CALENDAR_ERROR_NONE Successful
 147  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
 148  * @retval #CALENDAR_ERROR_NO_DATA Requested data does not exist
 149  * @see calendar_list_prev()
 150  */
 151 int calendar_list_next(calendar_list_h list);
 152
 153
 154 /**
 155  * @brief Moves a calendar list to the first position.
 156  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 157  * @param[in] list The calendar list handle
 158  * @return @c 0 on success,
 159  *         otherwise a negative error value
 160  * @retval #CALENDAR_ERROR_NONE Successful
 161  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
 162  * @see calendar_list_last()
 163  */
 164 int calendar_list_first(calendar_list_h list);
 165
 166
 167 /**
 168  * @brief Moves a calendar list to the last position.
 169  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 170  * @param[in] list The calendar list handle
 171  * @return @c 0 on success,
 172  *         otherwise a negative error value
 173  * @retval #CALENDAR_ERROR_NONE Successful
 174  * @retval #CALENDAR_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @see calendar_list_first()
 176  */
 177 int calendar_list_last(calendar_list_h list);
 178
 179
 180 /**
 181  * @}
 182  */
 183
 184 #ifdef __cplusplus
 185 }
 186 #endif
 187
 188 #endif /* __TIZEN_SOCIAL_CALENDAR_LIST_H__ */
 189