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  *
  37  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  38  *
  39  * @remarks You must release @a calendar_list using calendar_list_destroy().
  40  *
  41  * @param[out]  out_list   The calendar list handle
  42  *
  43  * @return  @c 0 on success,
  44  *          otherwise a negative error value
  45  * @retval  #CALENDAR_ERROR_NONE                Successful
  46  * @retval  #CALENDAR_ERROR_OUT_OF_MEMORY       Out of memory
  47  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
  48  *
  49  * @see calendar_list_destroy()
  50  */
  51 int calendar_list_create(calendar_list_h* out_list);
  52
  53 /**
  54  * @brief Destroys a calendar list handle and releases all its resources.
  55  *
  56  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  57  *
  58  * @param[in]   list            The calendar list handle
  59  * @param[in]   delete_record   If @c true, child records are destroyed automatically,
  60  *                              otherwise @c false
  61  *
  62  * @return  @c 0 on success,
  63  *          otherwise a negative error value
  64  * @retval  #CALENDAR_ERROR_NONE                   Successful
  65  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER      Invalid parameter
  66  *
  67  * @see calendar_list_create()
  68  */
  69 int calendar_list_destroy(calendar_list_h list, bool delete_record);
  70
  71
  72 /**
  73  * @brief Retrieves the number of calendar entities in a calendar list.
  74  *
  75  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  76  *
  77  * @param[in]   list     The calendar list handle
  78  * @param[out]  count    The count of the calendar entity
  79  *
  80  * @return  @c 0 on success,
  81  *          otherwise a negative error value
  82  * @retval  #CALENDAR_ERROR_NONE                Successful
  83  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
  84  *
  85  * @see calendar_list_add()
  86  */
  87 int calendar_list_get_count(calendar_list_h list, int *count);
  88
  89 /**
  90  * @brief Adds a record to the calendar list.
  91  *
  92  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  93  *
  94  * @param[in]   list    The calendar list handle
  95  * @param[in]   record  The record handle
  96  *
  97  * @return  @c 0 on success,
  98  *          otherwise a negative error value
  99  * @retval  #CALENDAR_ERROR_NONE                Successful
 100  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 101  *
 102  * @see calendar_list_remove()
 103  */
 104 int calendar_list_add(calendar_list_h list, calendar_record_h record);
 105
 106 /**
 107  * @brief Removes a record from the calendar list.
 108  * @details If the record is the current record, then the current record is changed to the next record.\n
 109  *          If the record is the last record then the current record will be @c NULL.
 110  *
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 112  *
 113  * @param[in]   list    The calendar list handle
 114  * @param[in]   record  The record handle
 115  *
 116  * @return  @c 0 on success,
 117  *          otherwise a negative error value
 118  * @retval  #CALENDAR_ERROR_NONE                Successful
 119  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 120  * @retval  #CALENDAR_ERROR_NO_DATA             Requested data does not exist
 121  *
 122  * @see calendar_list_add()
 123  */
 124 int calendar_list_remove(calendar_list_h list, calendar_record_h record);
 125
 126 /**
 127  * @brief Retrieves a record from the calendar list.
 128  * @details The default current record is the first record.
 129  *
 130  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 131  *
 132  * @remarks You MUST NOT destroy the @a record handle.
 133  *          It is destroyed automatically when the @a list is destroyed.
 134  *
 135  * @param[in]   list        The calendar list handle
 136  * @param[out]  record      The record handle
 137  *
 138  * @return  @c 0 on success,
 139  *          otherwise a negative error value
 140  * @retval  #CALENDAR_ERROR_NONE                Successful
 141  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 142  * @retval  #CALENDAR_ERROR_NO_DATA             Requested data does not exist
 143  */
 144 int calendar_list_get_current_record_p(calendar_list_h list, calendar_record_h* record);
 145
 146 /**
 147  * @brief Moves a calendar list to the previous position.
 148  *
 149  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 150  *
 151  * @param[in]  list  The calendar list handle
 152  *
 153  * @return  @c 0 on success,
 154  *          otherwise a negative error value
 155  * @retval  #CALENDAR_ERROR_NONE                Successful
 156  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 157  * @retval  #CALENDAR_ERROR_NO_DATA             Requested data does not exist
 158  *
 159  * @see calendar_list_next()
 160  */
 161 int calendar_list_prev(calendar_list_h list);
 162
 163 /**
 164  * @brief Moves a calendar list to the next position.
 165  *
 166  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 167  *
 168  * @param[in]  list  The calendar list handle
 169  *
 170  * @return  @c 0 on success,
 171  *          otherwise a negative error value
 172  * @retval  #CALENDAR_ERROR_NONE                Successful
 173  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 174  * @retval  #CALENDAR_ERROR_NO_DATA             Requested data does not exist
 175  *
 176  * @see calendar_list_prev()
 177  */
 178 int calendar_list_next(calendar_list_h list);
 179
 180 /**
 181  * @brief Moves a calendar list to the first position.
 182  *
 183  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 184  *
 185  * @param[in]  list  The calendar list handle
 186  *
 187  * @return  @c 0 on success,
 188  *          otherwise a negative error value
 189  * @retval  #CALENDAR_ERROR_NONE                Successful
 190  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 191  *
 192  * @see calendar_list_last()
 193  */
 194 int calendar_list_first(calendar_list_h list);
 195
 196 /**
 197  * @brief Moves a calendar list to the last position.
 198  *
 199  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 200  *
 201  * @param[in]  list  The calendar list handle
 202  *
 203  * @return  @c 0 on success,
 204  *          otherwise a negative error value
 205  * @retval  #CALENDAR_ERROR_NONE                Successful
 206  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 207  *
 208  * @see calendar_list_first()
 209  */
 210 int calendar_list_last(calendar_list_h list);
 211
 212 /**
 213  * @}
 214  */
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 #endif /* __TIZEN_SOCIAL_CALENDAR_LIST_H__ */
 221