include/data-adapter/interface_service_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_SERVICE_ITEM_H_
  19 #define INTERFACE_SERVICE_ITEM_H_
  20
  21 #include "common.h"
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif                          /* __cplusplus */
  26
  27 /**
  28  * @file                interface_service_item.h
  29  * @brief       Support to use service storage
  30  */
  31
  32 /** @addtogroup data_adapter
  33  *      @{
  34  */
  35
  36 /**
  37  * @brief       Structure of framework service item instance
  38  */
  39         typedef struct {
  40                 char *item_id;          /** service item id */
  41                 int content_type;               /** content type of service item */
  42                 int account_id;         /** service account id */
  43                 char *folder_id;                /** service folder id to which service item mapped to */
  44                 char *access_name;      /** name of accessor */
  45                 const void *data;               /** void pointer type of service data */
  46         } sync_agent_da_service_item_s;
  47
  48 /**
  49  * @brief       Structure of framework service folder instance
  50  */
  51         typedef struct {
  52                 char *folder_id;                /** service folder id */
  53                 char *folder_name;      /** name of service folder */
  54                 int folder_type;                /** type of service folder */
  55         } sync_agent_da_service_folder_s;
  56
  57 /**
  58  * @brief       Structure of query used to delete framework service item
  59  */
  60         typedef struct {
  61                 int content_type;       /**< type of content to delete */
  62                 int account_id; /**< id of the account desired to delete */
  63         } sync_agent_da_delete_service_item_query_s;
  64
  65 /**
  66  * @brief                               Open service database
  67  * @par Usage:
  68  * @code
  69
  70  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
  71
  72  ret = sync_agent_open_service(FW_CONTACT);
  73  if (ret != SYNC_AGENT_DA_SUCCESS) {
  74         ...
  75  }
  76
  77  * @endcode
  78  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
  79  * @return                      operation result
  80  * @retval                      SYNC_AGENT_DA_SUCCESS                   success
  81  * @retval                      error_value                                             fail
  82  */
  83         sync_agent_da_return_e sync_agent_open_service(int content_type);
  84
  85 /**
  86  * @brief                               Close service database
  87  * @par Usage:
  88  * @code
  89
  90  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
  91
  92  ret = sync_agent_close_service(FW_CONTACT);
  93  if (ret != SYNC_AGENT_DA_SUCCESS) {
  94         ...
  95  }
  96
  97  * @endcode
  98  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
  99  * @return                      operation result
 100  * @retval                      SYNC_AGENT_DA_SUCCESS                   success
 101  * @retval                      error_value                                             fail
 102  */
 103         sync_agent_da_return_e sync_agent_close_service(int content_type);
 104
 105 /**
 106  * @brief                               Start transaction for service database
 107  * @par Usage:
 108  * @code
 109
 110  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 111
 112  ret = sync_agent_begin_service(FW_CONTACT);
 113  if (ret != SYNC_AGENT_DA_SUCCESS) {
 114         ...
 115  }
 116
 117  * @endcode
 118  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
 119  * @return                      operation result
 120  * @retval                      SYNC_AGENT_DA_SUCCESS                   success
 121  * @retval                      error_value                                             fail
 122  */
 123         sync_agent_da_return_e sync_agent_begin_service(int content_type);
 124
 125 /**
 126  * @brief                               End transaction for service database
 127  * @par Usage:
 128  * @code
 129
 130  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 131
 132  ret = sync_agent_end_service(FW_CONTACT, false);       //transaction rollback by 'false'
 133  if (ret != SYNC_AGENT_DA_SUCCESS) {
 134         ...
 135  }
 136
 137  * @endcode
 138  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
 139  * @param[in]                   is_success                                              1 : commit, 0 : rollback
 140  * @return                      operation result
 141  * @retval                      SYNC_AGENT_DA_SUCCESS                   success
 142  * @retval                      error_value                                             fail
 143  */
 144         sync_agent_da_return_e sync_agent_end_service(int content_type, int is_success);
 145
 146 /**
 147 * @brief                                Create initialized framework service item instance
 148 * @par Usage:
 149 * @code
 150
 151 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 152 sync_agent_da_service_item_s *service_item = NULL;
 153
 154 ret = sync_agent_create_service_item(&service_item);
 155 if (ret != SYNC_AGENT_DA_SUCCESS) {
 156    ...
 157 }
 158
 159 * @endcode
 160 * @param[out]           service_item                                            sync_agent_da_service_item_s type of framework service item instance newly initialied
 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_service_item(sync_agent_da_service_item_s ** service_item);
 166
 167 /**
 168 * @brief                                Create initialized framework service folder instance
 169 * @par Usage:
 170 * @code
 171
 172 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 173 sync_agent_da_service_folder_s *service_folder = NULL;
 174
 175 ret = sync_agent_create_service_folder(&service_folder);
 176 if (ret != SYNC_AGENT_DA_SUCCESS) {
 177    ...
 178 }
 179
 180 * @endcode
 181 * @param[out]           service_folder                                          sync_agent_da_service_folder_s type of framework service folder instance newly initialied
 182 * @return                       operation result
 183 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 184 * @retval                               error_value                                             fail
 185 */
 186         sync_agent_da_return_e sync_agent_create_service_folder(sync_agent_da_service_folder_s ** service_folder);
 187
 188 /**
 189 * @brief                                Free framework service item instance provided
 190 * @par Usage:
 191 * @code
 192
 193 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 194 sync_agent_da_service_item_s *service_item = NULL;
 195
 196 ret = sync_agent_create_service_item(&service_item);
 197 if (ret != SYNC_AGENT_DA_SUCCESS) {
 198    ...
 199 }
 200
 201 ...
 202
 203 ret = sync_agent_free_service_item(service_item);
 204 if (ret != SYNC_AGENT_DA_SUCCESS) {
 205    ...
 206 }
 207
 208 * @endcode
 209 * @param[in]                    service_item                                            sync_agent_da_service_item_s type of framework service item instance to free
 210 * @return                       operation result
 211 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 212 * @retval                               error_value                                             fail
 213 */
 214         sync_agent_da_return_e sync_agent_free_service_item(sync_agent_da_service_item_s * service_item);
 215
 216 /**
 217 * @brief                                Free framework service folder instance provided
 218 * @par Usage:
 219 * @code
 220
 221 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 222 sync_agent_da_service_folder_s *service_folder = NULL;
 223
 224 ret = sync_agent_create_service_folder(&service_folder);
 225 if (ret != SYNC_AGENT_DA_SUCCESS) {
 226    ...
 227 }
 228
 229 ...
 230
 231 ret = sync_agent_free_service_folder(&service_folder);
 232 if (ret != SYNC_AGENT_DA_SUCCESS) {
 233    ...
 234 }
 235
 236 * @endcode
 237 * @param[in]                    service_folder                                          sync_agent_da_service_folder_s type of framework service folder instance to free
 238 * @return                       operation result
 239 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 240 * @retval                               error_value                                             fail
 241 */
 242         sync_agent_da_return_e sync_agent_free_service_folder(sync_agent_da_service_folder_s * service_folder);
 243
 244 /**
 245 * @brief                                Add framework service item instance into frameowrk db
 246 * @par Usage:
 247 * @code
 248
 249 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 250 sync_agent_da_service_item_s *service_item = NULL;
 251 char *item_id = NULL;
 252
 253 ret = sync_agent_create_service_item(&service_item);
 254 if (ret != SYNC_AGENT_DA_SUCCESS) {
 255    ...
 256 }
 257
 258 ...
 259
 260 ret = sync_agent_add_service_item(service_item, &item_id, true);
 261 if (ret != SYNC_AGENT_DA_SUCCESS) {
 262    ...
 263 }
 264
 265 * @endcode
 266 * @param[in]                    service_item                                            sync_agent_da_service_item_s type of framework service item instance to add into framework db
 267 * @param[out]           item_id                                                 id of framework service item instance added new
 268 * @param[in]                    update_changelog                                        option specifying whether use of changelog for sync history
 269 * @return                       operation result
 270 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 271 * @retval                               error_value                                             fail
 272 */
 273         sync_agent_da_return_e sync_agent_add_service_item(sync_agent_da_service_item_s * service_item, char **item_id, bool update_changelog);
 274
 275
 276 /**
 277 * @brief                                Add framework service item instance into frameowrk db
 278 * @par Usage:
 279 * @code
 280
 281 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 282 sync_agent_da_service_item_s *service_item = NULL;
 283 char *item_id = NULL;
 284
 285 ret = sync_agent_create_service_item(&service_item);
 286 if (ret != SYNC_AGENT_DA_SUCCESS) {
 287    ...
 288 }
 289
 290 ...
 291
 292 ret = sync_agent_add_service_bulk_item(service_item, &item_id, true);
 293 if (ret != SYNC_AGENT_DA_SUCCESS) {
 294    ...
 295 }
 296
 297 * @endcode
 298 * @param[in]                    service_item                                            sync_agent_da_service_item_s type of framework service item instance to add into framework db
 299 * @param[out]           item_id                                                 id of framework service item instance added new
 300 * @param[in]                    update_changelog                                        option specifying whether use of changelog for sync history
 301 * @return                       operation result
 302 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 303 * @retval                               error_value                                             fail
 304 */
 305         sync_agent_da_return_e sync_agent_add_service_bulk_item(sync_agent_da_service_item_s *service_item, char **item_id, bool update_changelog);
 306
 307 /**
 308 * @brief                                Update framework service item on framework db
 309 * @par Usage:
 310 * @code
 311
 312 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 313 sync_agent_da_service_item_s *service_item = NULL;
 314
 315 ret = sync_agent_get_service_item(item_id, &service_item);
 316 if (ret != SYNC_AGENT_DA_SUCCESS) {
 317    ...
 318 }
 319
 320 ...
 321
 322 ret = sync_agent_update_service_item(service_item, item_id, true);
 323 if (ret != SYNC_AGENT_DA_SUCCESS) {
 324    ...
 325 }
 326
 327 * @endcode
 328 * @param[in]                    service_item                                            sync_agent_da_service_item_s type of framework service item instance to update into framework db
 329 * @param[in]                    item_id                                                 id of framework service item instance desired to update
 330 * @param[in]                    update_changelog                                        option specifying whether use of changelog for sync history
 331 * @return                       operation result
 332 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 333 * @retval                               error_value                                             fail
 334 */
 335         sync_agent_da_return_e sync_agent_update_service_item(sync_agent_da_service_item_s * service_item, char *item_id, bool update_changelog);
 336
 337 /**
 338 * @brief                                Update framework service item on framework db
 339 * @par Usage:
 340 * @code
 341
 342 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 343 sync_agent_da_service_item_s *service_item = NULL;
 344
 345 ret = sync_agent_get_service_item(item_id, &service_item);
 346 if (ret != SYNC_AGENT_DA_SUCCESS) {
 347    ...
 348 }
 349
 350 ...
 351
 352 ret = sync_agent_update_service_bulk_item(service_item, &item_id, true);
 353 if (ret != SYNC_AGENT_DA_SUCCESS) {
 354    ...
 355 }
 356
 357 * @endcode
 358 * @param[in]                    service_item                                            sync_agent_da_service_item_s type of framework service item instance to update into framework db
 359 * @param[in]                    item_id                                                 id of framework service item instance desired to update
 360 * @param[in]                    update_changelog                                        option specifying whether use of changelog for sync history
 361 * @return                       operation result
 362 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 363 * @retval                               error_value                                             fail
 364 */
 365         sync_agent_da_return_e sync_agent_update_service_bulk_item(sync_agent_da_service_item_s *service_item, char **item_id, bool update_changelog);
 366
 367 /**
 368 * @brief                                Delete framework service item instance from frameowrk db
 369 * @par Usage:
 370 * @code
 371
 372 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 373
 374 ret = sync_agent_delete_service_item(item_id, true);
 375 if (ret != SYNC_AGENT_DA_SUCCESS) {
 376    ...
 377 }
 378
 379 * @endcode
 380 * @param[in]                    item_id                                                 id of framework service item instance desired to delete
 381 * @param[in]                    update_changelog                                        option specifying whether use of changelog for sync history
 382 * @return                       operation result
 383 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 384 * @retval                               error_value                                             fail
 385 */
 386         sync_agent_da_return_e sync_agent_delete_service_item(char *item_id, bool update_changelog);
 387
 388 /**
 389 * @brief                                Delete framework service item instance from frameowrk db
 390 * @par Usage:
 391 * @code
 392
 393 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 394
 395 ret = sync_agent_delete_service_bulk_item(item_id, true);
 396 if (ret != SYNC_AGENT_DA_SUCCESS) {
 397    ...
 398 }
 399
 400 * @endcode
 401 * @param[in]                    item_id                                                 id of framework service item instance desired to delete
 402 * @param[in]                    update_changelog                                        option specifying whether use of changelog for sync history
 403 * @return                       operation result
 404 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 405 * @retval                               error_value                                     fail
 406 */
 407         sync_agent_da_return_e sync_agent_delete_service_bulk_item(char **item_id, int count, bool update_changelog);
 408
 409
 410 /**
 411 * @brief                                Delete framework service item instance from frameowrk db using query option
 412 * @par Usage:
 413 * @code
 414
 415 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 416 sync_agent_da_delete_service_item_query_s query;
 417
 418 query.content_type = FW_CONTACT;
 419 query.account_id = account_id;
 420
 421 ret = sync_agent_query_delete_service_items(&query);
 422 if (ret != SYNC_AGENT_DA_SUCCESS) {
 423    ...
 424 }
 425
 426 * @endcode
 427 * @param[in]                    query                                                   sync_agent_da_delete_service_item_query_s type of query for delete operation
 428 * @return                       operation result
 429 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 430 * @retval                               error_value                                             fail
 431 */
 432         sync_agent_da_return_e sync_agent_query_delete_service_items(sync_agent_da_delete_service_item_query_s * query);
 433
 434 /**
 435 * @brief                                Fetch framework service item from framework db
 436 * @par Usage:
 437 * @code
 438
 439 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 440 sync_agent_da_service_item_s *service_item = NULL;
 441
 442 ret = sync_agent_get_service_item(item_id, &service_item);
 443 if (ret != SYNC_AGENT_DA_SUCCESS) {
 444    ...
 445 }
 446
 447 * @endcode
 448 * @param[in]                    item_id                                                 id of framework service item instance desired to get
 449 * @param[out]           service_item                                            framework service item instance fetched
 450 * @return                       operation result
 451 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 452 * @retval                               error_value                                             fail
 453 */
 454         sync_agent_da_return_e sync_agent_get_service_item(char *item_id, sync_agent_da_service_item_s ** service_item);
 455
 456 /**
 457 * @brief                                Fetch framework service folder from framework db
 458 * @par Usage:
 459 * @code
 460
 461 sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 462 sync_agent_da_service_folder_s *service_folder = NULL;
 463
 464 ret = sync_agent_get_service_folder(folder_id, &service_folder);
 465 if (ret != SYNC_AGENT_DA_SUCCESS) {
 466    ...
 467 }
 468
 469 * @endcode
 470 * @param[in]                    folder_id                                                       id of framework service folder instance desired to get
 471 * @param[out]           service_folder                                          framework service folder instance fetched
 472 * @return                       operation result
 473 * @retval                               SYNC_AGENT_DA_SUCCESS                   success
 474 * @retval                               error_value                                             fail
 475 */
 476         sync_agent_da_return_e sync_agent_get_service_folder(char *folder_id, sync_agent_da_service_folder_s ** service_folder);
 477
 478 /**
 479  * @brief                               Execute predefined operation through plug-in
 480  * @par Usage:
 481  * @code
 482
 483  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 484  char *msg = get_msg_body();
 485  bool *result = NULL;
 486
 487  ret = sync_agent_execute_service(FW_SMS, account_id, "send_msg", msg, &result);
 488  if (ret != SYNC_AGENT_DA_SUCCESS) {
 489         ...
 490  }
 491
 492  * @endcode
 493  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
 494  * @param[in]                   account_id                                              F/W account id
 495  * @param[in]                   execute_key                                             execute key
 496  * @param[in]                   execute_values                                  execute values
 497  * @param[out]          result                                                  extension result info
 498  * @return                      operation result
 499  * @retval                      SYNC_AGENT_DA_SUCCESS                   success
 500  * @retval                      error_value                                             fail
 501  */
 502         sync_agent_da_return_e sync_agent_execute_service(int content_type, int account_id, const char *execute_key, void *execute_values, void **result);
 503
 504 /**
 505  * @brief                               Get item used count
 506  * @par Usage:
 507  * @code
 508
 509  int count = 0;
 510
 511  count = sync_agent_get_used_service_item_count(FW_CONTACT);
 512  if (count == 0) {
 513         ...
 514  } else {
 515         ...
 516  }
 517
 518  * @endcode
 519  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
 520  * @return                      operation result
 521  * @retval                      current item count                                      success
 522  * @retval                      error value                                             fail
 523  */
 524         int sync_agent_get_used_service_item_count(int content_type);
 525
 526 /**
 527  * @brief                               Get item used count for folder
 528  * @par Usage:
 529  * @code
 530
 531  int count = 0;
 532
 533  count = sync_agent_get_used_service_item_count_for_folder(FW_CONTACT, account_id, folder_id);
 534  if (count == 0) {
 535         ...
 536  } else {
 537         ...
 538  }
 539
 540  * @endcode
 541  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
 542  * @param[in]                   account_id                                              F/W account id
 543  * @param[in]                   folder_id       F/W                                             folder id
 544  * @return                      operation result
 545  * @retval                      current item count                                      success
 546  * @retval                      error value                                             fail
 547  */
 548         int sync_agent_get_used_service_item_count_for_folder(int content_type, int account_id, char *folder_id);
 549
 550 /**
 551  * @brief                               Write data store items to file
 552  * @par Usage:
 553  * @code
 554
 555  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 556
 557  ret = sync_agent_backup_service_items_to_file(FW_CONTACT, account_id, "/tmp/contact_backup");
 558  if (ret != SYNC_AGENT_DA_SUCCESS) {
 559         ...
 560  }
 561
 562  * @endcode
 563  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
 564  * @param[in]                   account_id                                              F/W account id
 565  * @param[out]          file_path                                                       written file path
 566  * @return                      operation result
 567  * @retval                      SYNC_AGENT_DA_SUCCESS                   success
 568  * @retval                      error value                                             fail
 569  */
 570         sync_agent_da_return_e sync_agent_backup_service_items_to_file(int content_type, int account_id, char **file_path);
 571
 572 /**
 573  * @brief                               Add file-written item to data store
 574  * @par Usage:
 575  * @code
 576
 577  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
 578
 579  ret = sync_agent_restore_service_items_from_file(FW_CONTACT, account_id, "/tmp/contact_backup");
 580  if (ret != SYNC_AGENT_DA_SUCCESS) {
 581         ...
 582  }
 583
 584  * @endcode
 585  * @param[in]                   content_type                                            service type - service data connector plug-in's ID described in F/W config file
 586  * @param[in]                   account_id                                              F/W account id
 587  * @param[in]                   file_path                                                       file path
 588  * @return                      operation result
 589  * @retval                      SYNC_AGENT_DA_SUCCESS                   success
 590  * @retval                      error_value                                             fail
 591  */
 592         sync_agent_da_return_e sync_agent_restore_service_items_from_file(int content_type, int account_id, const char *file_path);
 593
 594 /**
 595  * @brief                               Get service item id from framework service item id
 596  * @par Usage:
 597  * @code
 598
 599  char *item_id = NULL;
 600
 601  item_id = sync_agent_get_service_item_id(framework_item_id);
 602  if (item_id != NULL) {
 603         ...
 604  }
 605
 606  * @endcode
 607  * @param[in]                   item_id                                                 item id
 608  * @return                      operation result
 609  * @retval                      service_item_id                                 success
 610  * @retval                      0                                                               fail
 611  */
 612         char *sync_agent_get_service_item_id(char *item_id);
 613
 614 /**
 615  * @brief                               Get service folder id from framework service folder id
 616  * @par Usage:
 617  * @code
 618
 619  char *folder_id = NULL;
 620
 621  folder_id = sync_agent_get_service_folder_id(framework_folder_id);
 622  if (folder_id != NULL) {
 623         ...
 624  }
 625
 626  * @endcode
 627  * @param[in]                   folder_id                                                       folder id
 628  * @return                      operation result
 629  * @retval                      service_folder_id                                       success
 630  * @retval                      0                                                               fail
 631  */
 632         char *sync_agent_get_service_folder_id(char *folder_id);
 633
 634 /**
 635  *      @}
 636  */
 637
 638 #ifdef __cplusplus
 639 }
 640 #endif
 641 #endif                          /* INTERFACE_SERVICE_ITEM_H_ */