include/contacts_record.h

   1 /*
   2  * Contacts Service
   3  *
   4  * Copyright (c) 2010 - 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
  21 #ifndef __TIZEN_SOCIAL_CONTACTS_RECORD_H__
  22 #define __TIZEN_SOCIAL_CONTACTS_RECORD_H__
  23
  24
  25 #ifdef __cplusplus
  26 extern "C"
  27 {
  28 #endif
  29
  30
  31 /**
  32  * @file contacts_record.h
  33  */
  34
  35
  36 /**
  37  * @ingroup CAPI_SOCIAL_CONTACTS_SVC_MODULE
  38  * @defgroup CAPI_SOCIAL_CONTACTS_SVC_RECORD_MODULE Record
  39  * @brief The contacts record API provides the set of the definitions and interfaces that enable application developers to get/set data from/to contacts record handle.
  40  * @section CAPI_SOCIAL_CONTACTS_SVC_RECORD_MODULE_HEADER Required Header
  41  *          \#include <contacts.h>
  42  * <BR>
  43  * @{
  44  */
  45
  46
  47 /**
  48  * @brief Creates a record.
  49  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  50  * @remarks You must release @a record using contacts_record_destroy().
  51  * @param[in] view_uri The view URI
  52  * @param[out] record The record handle
  53  * @return @c 0 on success,
  54  *         otherwise a negative error value
  55  * @retval #CONTACTS_ERROR_NONE Successful
  56  * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory
  57  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
  58  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
  59  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
  60  * @pre contacts_connect() should be called to initialize.
  61  * @see contacts_record_destroy()
  62  */
  63 int contacts_record_create(const char *view_uri, contacts_record_h *record);
  64
  65
  66 /**
  67  * @brief Destroys a record and releases its all resources.
  68  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  69  * @param[in] record The record handle
  70  * @param[in] delete_child Set @c true to destroy child records automatically,
  71  *                         otherwise set @c false to not destroy child records automatically
  72  * @return @c 0 on success,
  73  *         otherwise a negative error value
  74  * @retval #CONTACTS_ERROR_NONE Successful
  75  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
  76  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
  77  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
  78  * @see contacts_record_create()
  79  */
  80 int contacts_record_destroy(contacts_record_h record, bool delete_child);
  81
  82
  83 /**
  84  * @brief Makes a clone of a record.
  85  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  86  * @remarks You must release @a cloned_record using contacts_record_destroy().
  87  * @param[in] record The record handle
  88  * @param[out] cloned_record The cloned record handle
  89  * @return @c 0 on success,
  90  *         otherwise a negative error value
  91  * @retval #CONTACTS_ERROR_NONE Successful
  92  * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory
  93  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
  94  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
  95  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
  96  * @see contacts_record_destroy()
  97  */
  98 int contacts_record_clone(contacts_record_h record, contacts_record_h *cloned_record);
  99
 100
 101 /**
 102  * @brief Gets a string from the record handle.
 103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 104  * @remarks You must release @a value using free().
 105  * @param[in] record The record handle
 106  * @param[in] property_id The property ID
 107  * @param[out] value The value to be returned
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  * @retval #CONTACTS_ERROR_NONE Successful
 111  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 112  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 113  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 114  * @see contacts_record_get_str_p()
 115  * @see contacts_record_set_str()
 116  */
 117 int contacts_record_get_str(contacts_record_h record, unsigned int property_id, char **value);
 118
 119
 120 /**
 121  * @brief Gets a string pointer from the record handle.
 122  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 123  * @remarks You MUST NOT release @a value.
 124  * @param[in] record The record handle
 125  * @param[in] property_id The property ID
 126  * @param[out] value The value to be returned
 127  * @return @c 0 on success,
 128  *         otherwise a negative error value
 129  * @retval #CONTACTS_ERROR_NONE Successful
 130  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 131  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 132  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 133  * @see contacts_record_get_str()
 134  * @see contacts_record_set_str()
 135  */
 136 int contacts_record_get_str_p(contacts_record_h record, unsigned int property_id, char **value);
 137
 138
 139 /**
 140  * @brief Sets a string to a record.
 141  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 142  * @param[in] record The record handle
 143  * @param[in] property_id The property ID
 144  * @param[in] value The value to set
 145  * @return @c 0 on success,
 146  *         otherwise a negative error value
 147  * @retval #CONTACTS_ERROR_NONE Successful
 148  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 149  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 150  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 151  * @see contacts_record_get_str()
 152  * @see contacts_record_get_str_p()
 153  */
 154 int contacts_record_set_str(contacts_record_h record, unsigned int property_id, const char *value);
 155
 156
 157 /**
 158  * @brief Gets a record's integer value.
 159  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 160  * @param[in] record The record handle
 161  * @param[in] property_id The property ID
 162  * @param[out] value The value to be returned
 163  * @return @c 0 on success,
 164  *         otherwise a negative error value
 165  * @retval #CONTACTS_ERROR_NONE Successful
 166  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 167  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 168  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 169  * @see contacts_record_set_int()
 170  */
 171 int contacts_record_get_int(contacts_record_h record, unsigned int property_id, int *value);
 172
 173
 174 /**
 175  * @brief Sets an integer value to a record.
 176  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 177  * @param[in] record The record handle
 178  * @param[in] property_id The property ID
 179  * @param[in] value The value to set
 180  * @return @c 0 on success,
 181  *         otherwise a negative error value
 182  * @retval #CONTACTS_ERROR_NONE Successful
 183  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 184  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 185  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 186  * @see contacts_record_get_int()
 187  */
 188 int contacts_record_set_int(contacts_record_h record, unsigned int property_id, int value);
 189
 190
 191 /**
 192  * @brief Gets a record's long integer value.
 193  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 194  * @param[in] record The record handle
 195  * @param[in] property_id The property ID
 196  * @param[out] value The value to be returned
 197  * @return @c 0 on success,
 198  *         otherwise a negative error value
 199  * @retval #CONTACTS_ERROR_NONE Successful
 200  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 201  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 202  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 203  * @see contacts_record_set_lli()
 204  */
 205 int contacts_record_get_lli(contacts_record_h record, unsigned int property_id, long long int *value);
 206
 207
 208 /**
 209  * @brief Sets a long long integer value to a record.
 210  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 211  * @param[in] record The record handle
 212  * @param[in] property_id The property ID
 213  * @param[in] value The value to set
 214  * @return @c 0 on success,
 215  *         otherwise a negative error value
 216  * @retval #CONTACTS_ERROR_NONE Successful
 217  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 218  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 219  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 220  * @see contacts_record_get_lli()
 221  */
 222 int contacts_record_set_lli(contacts_record_h record, unsigned int property_id, long long int value);
 223
 224
 225 /**
 226  * @brief Gets a record's boolean value.
 227  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 228  * @param[in] record The record handle
 229  * @param[in] property_id The property ID
 230  * @param[out] value The value to be returned
 231  * @return @c 0 on success,
 232  *         otherwise a negative error value
 233  * @retval #CONTACTS_ERROR_NONE Successful
 234  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 235  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 236  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 237  * @see contacts_record_set_bool()
 238  */
 239 int contacts_record_get_bool(contacts_record_h record, unsigned int property_id, bool *value);
 240
 241
 242 /**
 243  * @brief Sets a boolean value to a record.
 244  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 245  * @param[in] record The record handle
 246  * @param[in] property_id The property ID
 247  * @param[in] value The value to set
 248  * @return @c 0 on success,
 249  *         otherwise a negative error value
 250  * @retval #CONTACTS_ERROR_NONE Successful
 251  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 252  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 253  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 254  * @see contacts_record_get_bool()
 255  */
 256 int contacts_record_set_bool(contacts_record_h record, unsigned int property_id, bool value);
 257
 258
 259 /**
 260  * @brief Gets a record's double value.
 261  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 262  * @param[in] record The record handle
 263  * @param[in] property_id The property ID
 264  * @param[out] value The value to be returned
 265  * @return @c 0 on success,
 266  *         otherwise a negative error value
 267  * @retval #CONTACTS_ERROR_NONE Successful
 268  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 269  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 270  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 271  * @see contacts_record_set_double()
 272  */
 273 int contacts_record_get_double(contacts_record_h record, unsigned int property_id, double *value);
 274
 275
 276 /**
 277  * @brief Sets a double value to a record.
 278  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 279  * @param[in] record The record handle
 280  * @param[in] property_id The property ID
 281  * @param[in] value The value to set
 282  * @return @c 0 on success,
 283  *         otherwise a negative error value
 284  * @retval #CONTACTS_ERROR_NONE Successful
 285  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 286  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 287  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 288  * @see contacts_record_get_double()
 289  */
 290 int contacts_record_set_double(contacts_record_h record, unsigned int property_id, double value);
 291
 292
 293 /**
 294  * @brief Adds a child record to the parent record.
 295  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 296  * @param[in] record The parent record handle
 297  * @param[in] property_id The property ID
 298  * @param[in] child_record The child record handle to be added to parent record handle
 299  * @return @c 0 on success,
 300  *         otherwise a negative error value
 301  * @retval #CONTACTS_ERROR_NONE Successful
 302  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 303  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 304  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 305  * @see contacts_record_remove_child_record()
 306  */
 307 int contacts_record_add_child_record(contacts_record_h record, unsigned int property_id, contacts_record_h child_record);
 308
 309
 310 /**
 311  * @brief Removes a child record from the parent record.
 312  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 313  * @param[in] record The parent record handle
 314  * @param[in] property_id The property ID
 315  * @param[in] child_record The child record handle to be removed from parent record handle
 316  * @return @c 0 on success,
 317  *         otherwise a negative error value
 318  * @retval #CONTACTS_ERROR_NONE Successful
 319  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 320  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 321  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 322  * @see contacts_record_add_child_record()
 323  */
 324 int contacts_record_remove_child_record(contacts_record_h record, unsigned int property_id, contacts_record_h child_record);
 325
 326
 327 /**
 328  * @brief Gets the number of child records of a parent record.
 329  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 330  * @param[in] record The parent record handle
 331  * @param[in] property_id The property ID
 332  * @param[out] count The child record count
 333  * @return @c 0 on success,
 334  *         otherwise a negative error value
 335  * @retval #CONTACTS_ERROR_NONE Successful
 336  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 337  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 338  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 339  * @see contacts_record_add_child_record()
 340  * @see contacts_record_remove_child_record()
 341  */
 342 int contacts_record_get_child_record_count(contacts_record_h record, unsigned int property_id, int *count);
 343
 344
 345 /**
 346  * @brief Gets a child record handle pointer from the parent record.
 347  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 348  * @remarks You MUST NOT release @a child_record. It is released when the parent record is destroyed.
 349  * @param[in] record The record handle
 350  * @param[in] property_id The property ID
 351  * @param[in] index The index of child record
 352  * @param[out] child_record The child record handle pointer
 353  * @return @c 0 on success,
 354  *         otherwise a negative error value
 355  * @retval #CONTACTS_ERROR_NONE Successful
 356  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 357  * @retval #CONTACTS_ERROR_NO_DATA
 358  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 359  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 360  * @see contacts_record_add_child_record()
 361  * @see contacts_record_remove_child_record()
 362  * @see contacts_record_get_child_record_count()
 363  */
 364 int contacts_record_get_child_record_at_p(contacts_record_h record, unsigned int property_id, int index, contacts_record_h *child_record);
 365
 366
 367 /**
 368  * @brief Clones a child record list of the given parent record.
 369  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 370  * @remarks You must release @a cloned_list using contacts_list_destroy().
 371  * @param[in] record The record handle
 372  * @param[in] property_id The property ID
 373  * @param[out] cloned_list The cloned list handle
 374  * @return @c 0 on success,
 375  *         otherwise a negative error value
 376  * @retval #CONTACTS_ERROR_NONE Successful
 377  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 378  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 379  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 380  * @see contacts_list_destroy()
 381  */
 382 int contacts_record_clone_child_record_list(contacts_record_h record, unsigned int property_id, contacts_list_h *cloned_list);
 383
 384
 385 /**
 386  * @brief Gets URI string from a record.
 387  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 388  * @param[in] record The record handle
 389  * @param[out] view_uri The URI of record
 390  * @return @c 0 on success,
 391  *         otherwise a negative error value
 392  * @retval #CONTACTS_ERROR_NONE Successful
 393  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 394  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 395  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 396  */
 397 int contacts_record_get_uri_p(contacts_record_h record, const char **view_uri);
 398
 399
 400 /**
 401  * @}
 402  */
 403
 404
 405 #ifdef __cplusplus
 406 }
 407 #endif
 408
 409
 410 #endif /* __TIZEN_SOCIAL_CONTACTS_RECORD_H__ */
 411