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 update item from service storage
 114  *
 115  * @param[in] account_id service account id
 116  * @param[in] folder_id service folder id
 117  * @param[in] item_id service item id
 118  * @param[in] data data to update to the service
 119  *
 120  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 121  *
 122  * @par Since:
 123  *
 124  *
 125  * @see sync_agent_plugin_update_item(int, char *, char *, void *)
 126  *
 127  */
 128         sync_agent_da_return_e sync_agent_plugin_update_item(int account_id, char *folder_id, char *item_id, void *data);
 129
 130 /**
 131  * API to delete 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 id of item expected to be deleted
 136  *
 137  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 138  *
 139  * @par Since:
 140  *
 141  *
 142  * @see sync_agent_plugin_delete_item(int, char *, char *)
 143  *
 144  */
 145         sync_agent_da_return_e sync_agent_plugin_delete_item(int account_id, char *folder_id, char *item_id);
 146
 147 /**
 148  * API to delete all items from service storage
 149  *
 150  * @param[in] account_id service account id
 151  *
 152  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 153  *
 154  * @par Since:
 155  *
 156  *
 157  * @see sync_agent_plugin_delete_all_items(int)
 158  *
 159  */
 160         sync_agent_da_return_e sync_agent_plugin_delete_all_items(int account_id);
 161
 162 /**
 163  * API to get item from service storage
 164  *
 165  * @param[in]   account_id service account id
 166  * @param[in]   folder_id service folder id
 167  * @param[in]   item_id expected to get service item id
 168  * @param[in]   data as returned by sync_agent_plugin_get_item() - success : item info, error : NULL
 169  *
 170  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 171  *
 172  * @par Since:
 173  *
 174  *
 175  * @see sync_agent_plugin_get_item(int, char *, char *, void **)
 176  *
 177  */
 178         sync_agent_da_return_e sync_agent_plugin_get_item(int account_id, char *folder_id, char *item_id, void **data);
 179
 180 /**
 181  * API to insert folder into service storage
 182  *
 183  * @param[in]   account_id service account id
 184  * @param[in]   folder_name folder name
 185  * @param[in] folder_type folder type
 186  * @param[in] folder_id as returned by sync_agent_plugin_add_folder() - success : id of the newly folder added to the service, fail : NULL
 187  *
 188  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 189  *
 190  * @par Since:
 191  *
 192  *
 193  * @see sync_agent_plugin_add_folder(int, char *, int, char **)
 194  *
 195  */
 196         sync_agent_da_return_e sync_agent_plugin_add_folder(int account_id, char *folder_name, int folder_type, char **folder_id);
 197
 198 /**
 199  * API to delete folder from service storage
 200  *
 201  * @param[in]   account_id service account id
 202  * @param[in]   folder_id service folder id
 203  *
 204  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 205  *
 206  * @par Since:
 207  *
 208  *
 209  * @see sync_agent_plugin_delete_folder(int, char *)
 210  *
 211  */
 212         sync_agent_da_return_e sync_agent_plugin_delete_folder(int account_id, char *folder_id);
 213
 214 /**
 215  * API to get folder info from service storage
 216  *
 217  * @param[in] account_id service account id
 218  * @param[in] folder_id service folder id
 219  * @param[in]   out_folder_name as returned by sync_agent_plugin_get_folder() - success : folder name, fail : NULL
 220  * @param[in]   out_folder_type as returned by sync_agent_plugin_get_folder() - success : folder type, fail : -1
 221  *
 222  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 223  *
 224  * @par Since:
 225  *
 226  *
 227  * @see sync_agent_plugin_get_folder(int, char *, char **, int *)
 228  *
 229  */
 230         sync_agent_da_return_e sync_agent_plugin_get_folder(int account_id, char *folder_id, char **out_folder_name, int *out_folder_type);
 231
 232 /**
 233  * API to execute data into service
 234  *
 235  * @param[in]   account_id service account id
 236  * @param[in]   execute_key execute key
 237  * @param[in]   execute_values execute values
 238  * @param[in]   result as returned by sync_agent_plugin_execute() -     extension result info
 239  *
 240  * @return SYNC_AGENT_DA_SUCCESS on success, otherwise error
 241  *
 242  * @par Since:
 243  *
 244  *
 245  * @see sync_agent_plugin_execute(int, const char *, void *, void **)
 246  *
 247  */
 248         sync_agent_da_return_e sync_agent_plugin_execute(int account_id, const char *execute_key, void *execute_values, void **result);
 249
 250 /**
 251  * API to get item used count
 252  *
 253  * @return current_item_count on success, negative value on error
 254  *
 255  * @par Since:
 256  *
 257  *
 258  * @see sync_agent_plugin_get_used_item_count()
 259  *
 260  */
 261         int sync_agent_plugin_get_used_item_count(void);
 262
 263 /**
 264  * API to get item used count for folder
 265  *
 266  * @param[in] account_id service account id
 267  * @param[in]   folder_id service folder id
 268  *
 269  * @return current_item_count on success, negative value on error
 270  *
 271  * @par Since:
 272  *
 273  *
 274  * @see sync_agent_plugin_get_used_item_count_for_folder(int, char *)
 275  *
 276  */
 277         int sync_agent_plugin_get_used_item_count_for_folder(int account_id, char *folder_id);
 278
 279 /**
 280  * API to get folder id list of a account
 281  *
 282  * @param[in]   account_id service account id
 283  * @param[in]   folder_count as returned by sync_agent_plugin_get_folder_id_list() - success : folder count,    fail or not exist : 0
 284  * @param[in] folder_type_list as returned by sync_agent_plugin_get_folder_id_list() - success : list,  fail or not exist : NULL
 285  *
 286  * @return folder_id_list on success, NULL on error or not exist
 287  *
 288  * @par Since:
 289  *
 290  *
 291  * @see sync_agent_plugin_get_folder_id_list(int, int *, int **)
 292  *
 293  */
 294         char **sync_agent_plugin_get_folder_id_list(int account_id, int *folder_count, int **folder_type_list);
 295
 296 /**
 297  * API to get all account id list that service has currently
 298  *
 299  * @param[in] count as returned by sync_agent_plugin_get_account_id_list() - success : count of account id,     fail or not exist : 0
 300  * @return account_id_list on success, NULL on fail or not exist
 301  *
 302  * @par Since:
 303  *
 304  *
 305  * @see sync_agent_plugin_get_account_id_list(int *)
 306  *
 307  */
 308         int *sync_agent_plugin_get_account_id_list(int *count);
 309
 310 /**
 311  * API to write data store items to file
 312  *
 313  * @param[in] account_id service account id
 314  * @param[in] file_path as returned by sync_agent_plugin_backup_service_items_to_file() - written file path
 315  *
 316  * @return SYNC_AGENT_DA_SUCCESS on success, minus value on error
 317  *
 318  * @par Since:
 319  *
 320  *
 321  * @see sync_agent_plugin_backup_service_items_to_file(int, char **)
 322  *
 323  */
 324         sync_agent_da_return_e sync_agent_plugin_backup_service_items_to_file(int account_id, char **file_path);
 325
 326 /**
 327  * API to add file wrote item to data store
 328  *
 329  * @param[in] account_id service account id
 330  * @param[in] file_path file path
 331  *
 332  * @return SYNC_AGENT_DA_SUCCESS on success, minus value on error
 333  *
 334  * @par Since:
 335  *
 336  *
 337  * @see sync_agent_plugin_restore_service_items_from_file(int, const char *)
 338  *
 339  */
 340         sync_agent_da_return_e sync_agent_plugin_restore_service_items_from_file(int account_id, const char *file_path);
 341
 342 /**
 343  * API to get added item list after specific point
 344  *
 345  * @param[in] account_id service account id
 346  * @param[in]   folder_id service folder id
 347  * @param[in]   changepoint     specific point
 348  * @param[in] changeCount as returned by sync_agent_plugin_get_changed_item_for_folder_add() - success : added item count, fail or not exist : NULL
 349  *
 350  * @return added_item_info_list (if exist) on success, NULL on error or not exist
 351  *
 352  * @par Since:
 353  *
 354  *
 355  * @see sync_agent_plugin_get_changed_item_for_folder_add(int, const char *, int, int *)
 356  *
 357  */
 358         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);
 359
 360 /**
 361  * API to get deleted item list after specific point
 362  *
 363  * @param[in] account_id service account id
 364  * @param[in]   folder_id service folder id
 365  * @param[in]   changepoint specific point
 366  * @param[in]   changeCount     as returned by sync_agent_plugin_get_changed_item_for_folder_delete() - success : deleted item count, fail or not exist : NULL
 367  *
 368  * @return deleted_item_info_list       (if exist) on success, NULL on error or not exist
 369  *
 370  * @par Since:
 371  *
 372  *
 373  * @see sync_agent_plugin_get_changed_item_for_folder_delete(int, const char *, int, int *)
 374  *
 375  */
 376         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);
 377
 378 /**
 379  * API to get updated item list after specific point
 380  *
 381  * @param[in]   account_id service account id
 382  * @param[in]   folder_id service folder id
 383  * @param[in]   changepoint specific point
 384  * @param[in]   changeCount as returned by sync_agent_plugin_get_changed_item_for_folder_update() - success : updated item count, fail or not exist : NULL
 385  *
 386  * @return updated_item_info_list       (if exist) on success, NULL on error or not exist
 387  *
 388  * @par Since:
 389  *
 390  *
 391  * @see sync_agent_plugin_get_changed_item_for_folder_update(int, const char *, int, int *)
 392  *
 393  */
 394         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);
 395
 396 /**
 397  * API to get last storage change point information
 398  *
 399  * @return last storage changing point information on success, 0 on error
 400  *
 401  * @par Since:
 402  *
 403  *
 404  * @see sync_agent_plugin_get_last_change_point()
 405  *
 406  */
 407         int sync_agent_plugin_get_last_change_point(void);
 408
 409 /**
 410  * API to check notification for the storage change
 411  *
 412  * @param[in] data user data
 413  *
 414  * @par Since:
 415  *
 416  *
 417  * @see sync_agent_plugin_start_listening_change_noti(void *)
 418  *
 419  */
 420         void sync_agent_plugin_start_listening_change_noti(void *data);
 421
 422 /**
 423  * API to set callback function to handle added item to storage
 424  *
 425  * @param[in] callback callback function - this function is provided from sync-agent-framework
 426  *
 427  * @par Since:
 428  *
 429  *
 430  * @see data_connector_resource.h
 431  *
 432  */
 433         void sync_agent_plugin_set_callback_add_item(sync_agent_add_item_cb_plugin callback);
 434
 435 /**
 436  * API to set callback function to handle deleted item to storage
 437  *
 438  * @param[in] callback callback function - this function is provided from sync-agent-framework
 439  *
 440  * @par Since:
 441  *
 442  *
 443  * @see data_connector_resource.h
 444  *
 445  */
 446         void sync_agent_plugin_set_callback_delete_item(sync_agent_del_item_cb_plugin callback);
 447
 448 /**
 449  * API to set callback function to handle updated item to storage
 450  *
 451  * @param[in] callback callback function - this function is provided from sync-agent-framework
 452  *
 453  * @par Since:
 454  *
 455  *
 456  * @see data_connector_resource.h
 457  *
 458  */
 459         void sync_agent_plugin_set_callback_update_item(sync_agent_update_item_cb_plugin callback);
 460
 461 /**
 462  * API to set callback function to get service account id list mapped sync-agent-framework account id
 463  *
 464  * @param[in]   callback callback function - this function is provided from sync-agent-framework
 465  *
 466  * @par Since:
 467  *
 468  *
 469  * @see data_connector_resource.h
 470  *
 471  */
 472         void sync_agent_plugin_set_callback_get_account_id_list(sync_agent_get_account_id_list_cb_plugin callback);
 473
 474 /**
 475  * API to get max item count per folder
 476  *
 477  * @param[in] folder_type folder type provided plugin
 478  *
 479  * @return max item count on success, -1 on error
 480  *
 481  * @par Since:
 482  *
 483  *
 484  * @see sync_agent_plugin_get_max_item_count(int)
 485  */
 486         int sync_agent_plugin_get_max_item_count(int folder_type);
 487
 488 /**
 489  * API to get service data's available field length
 490  *
 491  * @param[in] field_name field_name provided data-connector plugin
 492  * @param[in]   child_field_name child field name provided data-connector plugin
 493  *
 494  * @return available_field_length       on success, -1 on error
 495  *
 496  * @par Since:
 497  *
 498  *
 499  * @see sync_agent_plugin_get_max_field_length(int, int)
 500  *
 501  */
 502         int sync_agent_plugin_get_max_field_length(int field_name, int child_field_name);
 503
 504 /**
 505  * API to get service data's available field count
 506  *
 507  * @param[in] field_name field_name provided data-connector plugin
 508  * @param[in]   child_field_name child field name provided data-connector plugin
 509  *
 510  * @return available_field_count on success, -1 on error
 511  *
 512  * @par Since:
 513  *
 514  *
 515  * @see sync_agent_plugin_get_max_field_count(int, int)
 516  *
 517  */
 518         int sync_agent_plugin_get_max_field_count(int field_name, int child_field_name);
 519
 520 /**
 521  * API to get service data's available field value's domain
 522  *
 523  * @param[in]   field_name field name provided data-connector plugin
 524  * @param[in]   child_field_name child field name provided data-connector plugin
 525  * @param[in]   str_val as returned by sync_agent_plugin_get_field_value() - when domain value is string
 526  * @param[in]   num_val1 as returned by sync_agent_plugin_get_field_value() - when domain value is integer (ex minimum value)
 527  * @param[in]   num_val2 as returned by sync_agent_plugin_get_field_value() - when domain value is integer (ex maximum value)
 528  *
 529  * @return 1 on success, -1 on error
 530  *
 531  * @par Since:
 532  *
 533  *
 534  * @see sync_agent_plugin_get_field_value(int, int, char **, int *, int *)
 535  *
 536  */
 537         int sync_agent_plugin_get_field_value(int field_name, int child_field_name, char **str_val, int *num_val1, int *num_val2);
 538
 539 /**
 540  * API to get service data's available field count
 541  *
 542  * @param[in]   feature feature provided data-connector plugin
 543  *
 544  * @return 1 : support, 0 : not support on success, -1 on error
 545  *
 546  * @par Since:
 547  *
 548  *
 549  * @see sync_agent_plugin_get_is_support_feature(int)
 550  *
 551  */
 552         int sync_agent_plugin_get_is_support_feature(int feature);
 553
 554 /**
 555  *      @}
 556  */
 557 #ifdef __cplusplus
 558 }
 559 #endif                          /* __cplusplus */
 560 #endif                          /* DATA_CONNECTOR_INTERFACE_H_ */