include/data-adapter/interface_item.h

   1 /*
   2  * sync-agent
   3  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the License);
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 #ifndef INTERFACE_ITEM_H_
  19 #define INTERFACE_ITEM_H_
  20
  21 #include "error.h"
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif                          /* __cplusplus */
  26
  27 /**
  28  * @file                interface_item.h
  29  * @brief
  30  */
  31
  32 /** @addtogroup data_adapter
  33  *      @{
  34  */
  35
  36 /**
  37  * @brief       Structure of framework item instance
  38  */
  39         typedef struct {
  40                 char *item_id;
  41                         /**< F/W item id */
  42                 int data_store_id;
  43                                 /**< service data connector pluIn's ID described in F/W config file  */
  44                 int account_id;
  45                         /**< F/W account id */
  46                 char *folder_id;/**< F/W folder id */
  47                 char *service_id;
  48                                 /**< service item id */
  49                 char *access_name;
  50                                 /**< name of accessor */
  51         } sync_agent_da_item_s;
  52
  53 /**
  54  * @brief       Enumerations of option used to delete framework item
  55  */
  56         typedef enum {
  57                 SYNC_AGENT_DA_DELETE_ITEM_OPTION_ITEM_TYPE_ID,
  58                                                         /**< delete item by item type */
  59         } sync_agent_da_delete_item_option_e;
  60
  61 /**
  62  * @brief       Structure of query used to delete framework item
  63  */
  64         typedef struct {
  65                 sync_agent_da_delete_item_option_e option;
  66                 int account_id;
  67                         /**< F/W account id - SYNC_AGENT_DA_DELETE_ITEM_OPTION_ITEM_TYPE_ID */
  68                 int item_type_id;
  69                                 /**< F/W item type id - SYNC_AGENT_DA_DELETE_ITEM_OPTION_ITEM_TYPE_ID */
  70         } sync_agent_da_delete_item_query_s;
  71
  72 /**
  73  * @brief       Enumerations of option used to fetch framework item list
  74  */
  75         typedef enum {
  76                 SYNC_AGENT_DA_GET_ITEM_LIST_OPTION_ACCOUNT_ID,          /**< get item by account id */
  77                 SYNC_AGENT_DA_GET_ITEM_LIST_OPTION_SERVICE_ID_MAPPING,
  78                                                                 /**< get item by service id */
  79         } sync_agent_da_get_item_list_option_e;
  80
  81 /**
  82  * @brief       Structure of query used to fetch framework item list
  83  */
  84         typedef struct {
  85                 sync_agent_da_get_item_list_option_e option;
  86                 int item_type_id;
  87                                 /**< F/W item type id - SYNC_AGENT_DA_ITEM_GET_LIST_OPTION_ACCOUNT_ID */
  88                 char *item_id;
  89                         /**< F/W item id - SYNC_AGENT_DA_ITEM_GET_LIST_OPTION_SERVICE_ID_MAPPING */
  90         } sync_agent_da_get_item_list_query_s;
  91
  92 /**
  93  * @brief       Structure of query used to fetch framework item id
  94  */
  95         typedef struct {
  96                 int account_id; /**< account id */
  97                 char *service_id;       /**< service id */
  98                 int item_type_id;       /**< item type */
  99         } sync_agent_da_get_item_id_query_s;
 100
 101 /**
 102  * @brief       Enumerations of option used to fetch framework item id list
 103  */
 104         typedef enum {
 105                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_COLUMN_NAME,                                      /**< get item by column name */
 106                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID,                                     /**< get item by operation id */
 107                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_FOLDER_ID,         /**< get item by operation id and folder id */
 108                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID,      /**< get item by operation id and item type */
 109                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_ITEM_TYPE_ID,                                     /**< get item by item type */
 110                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_ITEM_TYPE_ID_N_ACCOUNT_ID,        /**< get item by item type and account id */
 111                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_FOLDER_ID_N_ACCOUNT_ID            /**< get item by folder id and account id */
 112         } sync_agent_da_get_item_id_list_option_e;
 113
 114 /**
 115  * @brief       Enumerations of common column related to framework item
 116  */
 117         typedef enum {
 118                 SYNC_AGENT_DA_COLUMN_NAME_ACCOUNT_ID,
 119                                                 /**< means column, account_id */
 120                 SYNC_AGENT_DA_COLUMN_NAME_ITEM_ID,
 121                                                 /**< means column, item_id */
 122                 SYNC_AGENT_DA_COLUMN_NAME_SERVICE_ID,
 123                                                 /**< means column, service_id */
 124                 SYNC_AGENT_DA_COLUMN_NAME_ACCESS_NAME,
 125                                                 /**< means column, access_name */
 126
 127                 SYNC_AGENT_DA_COLUMN_NAME_MAX
 128                                         /**< count of common columns */
 129         } sync_agent_da_column_name_e;
 130
 131 /**
 132  * @brief       Structure of query used to fetch framework item id list
 133  */
 134         typedef struct {
 135                 sync_agent_da_get_item_id_list_option_e option;
 136                 sync_agent_da_column_name_e column_name;/**< Column name - SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_COLUMN_NAME */
 137                 int operation_id;       /**< F/W operation id - SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_FOLDER_ID, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID*/
 138                 char *folder_id;/**< F/W folder id - SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_COLUMN_NAME, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_FOLDER_ID */
 139                 int account_id;
 140                         /**< F/W account id - SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_FOLDER_ID, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_ITEM_TYPE_ID_N_ACCOUNT_ID */
 141                 int item_type_id;
 142                                 /**< F/W item type id - SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_FOLDER_ID, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_ITEM_TYPE_ID, SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_ITEM_TYPE_ID_N_ACCOUNT_ID */
 143         } sync_agent_da_get_item_id_list_query_s;
 144
 145 /**
 146  * @brief                       Create initialized framework item instance
 147  * @par Usage:
 148  * @code
 149
 150  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 151  sync_agent_da_item_s *item;
 152
 153  ret = sync_agent_create_item(&item);
 154  if (ret != SYNC_AGENT_DA_SUCCESS) {
 155         ...
 156  }
 157
 158  * @endcode
 159  * @remarks             item in FW corresponds to entity in service layer such as conatct in Contact-service and event in Calendar-service
 160  * @param[out]  sync_agent_item                         framework item instance initialized new
 161  * @return              operation result
 162  * @retval              SYNC_AGENT_DA_SUCCESS           success
 163  * @retval              error_value                                     fail
 164  */
 165         sync_agent_da_return_e sync_agent_create_item(sync_agent_da_item_s ** sync_agent_item);
 166
 167 /**
 168  * @brief                       Add framework item instance into frameowrk db
 169  * @par Usage:
 170  * @code
 171
 172  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 173  sync_agent_da_item_s *item = NULL;
 174  char *item_id = NULL;
 175
 176  ret = sync_agent_create_item(&item);
 177  if (ret != SYNC_AGENT_DA_SUCCESS) {
 178         ...
 179  }
 180
 181  ...
 182
 183  ret = sync_agent_add_item(item, &item_id, true);
 184  if (ret != SYNC_AGENT_DA_SUCCESS) {
 185         ...
 186  }
 187
 188  * @endcode
 189  * @param[in]           sync_agent_item                         framework item instance to add
 190  * @param[out]  item_id                                         id of framework item instance added new
 191  * @param[in]           use_changelog                           option specifying whether use of changelog for sync history
 192  * @return              operation result
 193  * @retval              SYNC_AGENT_DA_SUCCESS           success
 194  * @retval              error_value                                     fail
 195  */
 196         sync_agent_da_return_e sync_agent_add_item(sync_agent_da_item_s * sync_agent_item, char **item_id, int use_changelog);
 197
 198 /**
 199  * @brief                       Update framework item
 200  * @par Usage:
 201  * @code
 202
 203  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 204  sync_agent_da_item_s *item = NULL;
 205
 206  ret = sync_agent_get_item(item_id, &item);
 207  if (ret != SYNC_AGENT_DA_SUCCESS) {
 208         ...
 209  }
 210
 211  ...
 212
 213  ret = sync_agent_update_item(item_id, true);
 214  if (ret != SYNC_AGENT_DA_SUCCESS) {
 215         ...
 216  }
 217
 218  * @endcode
 219  * @remarks             Framework item is just mapped to service item so just has mapping information. Means it doesn't have real service data, and mapping information which framework item has just need to be updated
 220  * @param[in]           item_id                                         id of framework item instance desired to update
 221  * @param[in]           use_changelog                           option specifying whether use of changelog for sync history
 222  * @return              operation result
 223  * @retval              SYNC_AGENT_DA_SUCCESS           success
 224  * @retval              error_value                                     fail
 225  */
 226         sync_agent_da_return_e sync_agent_update_item(char *item_id, int use_changelog);
 227
 228 /**
 229  * @brief                       Delete framework item
 230  * @par Usage:
 231  * @code
 232
 233  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 234
 235  ret = sync_agent_delete_item(item_id, true);
 236  if (ret != SYNC_AGENT_DA_SUCCESS) {
 237         ...
 238  }
 239
 240  * @endcode
 241  * @param[in]           item_id                                         id of framework item instance desired to delete
 242  * @param[in]           use_changelog                           option specifying whether use of changelog for sync history
 243  * @return              operation result
 244  * @retval              SYNC_AGENT_DA_SUCCESS           success
 245  * @retval              error_value                                     fail
 246  */
 247         sync_agent_da_return_e sync_agent_delete_item(char *item_id, int use_changelog);
 248
 249 /**
 250  * @brief                       Delete framework items according to given query in GList form
 251  * @par Usage:
 252  * @code
 253
 254  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 255  sync_agent_da_delete_item_query_s query;
 256
 257  query_item.option = SYNC_AGENT_DA_DELETE_ITEM_OPTION_ITEM_TYPE_ID;
 258  query_item.item_type_id = FW_CONTACT;
 259  query_item.account_id = account_id;
 260
 261  ret = sync_agent_query_delete_item(&query);
 262  if (ret != SYNC_AGENT_DA_SUCCESS) {
 263         ...
 264  }
 265
 266  * @endcode
 267  * @param[in]           query                                           sync_agent_da_delete_item_query_s type of query for delete operation
 268  * @return              operation result
 269  * @retval              SYNC_AGENT_DA_SUCCESS           success
 270  * @retval              error_value                                     fail
 271  */
 272         sync_agent_da_return_e sync_agent_query_delete_item(sync_agent_da_delete_item_query_s * query);
 273
 274 /**
 275  * @brief                       Fetch framework item instance
 276  * @par Usage:
 277  * @code
 278
 279  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 280  sync_agent_da_item_s *item = NULL;
 281
 282  ret = sync_agent_get_item(item_id, &item);
 283  if (ret != SYNC_AGENT_DA_SUCCESS) {
 284         ...
 285  }
 286
 287  * @endcode
 288  * @param[in]           item_id                                         id of framework folder item instance desired to get
 289  * @param[out]  sync_agent_item                         framework item instance fetched
 290  * @return              operation result
 291  * @retval              SYNC_AGENT_DA_SUCCESS           success
 292  * @retval              error_value                                     fail
 293  */
 294         sync_agent_da_return_e sync_agent_get_item(char *item_id, sync_agent_da_item_s ** sync_agent_item);
 295
 296 /**
 297  * @brief                       Fetch framework items according to given query in GList form
 298  * @par Usage:
 299  * @code
 300
 301  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 302  sync_agent_da_get_item_list_query_s query;
 303  GList *item_list = NULL;
 304
 305  query.option = SYNC_AGENT_DA_GET_ITEM_LIST_OPTION_ACCOUNT_ID;
 306  query.item_type_id = FW_CONTACT;
 307
 308  ret = sync_agent_get_item_list(accoutn_id, &query, &item_list);
 309  if (ret != SYNC_AGENT_DA_SUCCESS) {
 310         ...
 311  }
 312
 313  * @endcode
 314  * @param[in]           account_id                                      account id of items desired to get
 315  * @param[in]           query                                           sync_agent_da_get_item_list_query_s type of query for fetch operation
 316  * @param[out]  list                                                    list of framework item instance fetched
 317  * @return              operation result
 318  * @retval              SYNC_AGENT_DA_SUCCESS           success
 319  * @retval              error_value                                     fail
 320  */
 321         sync_agent_da_return_e sync_agent_get_item_list(int account_id, sync_agent_da_get_item_list_query_s * query, GList ** list);
 322
 323 /**
 324  * @brief                       Get framework item id according to given query
 325  * @par Usage:
 326  * @code
 327
 328  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 329  sync_agent_da_get_item_id_query_s query;
 330  char *item_id = NULL;
 331
 332  query.service_id = service_item_id;
 333  query.account_id = account_id;
 334  query.item_type_id = FW_CONTACT;
 335
 336  da_err = sync_agent_get_item_id(&query, &item_id);
 337  if (ret != SYNC_AGENT_DA_SUCCESS) {
 338         ...
 339  }
 340
 341  * @endcode
 342  * @param[in]           query                                           sync_agent_da_get_item_id_query_s type of query for fetch operation
 343  * @param[out]  item_id                                         id of framework item instance requested
 344  * @return              operation result
 345  * @retval              SYNC_AGENT_DA_SUCCESS           success
 346  * @retval              error_value                                     fail
 347  */
 348         sync_agent_da_return_e sync_agent_get_item_id(sync_agent_da_get_item_id_query_s * query, char **item_id);
 349
 350 /**
 351  * @brief                       Get framework item ids according to given query in GList form
 352  * @par Usage:
 353  * @code
 354
 355  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 356  sync_agent_da_get_item_id_list_query_s query;
 357  GList *item_id_list = NULL;
 358
 359  query.option = SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID;
 360  query.account_id = account_id;
 361  query.item_type_id = FW_CONTACT;
 362  query.operation_id = SYNC_AGENT_DA_CHANGE_OPERATION_DELETE;
 363
 364
 365  da_err = sync_agent_get_item_id_list(&query, &item_id_list);
 366  if (ret != SYNC_AGENT_DA_SUCCESS) {
 367         ...
 368  }
 369
 370  * @endcode
 371  * @param[in]           query                                           sync_agent_da_get_item_id_list_query_s type of query for fetch operation
 372  * @param[out]  list                                                    list of framework item id fetched
 373  * @return              operation result
 374  * @retval              SYNC_AGENT_DA_SUCCESS           success
 375  * @retval              error_value                                     fail
 376  */
 377         sync_agent_da_return_e sync_agent_get_item_id_list(sync_agent_da_get_item_id_list_query_s * query, GList ** list);
 378
 379 /**
 380  * @brief                       Free framework item instance provided
 381  * @par Usage:
 382  * @code
 383
 384  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 385  sync_agent_da_item_s *item = NULL;
 386
 387  ret = sync_agent_get_item(item_id, &item);
 388  if (ret != SYNC_AGENT_DA_SUCCESS) {
 389         ...
 390  }
 391
 392  ...
 393
 394  ret = sync_agent_free_item(item);
 395
 396  if (ret != SYNC_AGENT_DA_SUCCESS) {
 397         ...
 398  }
 399
 400  * @endcode
 401  * @param[in]           sync_agent_item                         framework item instance to free
 402  * @return              operation result
 403  * @retval              SYNC_AGENT_DA_SUCCESS           success
 404  * @retval              error_value                                     fail
 405  */
 406         sync_agent_da_return_e sync_agent_free_item(sync_agent_da_item_s * sync_agent_item);
 407
 408 /**
 409  * @brief                       Free framework items provided in GList form
 410  * @par Usage:
 411  * @code
 412
 413  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 414  sync_agent_da_get_item_list_query_s query;
 415  GList *item_list = NULL;
 416
 417  query.option = SYNC_AGENT_DA_GET_ITEM_LIST_OPTION_ACCOUNT_ID;
 418  query.item_type_id = FW_CONTACT;
 419
 420  ret = sync_agent_get_item_list(accoutn_id, &query, &item_list);
 421  if (ret != SYNC_AGENT_DA_SUCCESS) {
 422         ...
 423  }
 424
 425  ...
 426
 427  ret = sync_agent_free_item_list(item_list);
 428  if (ret != SYNC_AGENT_DA_SUCCESS) {
 429         ...
 430  }
 431
 432  * @endcode
 433  * @param[in]           list                                                    framework item instance list to free
 434  * @return              operation result
 435  * @retval              SYNC_AGENT_DA_SUCCESS           success
 436  * @retval              error_value                                     fail
 437  */
 438         sync_agent_da_return_e sync_agent_free_item_list(GList * list);
 439
 440 /**
 441  * @brief                       Free framework item id provided
 442  * @par Usage:
 443  * @code
 444
 445  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 446  sync_agent_da_get_item_id_query_s query;
 447  char *item_id = NULL;
 448
 449  query.service_id = service_item_id;
 450  query.account_id = account_id;
 451  query.item_type_id = FW_CONTACT;
 452
 453  da_err = sync_agent_get_item_id(&query, &item_id);
 454  if (ret != SYNC_AGENT_DA_SUCCESS) {
 455         ...
 456  }
 457
 458  ...
 459
 460  ret = sync_agent_free_item_id(item_id);
 461  if (ret != SYNC_AGENT_DA_SUCCESS) {
 462         ...
 463  }
 464
 465  * @endcode
 466  * @param[in]           item_id                                         framework item id to free
 467  * @return              operation result
 468  * @retval              SYNC_AGENT_DA_SUCCESS           success
 469  * @retval              error_value                                     fail
 470  */
 471         sync_agent_da_return_e sync_agent_free_item_id(char *item_id);
 472
 473 /**
 474  * @brief                       Free framework item id list provided in GList form
 475  * @par Usage:
 476  * @code
 477
 478  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 479  sync_agent_da_get_item_id_list_query_s query;
 480  GList *item_id_list = NULL;
 481
 482  query.option = SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID;
 483  query.account_id = account_id;
 484  query.item_type_id = FW_CONTACT;
 485  query.operation_id = SYNC_AGENT_DA_CHANGE_OPERATION_DELETE;
 486
 487
 488  da_err = sync_agent_get_item_id_list(&query, &item_id_list);
 489  if (ret != SYNC_AGENT_DA_SUCCESS) {
 490         ...
 491  }
 492
 493  ...
 494
 495  ret = sync_agent_free_item_id_list(item_id_list);
 496  if (ret != SYNC_AGENT_DA_SUCCESS) {
 497         ...
 498  }
 499
 500  * @endcode
 501  * @param[in]           list                                                    framework item id list to free
 502  * @return              operation result
 503  * @retval              SYNC_AGENT_DA_SUCCESS           success
 504  * @retval              error_value                                     fail
 505  */
 506         sync_agent_da_return_e sync_agent_free_item_id_list(GList * list);
 507
 508 /**
 509  * @brief               get item count in item table where service type
 510  * @param[in]   data_store_id                           item's service type
 511  * @param[out]  item_count                                      item count for service id
 512  * @return              operation result
 513  * @retval              SYNC_AGENT_DA_SUCCESS           success
 514  * @retval              error_value                                     fail
 515  */
 516         sync_agent_da_return_e sync_agent_get_item_count(int data_store_id, int *item_count);
 517
 518 /**
 519  *      @}
 520  */
 521
 522 #ifdef __cplusplus
 523 }
 524 #endif                          /* __cplusplus */
 525 #endif                          /* INTERFACE_ITEM_H_ */