include/calendar_record.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_RECORD_H__
  21 #define __TIZEN_SOCIAL_CALENDAR_RECORD_H__
  22
  23 #include <calendar_types.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @file calendar_record.h
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_SOCIAL_CALENDAR_SVC_RECORD_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief Creates a record handle.
  40  *
  41  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  42  *
  43  * @remarks You must release @a record using calendar_record_destroy().
  44  *
  45  * @param[in]   view_uri    The view URI
  46  * @param[out]  out_record  The record handle
  47  *
  48  * @return  @c 0 on success,
  49  *          otherwise a negative error value
  50  * @retval  #CALENDAR_ERROR_NONE                Successful
  51  * @retval  #CALENDAR_ERROR_OUT_OF_MEMORY       Out of memory
  52  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
  53  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
  54  *
  55  * @pre     calendar_connect() should be called to initialize.
  56  *
  57  * @see calendar_record_destroy()
  58  */
  59 int calendar_record_create(const char* view_uri, calendar_record_h* out_record);
  60
  61 /**
  62  * @brief Destroys a record handle and releases all its resources.
  63  *
  64  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  65  *
  66  * @param[in]   record          The record handle
  67  * @param[in]   delete_child    If @c true, child records are destroyed automatically,
  68  *                              otherwise @c false
  69  *
  70  * @return  @c 0 on success,
  71  *          otherwise a negative error value
  72  * @retval  #CALENDAR_ERROR_NONE                 Successful
  73  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER    Invalid parameter
  74  * @retval  #CALENDAR_ERROR_NOT_PERMITTED        Operation not permitted
  75  *
  76  * @see calendar_record_create()
  77  */
  78 int calendar_record_destroy(calendar_record_h record, bool delete_child);
  79
  80 /**
  81  * @brief Makes a clone of a record handle.
  82  *
  83  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  84  *
  85  * @remarks You must release @a cloned_record using calendar_record_destroy().
  86  *
  87  * @param[in]   record          The record handle
  88  * @param[out]  out_record      The cloned record handle
  89  *
  90  * @return  @c 0 on success,
  91  *          otherwise a negative error value
  92  * @retval  #CALENDAR_ERROR_NONE                    Successful
  93  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER       Invalid parameter
  94  * @retval  #CALENDAR_ERROR_NOT_PERMITTED           Operation not permitted
  95  *
  96  * @see calendar_record_destroy()
  97  */
  98 int calendar_record_clone(calendar_record_h record, calendar_record_h* out_record);
  99
 100 /**
 101  * @brief Gets a URI string from a record.
 102  *
 103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 104  *
 105  * @param[in]   record   The record handle
 106  * @param[out]  uri      The URI of the record
 107  *
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  * @retval  #CALENDAR_ERROR_NONE                 Successful
 111  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER    Invalid parameter
 112  */
 113 int calendar_record_get_uri_p(calendar_record_h record, char** uri);
 114
 115 /**
 116  * @brief Gets a string from a record.
 117  *
 118  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 119  *
 120  * @remarks You must release @a value using free().
 121  *
 122  * @param[in]   record        The record handle
 123  * @param[in]   property_id   The property ID
 124  * @param[out]  out_str       The result value
 125  *
 126  * @return @c 0 on success,
 127  *         otherwise a negative error value
 128  * @retval  #CALENDAR_ERROR_NONE                Successful
 129  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 130  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 131  *
 132  * @see calendar_record_get_str_p()
 133  * @see calendar_record_set_str()
 134  */
 135 int calendar_record_get_str(calendar_record_h record, unsigned int property_id, char** out_str);
 136
 137 /**
 138  * @brief Gets a string pointer from a record.
 139  *
 140  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 141  *
 142  * @remarks You MUST NOT release @a value.
 143  *
 144  * @param[in]   record         The record handle
 145  * @param[in]   property_id    The property ID
 146  * @param[out]  out_str        The result value
 147  *
 148  * @return @c 0 on success,
 149  *         otherwise a negative error value
 150  * @retval  #CALENDAR_ERROR_NONE                Successful
 151  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 152  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 153  *
 154  * @see calendar_record_get_str()
 155  * @see calendar_record_set_str()
 156  */
 157 int calendar_record_get_str_p(calendar_record_h record, unsigned int property_id, char** out_str);
 158
 159 /**
 160  * @brief Gets an integer value from a record.
 161  *
 162  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 163  *
 164  * @param[in]   record          The record handle
 165  * @param[in]   property_id     The property ID
 166  * @param[out]  out_value       The result value
 167  *
 168  * @return @c 0 on success,
 169  *         otherwise a negative error value
 170  * @retval  #CALENDAR_ERROR_NONE                Successful
 171  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 172  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 173  *
 174  * @see calendar_record_set_int()
 175  */
 176 int calendar_record_get_int(calendar_record_h record, unsigned int property_id, int* out_value);
 177
 178 /**
 179  * @brief Gets a double value from a record.
 180  *
 181  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 182  *
 183  * @param[in]   record          The record handle
 184  * @param[in]   property_id     The property ID
 185  * @param[out]  out_value       The result value
 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  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 192  *
 193  * @see calendar_record_set_double()
 194  */
 195 int calendar_record_get_double(calendar_record_h record, unsigned int property_id, double* out_value);
 196
 197 /**
 198  * @brief Gets a long long integer value from a record.
 199  *
 200  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 201  *
 202  * @param[in]   record          The record handle
 203  * @param[in]   property_id         The property ID
 204  * @param[out]  out_value       The result value
 205  *
 206  * @return @c 0 on success,
 207  *         otherwise a negative error value
 208  * @retval  #CALENDAR_ERROR_NONE                Successful
 209  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 210  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 211  *
 212  * @see calendar_record_set_lli()
 213  */
 214 int calendar_record_get_lli(calendar_record_h record, unsigned int property_id, long long int* out_value);
 215
 216 /**
 217  * @brief Gets a calendar_caltime_s value from a record.
 218  *
 219  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 220  *
 221  * @param[in]   record          The record handle
 222  * @param[in]   property_id     The property ID
 223  * @param[out]  out_value       The result value
 224  *
 225  * @return @c 0 on success,
 226  *         otherwise a negative error value
 227  * @retval  #CALENDAR_ERROR_NONE                Successful
 228  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 229  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 230  *
 231  * @see calendar_record_set_caltime()
 232  */
 233 int calendar_record_get_caltime(calendar_record_h record, unsigned int property_id, calendar_time_s* out_value);
 234
 235 /**
 236  * @brief Sets a string to a record.
 237  *
 238  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 239  *
 240  * @param[in]   record          The record handle
 241  * @param[in]   property_id     The property ID
 242  * @param[in]   value           The value to be set
 243  *
 244  * @return      @c 0 on success,
 245  *              otherwise a negative error value
 246  * @retval      #CALENDAR_ERROR_NONE                  Successful
 247  * @retval      #CALENDAR_ERROR_INVALID_PARAMETER     Invalid parameter
 248  * @retval      #CALENDAR_ERROR_NOT_PERMITTED         Operation not permitted
 249  *
 250  * @see calendar_record_get_str()
 251  * @see calendar_record_get_str_p()
 252  */
 253 int calendar_record_set_str(calendar_record_h record, unsigned int property_id, const char* value);
 254
 255 /**
 256  * @brief Sets an integer value to a record.
 257  *
 258  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 259  *
 260  * @param[in]   record          The record handle
 261  * @param[in]   property_id         The property ID
 262  * @param[in]   value           The value to be set
 263  *
 264  * @return      @c 0 on success,
 265  *              otherwise a negative error value
 266  * @retval      #CALENDAR_ERROR_NONE                  Successful
 267  * @retval      #CALENDAR_ERROR_INVALID_PARAMETER     Invalid parameter
 268  * @retval      #CALENDAR_ERROR_NOT_PERMITTED         Operation not permitted
 269  *
 270  * @see calendar_record_get_int()
 271  */
 272 int calendar_record_set_int(calendar_record_h record, unsigned int property_id, int value);
 273
 274 /**
 275  * @brief Sets a double value to a record.
 276  *
 277  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 278  *
 279  * @param[in]   record          The record handle
 280  * @param[in]   property_id     The property ID
 281  * @param[in]   value           The value to be set
 282  *
 283  * @return      @c 0 on success,
 284  *              otherwise a negative error value
 285  * @retval      #CALENDAR_ERROR_NONE                  Successful
 286  * @retval      #CALENDAR_ERROR_INVALID_PARAMETER     Invalid parameter
 287  * @retval      #CALENDAR_ERROR_NOT_PERMITTED         Operation not permitted
 288  *
 289  * @see calendar_record_get_double()
 290  */
 291 int calendar_record_set_double(calendar_record_h record, unsigned int property_id, double value);
 292
 293 /**
 294  * @brief Sets a long long integer value to a record.
 295  *
 296  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 297  *
 298  * @param[in]   record          The record handle
 299  * @param[in]   property_id     The property ID
 300  * @param[in]   value           The value to be set
 301  *
 302  * @return      @c 0 on success,
 303  *              otherwise a negative error value
 304  * @retval      #CALENDAR_ERROR_NONE                  Successful
 305  * @retval      #CALENDAR_ERROR_INVALID_PARAMETER     Invalid parameter
 306  * @retval      #CALENDAR_ERROR_NOT_PERMITTED         Operation not permitted
 307  *
 308  * @see calendar_record_get_lli()
 309  */
 310 int calendar_record_set_lli(calendar_record_h record, unsigned int property_id, long long int value);
 311
 312 /**
 313  * @brief Sets a calendar_time_s value to a record.
 314  *
 315  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 316  *
 317  * @param[in]   record          The record handle
 318  * @param[in]   property_id     The property ID
 319  * @param[in]   value           The value to be set
 320  *
 321  * @return      @c 0 on success,
 322  *              otherwise a negative error value
 323  * @retval      #CALENDAR_ERROR_NONE                  Successful
 324  * @retval      #CALENDAR_ERROR_INVALID_PARAMETER     Invalid parameter
 325  * @retval      #CALENDAR_ERROR_NOT_PERMITTED         Operation not permitted
 326  *
 327  * @see calendar_record_get_caltime()
 328  */
 329 int calendar_record_set_caltime(calendar_record_h record, unsigned int property_id, calendar_time_s value);
 330
 331 /**
 332  * @brief Adds a child record to the parent record.
 333  *
 334  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 335  *
 336  * @param[in]   record          The parent record handle
 337  * @param[in]   property_id     The property ID
 338  * @param[in]   child_record    The handle of the child record to be added to the parent record
 339  *
 340  * @return  @c 0 on success,
 341  *          otherwise a negative error value
 342  * @retval  #CALENDAR_ERROR_NONE                  Successful
 343  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER     Invalid parameter
 344  * @retval  #CALENDAR_ERROR_NOT_PERMITTED         Operation not permitted
 345  *
 346  * @see calendar_record_remove_child_record()
 347  */
 348 int calendar_record_add_child_record(calendar_record_h record, unsigned int property_id, calendar_record_h child_record);
 349
 350 /**
 351  * @brief Removes a child record from the parent record.
 352  *
 353  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 354  *
 355  * @param[in]   record        The parent record handle
 356  * @param[in]   property_id   The property ID
 357  * @param[in]   child_record  The handle of the child record to be removed from the parent record
 358  *
 359  * @return  @c 0 on success,
 360  *          otherwise a negative error value
 361  * @retval  #CALENDAR_ERROR_NONE                Successful
 362  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 363  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 364  *
 365  * @see calendar_record_add_child_record()
 366  */
 367 int calendar_record_remove_child_record(calendar_record_h record, unsigned int property_id, calendar_record_h child_record);
 368
 369 /**
 370  * @brief Gets the number of child records in a record.
 371  *
 372  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 373  *
 374  * @param[in]   record          The parent record handle
 375  * @param[in]   property_id     The property ID
 376  * @param[out]  count           The child record count
 377  *
 378  * @return @c 0 on success,
 379  *         otherwise a negative error value
 380  * @retval  #CALENDAR_ERROR_NONE                Successful
 381  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 382  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 383  *
 384  * @see calendar_record_add_child_record()
 385  * @see calendar_record_remove_child_record()
 386  */
 387 int calendar_record_get_child_record_count(calendar_record_h record, unsigned int property_id, unsigned int* count);
 388
 389 /**
 390  * @brief Gets a child record handle pointer from the parent record.
 391  *
 392  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 393  *
 394  * @remarks You MUST NOT release @a child_record. \n It is released when the parent record handle is destroyed.
 395  *
 396  * @param[in]   record          The record handle
 397  * @param[in]   property_id     The property ID
 398  * @param[in]   index           The index of the child record
 399  * @param[out]  child_record    The child record handle pointer
 400  *
 401  * @return @c 0 on success,
 402  *         otherwise a negative error value
 403  * @retval  #CALENDAR_ERROR_NONE                Successful
 404  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 405  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 406  *
 407  * @see calendar_record_add_child_record()
 408  * @see calendar_record_remove_child_record()
 409  * @see calendar_record_get_child_record_count()
 410  */
 411 int calendar_record_get_child_record_at_p(calendar_record_h record, unsigned int property_id, int index, calendar_record_h* child_record);
 412
 413 /**
 414  * @brief Makes a clone of a given record's child record list.
 415  *
 416  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 417  *
 418  * @remarks You must release @a cloned_list using calendar_list_destroy().
 419  *
 420  * @param[in]   record          The record handle
 421  * @param[in]   property_id     The property ID
 422  * @param[out]  out_list        The cloned list handle
 423  *
 424  * @return @c 0 on success,
 425  *         otherwise a negative error value
 426  * @retval  #CALENDAR_ERROR_NONE                Successful
 427  * @retval  #CALENDAR_ERROR_INVALID_PARAMETER   Invalid parameter
 428  * @retval  #CALENDAR_ERROR_NOT_PERMITTED       Operation not permitted
 429  *
 430  * @see calendar_list_destroy()
 431  */
 432 int calendar_record_clone_child_record_list(calendar_record_h record, unsigned int property_id, calendar_list_h* out_list);
 433
 434 /**
 435  * @}
 436  */
 437
 438 #ifdef __cplusplus
 439 }
 440 #endif
 441
 442 #endif /* __TIZEN_SOCIAL_CALENDAR_RECORD_H__ */
 443