[Internal: merge sync-agent]
[platform/core/system/sync-agent.git] / 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;                          /**< F/W item id */
41                 int data_store_id;                      /**< service data connector pluIn's ID described in F/W config file  */
42                 int account_id;                         /**< F/W account id */
43                 char *folder_id;                        /**< F/W folder id */
44                 char *service_id;                       /**< service item id */
45                 char *parent_service_id;        /**< parent F/W item id for exdate items => normal item : NULL / exdate parent item : -1 / exdate child item : parent service id */
46                 char *access_name;                      /**< name of accessor */
47         } sync_agent_da_item_s;
48
49 /**
50  * @brief       Enumerations of option used to delete framework item
51  */
52         typedef enum {
53                 SYNC_AGENT_DA_DELETE_ITEM_OPTION_ITEM_TYPE_ID,
54                                                         /**< delete item by item type */
55         } sync_agent_da_delete_item_option_e;
56
57 /**
58  * @brief       Structure of query used to delete framework item
59  */
60         typedef struct {
61                 sync_agent_da_delete_item_option_e option;
62                 int account_id;
63                         /**< F/W account id - SYNC_AGENT_DA_DELETE_ITEM_OPTION_ITEM_TYPE_ID */
64                 int item_type_id;
65                                 /**< F/W item type id - SYNC_AGENT_DA_DELETE_ITEM_OPTION_ITEM_TYPE_ID */
66         } sync_agent_da_delete_item_query_s;
67
68 /**
69  * @brief       Enumerations of option used to fetch framework item list
70  */
71         typedef enum {
72                 SYNC_AGENT_DA_GET_ITEM_LIST_OPTION_ACCOUNT_ID,          /**< get item by account id */
73                 SYNC_AGENT_DA_GET_ITEM_LIST_OPTION_SERVICE_ID_MAPPING,
74                                                                 /**< get item by service id */
75         } sync_agent_da_get_item_list_option_e;
76
77 /**
78  * @brief       Structure of query used to fetch framework item list
79  */
80         typedef struct {
81                 sync_agent_da_get_item_list_option_e option;
82                 int item_type_id;
83                                 /**< F/W item type id - SYNC_AGENT_DA_ITEM_GET_LIST_OPTION_ACCOUNT_ID */
84                 char *item_id;
85                         /**< F/W item id - SYNC_AGENT_DA_ITEM_GET_LIST_OPTION_SERVICE_ID_MAPPING */
86         } sync_agent_da_get_item_list_query_s;
87
88 /**
89  * @brief       Structure of query used to fetch framework item id
90  */
91         typedef struct {
92                 int account_id; /**< account id */
93                 char *service_id;       /**< service id */
94                 int item_type_id;       /**< item type */
95         } sync_agent_da_get_item_id_query_s;
96
97 /**
98  * @brief       Enumerations of option used to fetch framework item id list
99  */
100         typedef enum {
101                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_COLUMN_NAME,                                      /**< get item by column name */
102                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID,                                     /**< get item by operation id */
103                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_FOLDER_ID,         /**< get item by operation id and folder id */
104                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID,      /**< get item by operation id and item type */
105                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_ITEM_TYPE_ID,                                     /**< get item by item type */
106                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_ITEM_TYPE_ID_N_ACCOUNT_ID,        /**< get item by item type and account id */
107                 SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_FOLDER_ID_N_ACCOUNT_ID            /**< get item by folder id and account id */
108         } sync_agent_da_get_item_id_list_option_e;
109
110 /**
111  * @brief       Enumerations of common column related to framework item
112  */
113         typedef enum {
114                 SYNC_AGENT_DA_COLUMN_NAME_ACCOUNT_ID,
115                                                 /**< means column, account_id */
116                 SYNC_AGENT_DA_COLUMN_NAME_ITEM_ID,
117                                                 /**< means column, item_id */
118                 SYNC_AGENT_DA_COLUMN_NAME_SERVICE_ID,
119                                                 /**< means column, service_id */
120                 SYNC_AGENT_DA_COLUMN_NAME_ACCESS_NAME,
121                                                 /**< means column, access_name */
122
123                 SYNC_AGENT_DA_COLUMN_NAME_MAX
124                                         /**< count of common columns */
125         } sync_agent_da_column_name_e;
126
127 /**
128  * @brief       Structure of query used to fetch framework item id list
129  */
130         typedef struct {
131                 sync_agent_da_get_item_id_list_option_e option;
132                 sync_agent_da_column_name_e column_name;/**< Column name - SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_COLUMN_NAME */
133                 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*/
134                 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 */
135                 int account_id;
136                         /**< 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 */
137                 int item_type_id;
138                                 /**< 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 */
139         } sync_agent_da_get_item_id_list_query_s;
140
141 /**
142  * @brief                       Create initialized framework item instance
143  * @par Usage:
144  * @code
145  
146  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
147  sync_agent_da_item_s *item;
148  
149  ret = sync_agent_create_item(&item);
150  if (ret != SYNC_AGENT_DA_SUCCESS) {
151         ...
152  }
153  
154  * @endcode
155  * @remarks             item in FW corresponds to entity in service layer such as conatct in Contact-service and event in Calendar-service
156  * @param[out]  sync_agent_item                         framework item instance initialized new
157  * @return              operation result
158  * @retval              SYNC_AGENT_DA_SUCCESS           success
159  * @retval              error_value                                     fail
160  */
161         sync_agent_da_return_e sync_agent_create_item(sync_agent_da_item_s ** sync_agent_item);
162
163 /**
164  * @brief                       Add framework item instance into frameowrk db
165  * @par Usage:
166  * @code
167  
168  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
169  sync_agent_da_item_s *item = NULL;
170  char *item_id = NULL;
171
172  ret = sync_agent_create_item(&item);
173  if (ret != SYNC_AGENT_DA_SUCCESS) {
174         ...
175  }
176
177  ...
178  
179  ret = sync_agent_add_item(item, &item_id, true);
180  if (ret != SYNC_AGENT_DA_SUCCESS) {
181         ...
182  }
183  
184  * @endcode
185  * @param[in]           sync_agent_item                         framework item instance to add
186  * @param[out]  item_id                                         id of framework item instance added new
187  * @param[in]           use_changelog                           option specifying whether use of changelog for sync history
188  * @return              operation result
189  * @retval              SYNC_AGENT_DA_SUCCESS           success
190  * @retval              error_value                                     fail
191  */
192         sync_agent_da_return_e sync_agent_add_item(sync_agent_da_item_s * sync_agent_item, char **item_id, int use_changelog);
193
194 /**
195  * @brief                       Update framework item
196  * @par Usage:
197  * @code
198  
199  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
200  sync_agent_da_item_s *item = NULL;
201
202  ret = sync_agent_get_item(item_id, &item);
203  if (ret != SYNC_AGENT_DA_SUCCESS) {
204         ...
205  }
206
207  ...
208
209  ret = sync_agent_update_item(item_id, true);
210  if (ret != SYNC_AGENT_DA_SUCCESS) {
211         ...
212  }
213
214  * @endcode
215  * @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
216  * @param[in]           item_id                                         id of framework item instance desired to update
217  * @param[in]           use_changelog                           option specifying whether use of changelog for sync history
218  * @return              operation result
219  * @retval              SYNC_AGENT_DA_SUCCESS           success
220  * @retval              error_value                                     fail
221  */
222         sync_agent_da_return_e sync_agent_update_item(char *item_id, int use_changelog);
223
224 /**
225  * @brief                       Delete framework item
226  * @par Usage:
227  * @code
228  
229  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
230
231  ret = sync_agent_delete_item(item_id, true);
232  if (ret != SYNC_AGENT_DA_SUCCESS) {
233         ...
234  }
235
236  * @endcode
237  * @param[in]           item_id                                         id of framework item instance desired to delete
238  * @param[in]           use_changelog                           option specifying whether use of changelog for sync history
239  * @return              operation result
240  * @retval              SYNC_AGENT_DA_SUCCESS           success
241  * @retval              error_value                                     fail
242  */
243         sync_agent_da_return_e sync_agent_delete_item(char *item_id, int use_changelog);
244
245 /**
246  * @brief                       Delete framework items according to given query in GList form
247  * @par Usage:
248  * @code
249  
250  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
251  sync_agent_da_delete_item_query_s query;
252
253  query_item.option = SYNC_AGENT_DA_DELETE_ITEM_OPTION_ITEM_TYPE_ID;
254  query_item.item_type_id = FW_CONTACT;
255  query_item.account_id = account_id;
256
257  ret = sync_agent_query_delete_item(&query);
258  if (ret != SYNC_AGENT_DA_SUCCESS) {
259         ...
260  }
261
262  * @endcode
263  * @param[in]           query                                           sync_agent_da_delete_item_query_s type of query for delete operation
264  * @return              operation result
265  * @retval              SYNC_AGENT_DA_SUCCESS           success
266  * @retval              error_value                                     fail
267  */
268         sync_agent_da_return_e sync_agent_query_delete_item(sync_agent_da_delete_item_query_s * query);
269
270 /**
271  * @brief                       Fetch framework item instance
272  * @par Usage:
273  * @code
274  
275  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
276  sync_agent_da_item_s *item = NULL;
277
278  ret = sync_agent_get_item(item_id, &item);
279  if (ret != SYNC_AGENT_DA_SUCCESS) {
280         ...
281  }
282
283  * @endcode
284  * @param[in]           item_id                                         id of framework folder item instance desired to get
285  * @param[out]  sync_agent_item                         framework item instance fetched
286  * @return              operation result
287  * @retval              SYNC_AGENT_DA_SUCCESS           success
288  * @retval              error_value                                     fail
289  */
290         sync_agent_da_return_e sync_agent_get_item(char *item_id, sync_agent_da_item_s ** sync_agent_item);
291
292 /**
293  * @brief                       Get data store item id
294  * @par Usage:
295  * @code
296
297  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
298  sync_agent_da_item_s *item = NULL;
299
300  ret = sync_agent_get_item_data_store_id(item_id, &item);
301  if (ret != SYNC_AGENT_DA_SUCCESS) {
302         ...
303  }
304
305  * @endcode
306  * @param[in]           item_id                                         id of framework folder item instance desired to get
307  * @param[out]  sync_agent_item                         framework item instance fetched
308  * @return              operation result
309  * @retval              SYNC_AGENT_DA_SUCCESS           success
310  * @retval              error_value                                     fail
311  */
312         sync_agent_da_return_e sync_agent_get_item_data_store_id(char *item_id, sync_agent_da_item_s ** sync_agent_item);
313
314 /**
315  * @brief                       Get account item id
316  * @par Usage:
317  * @code
318
319  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
320  sync_agent_da_item_s *item = NULL;
321
322  ret = sync_agent_get_item_account_id(item_id, &item);
323  if (ret != SYNC_AGENT_DA_SUCCESS) {
324         ...
325  }
326
327  * @endcode
328  * @param[in]           item_id                                         id of framework folder item instance desired to get
329  * @param[out]  sync_agent_item                         framework item instance fetched
330  * @return              operation result
331  * @retval              SYNC_AGENT_DA_SUCCESS           success
332  * @retval              error_value                                     fail
333  */
334         sync_agent_da_return_e sync_agent_get_item_account_id(char *item_id, sync_agent_da_item_s ** sync_agent_item);
335
336 /**
337  * @brief                       Fetch framework items according to given query in GList form
338  * @par Usage:
339  * @code
340  
341  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
342  sync_agent_da_get_item_list_query_s query;
343  GList *item_list = NULL;
344
345  query.option = SYNC_AGENT_DA_GET_ITEM_LIST_OPTION_ACCOUNT_ID;
346  query.item_type_id = FW_CONTACT;
347
348  ret = sync_agent_get_item_list(accoutn_id, &query, &item_list);
349  if (ret != SYNC_AGENT_DA_SUCCESS) {
350         ...
351  }
352
353  * @endcode
354  * @param[in]           account_id                                      account id of items desired to get
355  * @param[in]           query                                           sync_agent_da_get_item_list_query_s type of query for fetch operation
356  * @param[out]  list                                                    list of framework item instance fetched
357  * @return              operation result
358  * @retval              SYNC_AGENT_DA_SUCCESS           success
359  * @retval              error_value                                     fail
360  */
361         sync_agent_da_return_e sync_agent_get_item_list(int account_id, sync_agent_da_get_item_list_query_s * query, GList ** list);
362
363 /**
364  * @brief                       Get framework item id according to given query
365  * @par Usage:
366  * @code
367  
368  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
369  sync_agent_da_get_item_id_query_s query;
370  char *item_id = NULL;
371
372  query.service_id = service_item_id;
373  query.account_id = account_id;
374  query.item_type_id = FW_CONTACT;
375
376  da_err = sync_agent_get_item_id(&query, &item_id);
377  if (ret != SYNC_AGENT_DA_SUCCESS) {
378         ...
379  }
380
381  * @endcode
382  * @param[in]           query                                           sync_agent_da_get_item_id_query_s type of query for fetch operation
383  * @param[out]  item_id                                         id of framework item instance requested
384  * @return              operation result
385  * @retval              SYNC_AGENT_DA_SUCCESS           success
386  * @retval              error_value                                     fail
387  */
388         sync_agent_da_return_e sync_agent_get_item_id(sync_agent_da_get_item_id_query_s * query, char **item_id);
389
390 /**
391  * @brief                       Get framework item ids according to given query in GList form
392  * @par Usage:
393  * @code
394  
395  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
396  sync_agent_da_get_item_id_list_query_s query;
397  GList *item_id_list = NULL;
398
399  query.option = SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID;
400  query.account_id = account_id;
401  query.item_type_id = FW_CONTACT;
402  query.operation_id = SYNC_AGENT_DA_CHANGE_OPERATION_DELETE;
403  
404
405  da_err = sync_agent_get_item_id_list(&query, &item_id_list);
406  if (ret != SYNC_AGENT_DA_SUCCESS) {
407         ...
408  }
409
410  * @endcode
411  * @param[in]           query                                           sync_agent_da_get_item_id_list_query_s type of query for fetch operation
412  * @param[out]  list                                                    list of framework item id fetched
413  * @return              operation result
414  * @retval              SYNC_AGENT_DA_SUCCESS           success
415  * @retval              error_value                                     fail
416  */
417         sync_agent_da_return_e sync_agent_get_item_id_list(sync_agent_da_get_item_id_list_query_s * query, GList ** list);
418
419 /**
420  * @brief                       Free framework item instance provided
421  * @par Usage:
422  * @code
423  
424  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
425  sync_agent_da_item_s *item = NULL;
426
427  ret = sync_agent_get_item(item_id, &item);
428  if (ret != SYNC_AGENT_DA_SUCCESS) {
429         ...
430  }
431
432  ...
433
434  ret = sync_agent_free_item(item);
435  
436  if (ret != SYNC_AGENT_DA_SUCCESS) {
437         ...
438  }
439
440  * @endcode
441  * @param[in]           sync_agent_item                         framework item instance to free
442  * @return              operation result
443  * @retval              SYNC_AGENT_DA_SUCCESS           success
444  * @retval              error_value                                     fail
445  */
446         sync_agent_da_return_e sync_agent_free_item(sync_agent_da_item_s * sync_agent_item);
447
448 /**
449  * @brief                       Free framework items provided in GList form
450  * @par Usage:
451  * @code
452  
453  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
454  sync_agent_da_get_item_list_query_s query;
455  GList *item_list = NULL;
456
457  query.option = SYNC_AGENT_DA_GET_ITEM_LIST_OPTION_ACCOUNT_ID;
458  query.item_type_id = FW_CONTACT;
459
460  ret = sync_agent_get_item_list(accoutn_id, &query, &item_list);
461  if (ret != SYNC_AGENT_DA_SUCCESS) {
462         ...
463  }
464
465  ...
466
467  ret = sync_agent_free_item_list(item_list);
468  if (ret != SYNC_AGENT_DA_SUCCESS) {
469         ...
470  }
471
472  * @endcode
473  * @param[in]           list                                                    framework item instance list to free
474  * @return              operation result
475  * @retval              SYNC_AGENT_DA_SUCCESS           success
476  * @retval              error_value                                     fail
477  */
478         sync_agent_da_return_e sync_agent_free_item_list(GList * list);
479
480 /**
481  * @brief                       Free framework item id provided
482  * @par Usage:
483  * @code
484  
485  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
486  sync_agent_da_get_item_id_query_s query;
487  char *item_id = NULL;
488
489  query.service_id = service_item_id;
490  query.account_id = account_id;
491  query.item_type_id = FW_CONTACT;
492
493  da_err = sync_agent_get_item_id(&query, &item_id);
494  if (ret != SYNC_AGENT_DA_SUCCESS) {
495         ...
496  }
497
498  ...
499
500  ret = sync_agent_free_item_id(item_id);
501  if (ret != SYNC_AGENT_DA_SUCCESS) {
502         ...
503  }
504
505  * @endcode
506  * @param[in]           item_id                                         framework item id to free
507  * @return              operation result
508  * @retval              SYNC_AGENT_DA_SUCCESS           success
509  * @retval              error_value                                     fail
510  */
511         sync_agent_da_return_e sync_agent_free_item_id(char *item_id);
512
513 /**
514  * @brief                       Free framework item id list provided in GList form
515  * @par Usage:
516  * @code
517  
518  sync_agent_da_return_e ret = SYNC_AGENT_DA_ERRORS;
519  sync_agent_da_get_item_id_list_query_s query;
520  GList *item_id_list = NULL;
521
522  query.option = SYNC_AGENT_DA_GET_ITEM_ID_LIST_OPTION_OPERATION_ID_N_ITEM_TYPE_ID;
523  query.account_id = account_id;
524  query.item_type_id = FW_CONTACT;
525  query.operation_id = SYNC_AGENT_DA_CHANGE_OPERATION_DELETE;
526  
527
528  da_err = sync_agent_get_item_id_list(&query, &item_id_list);
529  if (ret != SYNC_AGENT_DA_SUCCESS) {
530         ...
531  }
532
533  ...
534
535  ret = sync_agent_free_item_id_list(item_id_list);
536  if (ret != SYNC_AGENT_DA_SUCCESS) {
537         ...
538  }
539
540  * @endcode
541  * @param[in]           list                                                    framework item id list to free
542  * @return              operation result
543  * @retval              SYNC_AGENT_DA_SUCCESS           success
544  * @retval              error_value                                     fail
545  */
546         sync_agent_da_return_e sync_agent_free_item_id_list(GList * list);
547
548 /**
549  * @brief               get item count in item table where service type
550  * @param[in]   data_store_id                           item's service type
551  * @param[out]  item_count                                      item count for service id
552  * @return              operation result
553  * @retval              SYNC_AGENT_DA_SUCCESS           success
554  * @retval              error_value                                     fail
555  */
556         sync_agent_da_return_e sync_agent_get_item_count(int data_store_id, int *item_count);
557
558 /**
559  * @brief                       get updated exdate item id list in item table where service type
560  * @param[in]           fw_id                                           item's framework id
561  * @param[in]           list                                                    list as returned updated exdate item_id list
562  * @return              sync_agent_da_return_e
563  * @retval              SYNC_AGENT_DA_SUCCESS           success
564  * @retval              error value                                     fail
565
566  */
567         sync_agent_da_return_e sync_agent_get_updated_exdate_item_id_list(char *fw_id, GList ** list);
568
569 /**
570  *      @}
571  */
572
573 #ifdef __cplusplus
574 }
575 #endif                          /* __cplusplus */
576 #endif                          /* INTERFACE_ITEM_H_ */