include/data-adapter/interface_folder.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_FOLDER_H_
  19 #define INTERFACE_FOLDER_H_
  20
  21 #include "error.h"
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif                          /* __cplusplus */
  26
  27 /**
  28  * @file                interface_folder.h
  29  * @brief               Support to store folder item into framework
  30  */
  31
  32 /** @addtogroup data_adapter
  33  *      @{
  34  */
  35
  36 /**
  37  * @brief       Structure of framework folder item instance
  38  */
  39         typedef struct {
  40                 char *folder_id;                /**< F/W folder 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                 int folder_type_id;             /**< data connector plugIn has this folder type id */
  44                 char *service_id;               /**< service folder id */
  45                 char *parent_folder_id;
  46                                 /**< parent folder id if exist hierarchy */
  47                 char *access_name;      /**< name of accessor */
  48         } sync_agent_da_folder_s;
  49
  50 /**
  51  * @brief       Enumerations of option used to fetch framework folder item list
  52  */
  53         typedef enum {
  54                 SYNC_AGENT_DA_GET_FOLDER_LIST_OPTION_SERVICE_ID_MAPPING,/**< get folder list by service id mapping */
  55         } sync_agent_da_get_folder_list_option_e;
  56
  57 /**
  58  * @brief       Structure of query used to fetch framework folder item list
  59  */
  60         typedef struct {
  61                 sync_agent_da_get_folder_list_option_e option;
  62                 int account_id;
  63                         /**< F/W account id - SYNC_AGENT_DA_GET_FOLDER_LIST_OPTION_SERVICE_ID_MAPPING */
  64                 char *folder_id;/**< F/W folder id - SYNC_AGENT_DA_GET_FOLDER_LIST_OPTION_SERVICE_ID_MAPPING */
  65         } sync_agent_da_get_folder_list_query_s;
  66
  67 /**
  68  * @brief       Enumerations of option used to fetch framework folder item id list
  69  */
  70         typedef enum {
  71                 SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_FOLDER_TYPE_ID,      /**< get folder id by folder type */
  72                 SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_ITEM_TYPE_ID,        /**< get folder id by item type */
  73         } sync_agent_da_get_folder_id_list_option_e;
  74
  75 /**
  76  * @brief       Structure of query used to fetch framework folder item id list
  77  */
  78         typedef struct {
  79                 sync_agent_da_get_folder_id_list_option_e option;
  80                                                                 /**< sync_agent_da_get_folder_id_list_option_e type of enumeration for fetch option */
  81                 int account_id;
  82                         /**< F/W account id - SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_FOLDER_TYPE_ID, SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_ITEM_TYPE_ID */
  83                 int item_type_id;
  84                                 /**< F/W item type id - SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_FOLDER_TYPE_ID, SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_ITEM_TYPE_ID */
  85                 int folder_type_id;
  86                                 /**< F/W folder type id - SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_FOLDER_TYPE_ID */
  87         } sync_agent_da_get_folder_id_list_query_s;
  88
  89 /**
  90  * @brief                       Create initialized folder item instance
  91  * @par Usage:
  92  * @code
  93
  94  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
  95  sync_agent_da_folder_s *folder = NULL;
  96
  97  da_err = sync_agent_create_folder(&folder);
  98  if (da_err != SYNC_AGENT_DA_SUCCESS) {
  99         ...
 100  }
 101
 102  * @endcode
 103  * @remarks             folder item in FW corresponds to entity in service layer such as addressbook in Contact-service and calendar in Calendar-service
 104  * @param[out]  sync_agent_folder                               framework folder item instance initialized new
 105  * @return              operation result
 106  * @retval              SYNC_AGENT_DA_SUCCESS           success
 107  * @retval              error_value                                     fail
 108  */
 109         sync_agent_da_return_e sync_agent_create_folder(sync_agent_da_folder_s ** sync_agent_folder);
 110
 111 /**
 112  * @brief                       Add framework folder item instance into framework db
 113  * @par Usage:
 114  * @code
 115
 116  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
 117  sync_agent_da_folder_s *folder = NULL;
 118  char *folder_id = NULL;
 119
 120  da_err = sync_agent_create_folder(&folder);
 121  if (da_err != SYNC_AGENT_DA_SUCCESS) {
 122         ...
 123  }
 124
 125  ...
 126
 127  da_err = sync_agent_add_folder(folder, &folder_id);
 128  if (da_err != SYNC_AGENT_DA_SUCCESS) {
 129         ...
 130  }
 131
 132  * @endcode
 133  * @param[in]           sync_agent_folder                               framework folder item instance to add
 134  * @param[out]  folder_id                                               id of framework folder item instance added new
 135  * @return              operation result
 136  * @retval              SYNC_AGENT_DA_SUCCESS           success
 137  * @retval              error_value                                     fail
 138  */
 139         sync_agent_da_return_e sync_agent_add_folder(sync_agent_da_folder_s * sync_agent_folder, char **folder_id);
 140
 141 /**
 142  * @brief                       Fetch framework folder item instance
 143  * @par Usage:
 144  * @code
 145
 146  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
 147  sync_agent_da_folder_s *folder = NULL;
 148
 149  da_err = sync_agent_get_folder(folder_id, &folder);
 150         ...
 151  }
 152
 153  * @endcode
 154  * @param[in]           folder_id                                               id of framework folder item instance desired to get
 155  * @param[out]  sync_agent_folder                               framework folder item instance fetched
 156  * @return              operation result
 157  * @retval              SYNC_AGENT_DA_SUCCESS           success
 158  * @retval              error_value                                     fail
 159  */
 160         sync_agent_da_return_e sync_agent_get_folder(char *folder_id, sync_agent_da_folder_s ** sync_agent_folder);
 161
 162 /**
 163  * @brief                       Fetch list of framework folder item instance
 164  * @par Usage:
 165  * @code
 166
 167  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
 168  sync_agent_da_get_folder_list_query_s query;
 169  GList *folder_list = NULL;
 170
 171  query.option = SYNC_AGENT_DA_GET_FOLDER_LIST_OPTION_SERVICE_ID_MAPPING;
 172  query.account_id = account_id;
 173  query.folder_id = folder_id;
 174
 175  da_err = sync_agent_get_folder_list(&query, &folder_list);
 176         ...
 177  }
 178
 179  * @endcode
 180  * @param[in]           query                                           sync_agent_da_get_folder_list_query_s type of query for fetch operation
 181  * @param[out]  list                                                    list of framework folder item instance fetched
 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_get_folder_list(sync_agent_da_get_folder_list_query_s * query, GList ** list);
 187
 188 /**
 189  * @brief                       Fetch list of framework folder item id
 190  * @par Usage:
 191  * @code
 192
 193  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
 194  sync_agent_da_get_folder_id_list_query_s query;
 195  GList *folder_id_list = NULL;
 196
 197  query.option = SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_FOLDER_TYPE_ID;
 198  query.account_id = account_id;
 199  query.item_type_id = FW_CONTACT;
 200  query.folder_type_id = 0;
 201
 202  da_err = sync_agent_get_folder_list(&query, &folder_id_list);
 203         ...
 204  }
 205
 206  * @endcode
 207  * @param[in]           query                                           sync_agent_da_get_folder_id_list_query_s type of query for fetch operation
 208  * @param[out]  list                                                    list of framework folder item id fetched
 209  * @return              operation result
 210  * @retval              SYNC_AGENT_DA_SUCCESS           success
 211  * @retval              error_value                                     fail
 212  */
 213         sync_agent_da_return_e sync_agent_get_folder_id_list(sync_agent_da_get_folder_id_list_query_s * query, GList ** list);
 214
 215 /**
 216  * @brief                       Free framework folder item instance
 217  * @par Usage:
 218  * @code
 219
 220  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
 221  sync_agent_da_folder_s *folder = NULL;
 222
 223  da_err = sync_agent_get_folder(folder_id, &folder);
 224         ...
 225  }
 226
 227 ...
 228
 229  da_err = sync_agent_free_folder(folder);
 230         ...
 231  }
 232
 233  * @endcode
 234  * @param[in]           sync_agent_folder                               framework folder item instance to free
 235  * @return              operation result
 236  * @retval              SYNC_AGENT_DA_SUCCESS           success
 237  * @retval              error_value                                     fail
 238  */
 239         sync_agent_da_return_e sync_agent_free_folder(sync_agent_da_folder_s * sync_agent_folder);
 240
 241 /**
 242  * @brief                       Free list of framework folder item instance
 243  * @par Usage:
 244  * @code
 245
 246  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
 247  sync_agent_da_get_folder_list_query_s query;
 248  GList *folder_list = NULL;
 249
 250  query.option = SYNC_AGENT_DA_GET_FOLDER_LIST_OPTION_SERVICE_ID_MAPPING;
 251  query.account_id = account_id;
 252  query.folder_id = folder_id;
 253
 254  da_err = sync_agent_get_folder_list(&query, &folder_list);
 255         ...
 256  }
 257
 258  ...
 259
 260  da_err = sync_agent_free_folder_list(folder_list);
 261         ...
 262  }
 263
 264  * @endcode
 265  * @param[in]           list                                                    list of framework folder item instance to free
 266  * @return              operation result
 267  * @retval              SYNC_AGENT_DA_SUCCESS           success
 268  * @retval              error_value                                     fail
 269  */
 270         sync_agent_da_return_e sync_agent_free_folder_list(GList * list);
 271
 272 /**
 273  * @brief                       Free framework folder item id
 274
 275 * @par Usage:
 276 * @code
 277
 278 sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
 279 sync_agent_da_folder_s *folder = NULL;
 280 char *folder_id = NULL;
 281
 282 da_err = sync_agent_create_folder(&folder);
 283 if (da_err != SYNC_AGENT_DA_SUCCESS) {
 284    ...
 285 }
 286
 287 ...
 288
 289 da_err = sync_agent_add_folder(folder, &folder_id);
 290 if (da_err != SYNC_AGENT_DA_SUCCESS) {
 291    ...
 292 }
 293
 294 ...
 295
 296 da_err = sync_agent_free_folder_id(folder_id);
 297 if (da_err != SYNC_AGENT_DA_SUCCESS) {
 298    ...
 299 }
 300
 301 * @endcode
 302 * @param[in]            folder_id                                               framework folder item id to free
 303  * @return              operation result
 304  * @retval              SYNC_AGENT_DA_SUCCESS           success
 305  * @retval              error_value                                     fail
 306  */
 307         sync_agent_da_return_e sync_agent_free_folder_id(char *folder_id);
 308
 309 /**
 310  * @brief                       Free list of framework folder item id
 311  * @par Usage:
 312  * @code
 313
 314  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
 315  sync_agent_da_get_folder_id_list_query_s query;
 316  GList *folder_id_list = NULL;
 317
 318  query.option = SYNC_AGENT_DA_GET_FOLDER_ID_OPTION_FOLDER_TYPE_ID;
 319  query.account_id = account_id;
 320  query.item_type_id = FW_CONTACT;
 321  query.folder_type_id = 0;
 322
 323  da_err = sync_agent_get_folder_list(&query, &folder_id_list);
 324         ...
 325  }
 326
 327  ...
 328
 329  da_err = sync_agent_free_folder_id_list(folder_id_list);
 330  if (da_err != SYNC_AGENT_DA_SUCCESS) {
 331         ...
 332  }
 333
 334  * @endcode
 335  * @param[in]           list                                                    list of framework folder item id to free
 336  * @return              operation result
 337  * @retval              SYNC_AGENT_DA_SUCCESS           success
 338  * @retval              error_value                                     fail
 339  */
 340         sync_agent_da_return_e sync_agent_free_folder_id_list(GList * list);
 341
 342 /**
 343  *      @}
 344  */
 345
 346 #ifdef __cplusplus
 347 }
 348 #endif                          /* __cplusplus */
 349 #endif                          /* INTERFACE_FOLDER_H_ */