include/plugin/data_connector_interface.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 DATA_CONNECTOR_INTERFACE_H_
  19 #define DATA_CONNECTOR_INTERFACE_H_
  20
  21 #include "data-adapter/error.h"
  22
  23 #include "data_connector_resource.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif                          /* __cplusplus */
  28
  29 /**
  30  * @file data_connector_interface.h
  31  * @brief       Interface list in this header will be implemented plugIn developer.
  32  * @remarks Implementation will operate sync-agent-framework data-adapter module.
  33  */
  34
  35 /** @addtogroup plugin_dataconnector DataConnector Domain
  36  * @ingroup plugin
  37  *      @{
  38  */
  39
  40 /**
  41  * API to connect(open) to the service
  42  *
  43  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
  44  *
  45  * @par Since:
  46  *
  47  *
  48  * @see sync_agent_plugin_open_service()
  49  *
  50  */
  51         sync_agent_da_return_e sync_agent_plugin_open_service(void);
  52
  53 /**
  54  * API to disconnect(close) to the service
  55  *
  56  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
  57  *
  58  * @par Since:
  59  *
  60  *
  61  * @see sync_agent_plugin_close_service()
  62  *
  63  */
  64         sync_agent_da_return_e sync_agent_plugin_close_service(void);
  65
  66 /**
  67  * API to start transaction for service storage
  68  *
  69  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
  70  *
  71  * @par Since:
  72  *
  73  *
  74  * @see sync_agent_plugin_begin_transaction()
  75  *
  76  */
  77         sync_agent_da_return_e sync_agent_plugin_begin_transaction(void);
  78
  79 /**
  80  * API to end transaction for service storage
  81  *
  82  * @param[in] is_success flag to decide commit/rollback (1:commit, 0:rollback)
  83  *
  84  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
  85  *
  86  * @par Since:
  87  *
  88  *
  89  * @see sync_agent_plugin_end_transaction(int)
  90  *
  91  */
  92         sync_agent_da_return_e sync_agent_plugin_end_transaction(int is_success);
  93
  94 /**
  95  * API to insert item into service storage
  96  *
  97  * @param[in] account_id service account id
  98  * @param[in] folder_id service folder id
  99  * @param[in] data data to add to the service
 100  * @param[in] item_id as returned by sync_agent_plugin_add_item() - success : id of the newly item added to the service, error : NULL
 101  *
 102  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 103  *
 104  * @par Since:
 105  *
 106  *
 107  * @see sync_agent_plugin_add_item(int, char *, void *, char **)
 108  *
 109  */
 110         sync_agent_da_return_e sync_agent_plugin_add_item(int account_id, char *folder_id, void *data, char **item_id);
 111
 112 /**
 113  * API to insert item into service storage
 114  *
 115  * @param[in] account_id service account id
 116  * @param[in] folder_id service folder id
 117  * @param[in] data data to add to the service
 118  * @param[in] item_id as returned by sync_agent_plugin_add_bulk_item() - success : id of the newly item added to the service, error : NULL
 119  *
 120  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 121  *
 122  * @par Since:
 123  *
 124  *
 125  * @see sync_agent_plugin_add_bulk_item(int, char *, void *, int **, int *)
 126  *
 127  */
 128         sync_agent_da_return_e sync_agent_plugin_add_bulk_item(int account_id, char *folder_id, void *data, int **item_id, int *item_id_count);
 129
 130 /**
 131  * API to update item from service storage
 132  *
 133  * @param[in] account_id service account id
 134  * @param[in] folder_id service folder id
 135  * @param[in] item_id service item id
 136  * @param[in] data data to update to the service
 137  *
 138  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 139  *
 140  * @par Since:
 141  *
 142  *
 143  * @see sync_agent_plugin_update_item(int, char *, char *, void *)
 144  *
 145  */
 146         sync_agent_da_return_e sync_agent_plugin_update_item(int account_id, char *folder_id, char *item_id, void *data);
 147
 148 /**
 149  * API to update item from service storage
 150  *
 151  * @param[in] data data to update to the service
 152  *
 153  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 154  *
 155  * @par Since:
 156  *
 157  *
 158  * @see sync_agent_plugin_update_bulk_item(void *)
 159  *
 160  */
 161         sync_agent_da_return_e sync_agent_plugin_update_bulk_item(void *data);
 162
 163 /**
 164  * API to delete item from service storage
 165  *
 166  * @param[in] account_id service account id
 167  * @param[in] folder_id service folder id
 168  * @param[in]   item_id service id of item expected to be deleted
 169  *
 170  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 171  *
 172  * @par Since:
 173  *
 174  *
 175  * @see sync_agent_plugin_delete_item(int, char *, char *)
 176  *
 177  */
 178         sync_agent_da_return_e sync_agent_plugin_delete_item(int account_id, char *folder_id, char *item_id);
 179
 180 /**
 181  * API to delete item from service storage
 182  *
 183  * @param[in]   item_id service id of item expected to be deleted
 184  * @param[in]   count   count of service item id expected to be deleted
 185  *
 186  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 187  *
 188  * @par Since:
 189  *
 190  *
 191  * @see sync_agent_plugin_delete_bulk_item(int *, int)
 192  *
 193  */
 194         sync_agent_da_return_e sync_agent_plugin_delete_bulk_item(int *item_id, int count);
 195
 196
 197 /**
 198  * API to delete all items from service storage
 199  *
 200  * @param[in] account_id service account id
 201  *
 202  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 203  *
 204  * @par Since:
 205  *
 206  *
 207  * @see sync_agent_plugin_delete_all_items(int)
 208  *
 209  */
 210         sync_agent_da_return_e sync_agent_plugin_delete_all_items(int account_id);
 211
 212 /**
 213  * API to get item from service storage
 214  *
 215  * @param[in]   account_id service account id
 216  * @param[in]   folder_id service folder id
 217  * @param[in]   item_id expected to get service item id
 218  * @param[in]   data as returned by sync_agent_plugin_get_item() - success : item info, error : NULL
 219  *
 220  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 221  *
 222  * @par Since:
 223  *
 224  *
 225  * @see sync_agent_plugin_get_item(int, char *, char *, void **)
 226  *
 227  */
 228         sync_agent_da_return_e sync_agent_plugin_get_item(int account_id, char *folder_id, char *item_id, void **data);
 229
 230 /**
 231  * API to insert folder into service storage
 232  *
 233  * @param[in]   account_id service account id
 234  * @param[in]   folder_name folder name
 235  * @param[in] folder_type folder type
 236  * @param[in] folder_id as returned by sync_agent_plugin_add_folder() - success : id of the newly folder added to the service, fail : NULL
 237  *
 238  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 239  *
 240  * @par Since:
 241  *
 242  *
 243  * @see sync_agent_plugin_add_folder(int, char *, int, char **)
 244  *
 245  */
 246         sync_agent_da_return_e sync_agent_plugin_add_folder(int account_id, char *folder_name, int folder_type, char **folder_id);
 247
 248 /**
 249  * API to delete folder from service storage
 250  *
 251  * @param[in]   account_id service account id
 252  * @param[in]   folder_id service folder id
 253  *
 254  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 255  *
 256  * @par Since:
 257  *
 258  *
 259  * @see sync_agent_plugin_delete_folder(int, char *)
 260  *
 261  */
 262         sync_agent_da_return_e sync_agent_plugin_delete_folder(int account_id, char *folder_id);
 263
 264 /**
 265  * API to get folder info from service storage
 266  *
 267  * @param[in] account_id service account id
 268  * @param[in] folder_id service folder id
 269  * @param[in]   out_folder_name as returned by sync_agent_plugin_get_folder() - success : folder name, fail : NULL
 270  * @param[in]   out_folder_type as returned by sync_agent_plugin_get_folder() - success : folder type, fail : -1
 271  *
 272  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 273  *
 274  * @par Since:
 275  *
 276  *
 277  * @see sync_agent_plugin_get_folder(int, char *, char **, int *)
 278  *
 279  */
 280         sync_agent_da_return_e sync_agent_plugin_get_folder(int account_id, char *folder_id, char **out_folder_name, int *out_folder_type);
 281
 282 /**
 283  * API to execute data into service
 284  *
 285  * @param[in]   account_id service account id
 286  * @param[in]   execute_key execute key
 287  * @param[in]   execute_values execute values
 288  * @param[in]   result as returned by sync_agent_plugin_execute() -     extension result info
 289  *
 290  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 291  *
 292  * @par Since:
 293  *
 294  *
 295  * @see sync_agent_plugin_execute(int, const char *, void *, void **)
 296  *
 297  */
 298         sync_agent_da_return_e sync_agent_plugin_execute(int account_id, const char *execute_key, void *execute_values, void **result);
 299
 300 /**
 301  * API to get item used count
 302  *
 303  * @return current_item_count on success, negative value on error
 304  *
 305  * @par Since:
 306  *
 307  *
 308  * @see sync_agent_plugin_get_used_item_count()
 309  *
 310  */
 311         int sync_agent_plugin_get_used_item_count(void);
 312
 313 /**
 314  * API to get item used count for folder
 315  *
 316  * @param[in] account_id service account id
 317  * @param[in]   folder_id service folder id
 318  *
 319  * @return current_item_count on success, negative value on error
 320  *
 321  * @par Since:
 322  *
 323  *
 324  * @see sync_agent_plugin_get_used_item_count_for_folder(int, char *)
 325  *
 326  */
 327         int sync_agent_plugin_get_used_item_count_for_folder(int account_id, char *folder_id);
 328
 329 /**
 330  * API to get folder id list of a account
 331  *
 332  * @param[in]   account_id service account id
 333  * @param[in]   folder_count as returned by sync_agent_plugin_get_folder_id_list() - success : folder count,    fail or not exist : 0
 334  * @param[in] folder_type_list as returned by sync_agent_plugin_get_folder_id_list() - success : list,  fail or not exist : NULL
 335  *
 336  * @return folder_id_list on success, NULL on error or not exist
 337  *
 338  * @par Since:
 339  *
 340  *
 341  * @see sync_agent_plugin_get_folder_id_list(int, int *, int **)
 342  *
 343  */
 344         char **sync_agent_plugin_get_folder_id_list(int account_id, int *folder_count, int **folder_type_list);
 345
 346 /**
 347  * API to get all account id list that service has currently
 348  *
 349  * @param[in] count as returned by sync_agent_plugin_get_account_id_list() - success : count of account id,     fail or not exist : 0
 350  * @return account_id_list on success, NULL on fail or not exist
 351  *
 352  * @par Since:
 353  *
 354  *
 355  * @see sync_agent_plugin_get_account_id_list(int *)
 356  *
 357  */
 358         int *sync_agent_plugin_get_account_id_list(int *count);
 359
 360 /**
 361  * API to write data store items to file
 362  *
 363  * @param[in] account_id service account id
 364  * @param[in] file_path as returned by sync_agent_plugin_backup_service_items_to_file() - written file path
 365  *
 366  * @return SYNC_AGENT_DA_SUCCESS on success, minus value on error
 367  *
 368  * @par Since:
 369  *
 370  *
 371  * @see sync_agent_plugin_backup_service_items_to_file(int, char **)
 372  *
 373  */
 374         sync_agent_da_return_e sync_agent_plugin_backup_service_items_to_file(int account_id, char **file_path);
 375
 376 /**
 377  * API to add file wrote item to data store
 378  *
 379  * @param[in] account_id service account id
 380  * @param[in] file_path file path
 381  *
 382  * @return SYNC_AGENT_DA_SUCCESS on success, minus value on error
 383  *
 384  * @par Since:
 385  *
 386  *
 387  * @see sync_agent_plugin_restore_service_items_from_file(int, const char *)
 388  *
 389  */
 390         sync_agent_da_return_e sync_agent_plugin_restore_service_items_from_file(int account_id, const char *file_path);
 391
 392 /**
 393  * API to get added item list after specific point
 394  *
 395  * @param[in] account_id service account id
 396  * @param[in]   folder_id service folder id
 397  * @param[in]   changepoint     specific point
 398  * @param[in] changeCount as returned by sync_agent_plugin_get_changed_item_for_folder_add() - success : added item count, fail or not exist : NULL
 399  *
 400  * @return added_item_info_list (if exist) on success, NULL on error or not exist
 401  *
 402  * @par Since:
 403  *
 404  *
 405  * @see sync_agent_plugin_get_changed_item_for_folder_add(int, const char *, int, int *)
 406  *
 407  */
 408         sync_agent_plugin_item_node_s *sync_agent_plugin_get_changed_item_for_folder_add(int account_id, const char *folder_id, int changepoint, int *changeCount);
 409
 410 /**
 411  * API to get deleted item list after specific point
 412  *
 413  * @param[in] account_id service account id
 414  * @param[in]   folder_id service folder id
 415  * @param[in]   changepoint specific point
 416  * @param[in]   changeCount     as returned by sync_agent_plugin_get_changed_item_for_folder_delete() - success : deleted item count, fail or not exist : NULL
 417  *
 418  * @return deleted_item_info_list       (if exist) on success, NULL on error or not exist
 419  *
 420  * @par Since:
 421  *
 422  *
 423  * @see sync_agent_plugin_get_changed_item_for_folder_delete(int, const char *, int, int *)
 424  *
 425  */
 426         sync_agent_plugin_item_node_s *sync_agent_plugin_get_changed_item_for_folder_delete(int account_id, const char *folder_id, int changepoint, int *changeCount);
 427
 428 /**
 429  * API to get updated item list after specific point
 430  *
 431  * @param[in]   account_id service account id
 432  * @param[in]   folder_id service folder id
 433  * @param[in]   changepoint specific point
 434  * @param[in]   changeCount as returned by sync_agent_plugin_get_changed_item_for_folder_update() - success : updated item count, fail or not exist : NULL
 435  *
 436  * @return updated_item_info_list       (if exist) on success, NULL on error or not exist
 437  *
 438  * @par Since:
 439  *
 440  *
 441  * @see sync_agent_plugin_get_changed_item_for_folder_update(int, const char *, int, int *)
 442  *
 443  */
 444         sync_agent_plugin_item_node_s *sync_agent_plugin_get_changed_item_for_folder_update(int account_id, const char *folder_id, int changepoint, int *changeCount);
 445
 446 /**
 447  * API to get last storage change point information
 448  *
 449  * @return last storage changing point information on success, 0 on error
 450  *
 451  * @par Since:
 452  *
 453  *
 454  * @see sync_agent_plugin_get_last_change_point()
 455  *
 456  */
 457         int sync_agent_plugin_get_last_change_point(void);
 458
 459 /**
 460  * API to check notification for the storage change
 461  *
 462  * @param[in] data user data
 463  *
 464  * @par Since:
 465  *
 466  *
 467  * @see sync_agent_plugin_start_listening_change_noti(void *)
 468  *
 469  */
 470         void sync_agent_plugin_start_listening_change_noti(void *data);
 471
 472 /**
 473  * API to set callback function to handle added item to storage
 474  *
 475  * @param[in] callback callback function - this function is provided from sync-agent-framework
 476  *
 477  * @par Since:
 478  *
 479  *
 480  * @see data_connector_resource.h
 481  *
 482  */
 483         void sync_agent_plugin_set_callback_add_item(sync_agent_add_item_cb_plugin callback);
 484
 485 /**
 486  * API to set callback function to handle deleted item to storage
 487  *
 488  * @param[in] callback callback function - this function is provided from sync-agent-framework
 489  *
 490  * @par Since:
 491  *
 492  *
 493  * @see data_connector_resource.h
 494  *
 495  */
 496         void sync_agent_plugin_set_callback_delete_item(sync_agent_del_item_cb_plugin callback);
 497
 498 /**
 499  * API to set callback function to handle updated item to storage
 500  *
 501  * @param[in] callback callback function - this function is provided from sync-agent-framework
 502  *
 503  * @par Since:
 504  *
 505  *
 506  * @see data_connector_resource.h
 507  *
 508  */
 509         void sync_agent_plugin_set_callback_update_item(sync_agent_update_item_cb_plugin callback);
 510
 511 /**
 512  * API to set callback function to get service account id list mapped sync-agent-framework account id
 513  *
 514  * @param[in]   callback callback function - this function is provided from sync-agent-framework
 515  *
 516  * @par Since:
 517  *
 518  *
 519  * @see data_connector_resource.h
 520  *
 521  */
 522         void sync_agent_plugin_set_callback_get_account_id_list(sync_agent_get_account_id_list_cb_plugin callback);
 523
 524 /**
 525  * API to get max item count per folder
 526  *
 527  * @param[in] folder_type folder type provided plugin
 528  *
 529  * @return max item count on success, -1 on error
 530  *
 531  * @par Since:
 532  *
 533  *
 534  * @see sync_agent_plugin_get_max_item_count(int)
 535  */
 536         int sync_agent_plugin_get_max_item_count(int folder_type);
 537
 538 /**
 539  * API to get service data's available field length
 540  *
 541  * @param[in] field_name field_name provided data-connector plugin
 542  * @param[in]   child_field_name child field name provided data-connector plugin
 543  *
 544  * @return available_field_length       on success, -1 on error
 545  *
 546  * @par Since:
 547  *
 548  *
 549  * @see sync_agent_plugin_get_max_field_length(int, int)
 550  *
 551  */
 552         int sync_agent_plugin_get_max_field_length(int field_name, int child_field_name);
 553
 554 /**
 555  * API to get service data's available field count
 556  *
 557  * @param[in] field_name field_name provided data-connector plugin
 558  * @param[in]   child_field_name child field name provided data-connector plugin
 559  *
 560  * @return available_field_count on success, -1 on error
 561  *
 562  * @par Since:
 563  *
 564  *
 565  * @see sync_agent_plugin_get_max_field_count(int, int)
 566  *
 567  */
 568         int sync_agent_plugin_get_max_field_count(int field_name, int child_field_name);
 569
 570 /**
 571  * API to get service data's available field value's domain
 572  *
 573  * @param[in]   field_name field name provided data-connector plugin
 574  * @param[in]   child_field_name child field name provided data-connector plugin
 575  * @param[in]   str_val as returned by sync_agent_plugin_get_field_value() - when domain value is string
 576  * @param[in]   num_val1 as returned by sync_agent_plugin_get_field_value() - when domain value is integer (ex minimum value)
 577  * @param[in]   num_val2 as returned by sync_agent_plugin_get_field_value() - when domain value is integer (ex maximum value)
 578  *
 579  * @return 1 on success, -1 on error
 580  *
 581  * @par Since:
 582  *
 583  *
 584  * @see sync_agent_plugin_get_field_value(int, int, char **, int *, int *)
 585  *
 586  */
 587         int sync_agent_plugin_get_field_value(int field_name, int child_field_name, char **str_val, int *num_val1, int *num_val2);
 588
 589 /**
 590  * API to get service data's available field count
 591  *
 592  * @param[in]   feature feature provided data-connector plugin
 593  *
 594  * @return 1 : support, 0 : not support on success, -1 on error
 595  *
 596  * @par Since:
 597  *
 598  *
 599  * @see sync_agent_plugin_get_is_support_feature(int)
 600  *
 601  */
 602         int sync_agent_plugin_get_is_support_feature(int feature);
 603
 604 /**
 605  *      @}
 606  */
 607 #ifdef __cplusplus
 608 }
 609 #endif                          /* __cplusplus */
 610 #endif                          /* DATA_CONNECTOR_INTERFACE_H_ */