include/data-adapter/converter.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 CONVERTER_H_
  19 #define CONVERTER_H_
  20
  21 #include "plugin/data_converter_resource.h"
  22 #include "error.h"
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif                          /* __cplusplus */
  27
  28 /**
  29  * @file                converter.h
  30  * @brief       Support to use service converter module
  31  */
  32
  33 /** @addtogroup data_adapter
  34  *      @{
  35  */
  36
  37 /**
  38  * @brief                       Allocate internal object for content type
  39  * @par Usage:
  40  * @code
  41
  42  int content_type = FW_CONTACT;
  43  char *obj = (char *)sync_agent_alloc_obj(content_type);
  44
  45  * @endcode
  46  * @param[in]   content_type    service type - service data connector pluIn's ID described in F/W config file
  47  * @return                      operation result
  48  * @retval                      internal_structure_pointer                                                      success
  49  * @retval                      0                                                                                                               fail
  50  */
  51         void *sync_agent_alloc_obj(int content_type);
  52
  53 /**
  54  * @brief                       Free internal object for content type
  55  * @par Usage:
  56  * @code
  57
  58  int content_type = 1;
  59  sync_agent_da_return_e da_err = SYNC_AGENT_DA_SUCCESS;
  60
  61  char *obj = (char *)sync_agent_alloc_obj(content_type);
  62  ...
  63  da_err = sync_agent_free_obj(1, (void *)obj);
  64  if (da_err != SYNC_AGENT_DA_SUCCESS) {
  65         ...
  66  }
  67
  68  * @endcode
  69  * @param[in]   content_type    service type - service data connector pluIn's ID described in F/W config file
  70  * @param[in]   in_object                                                                                       internal object pointer
  71  * @return                      operation result
  72  * @retval                      SYNC_AGENT_DA_SUCCESS                                                                   success
  73  * @retval                      SYNC_AGENT_DA_ERRORS                                    fail
  74  */
  75         sync_agent_da_return_e sync_agent_free_obj(int content_type, void *in_object);
  76
  77 /**
  78  * @brief                       Set value for internal object
  79  * @par Usage:
  80  * @code
  81
  82  char *object = (char*)sync_agent_alloc_obj(FW_CONTACT);
  83  char *account_name = "test_account";
  84  char *result = sync_agent_set_value_to_obj(FW_CONTACT, (void*)object, VCARD_CONTENT_EXTENSION, "X-ACCOUNT-N", (void*)account_name);
  85  if (result == NULL) {
  86         ...
  87  }
  88
  89  * @endcode
  90  * @param[in]   content_type    service type - service data connector pluIn's ID described in F/W config file
  91  * @param[in]   in_object                                                                                       internal object pointer
  92  * @param[in]   key                                                                                                     key
  93  * @param[in]   extension_key                                                                   extension key
  94  * @param[in]   set_value                                                                                       value
  95  * @return                      operation result
  96  * @retval                      new_object_pointer                                                              success
  97  * @retval                      0                                                                                                               fail
  98  */
  99         void *sync_agent_set_value_to_obj(int content_type, void *in_object, int key, char *extension_key, void *set_value);
 100
 101 /**
 102  * @brief                       Allocate internal object for content type
 103  * @par Usage:
 104  * @code
 105
 106  char *account_full_name = sync_agent_get_value_to_obj(FW_CONTACT, object, VCARD_CONTENT_EXTENSION, "X-ACCOUNT");
 107  if (account_full_name == NULL) {
 108         ...
 109  }
 110
 111  * @endcode
 112  * @param[in]   content_type    service type - service data connector pluIn's ID described in F/W config file
 113  * @param[in]   in_object                                                                                       internal object pointer
 114  * @param[in]   key                                                                                                     key
 115  * @param[in]   extension_key                                                                   extension key
 116  * @return                      operation result
 117  * @retval                      value_pointer                                                                           success
 118  * @retval                      0                                                                                                               fail
 119  */
 120         void *sync_agent_get_value_to_obj(int content_type, void *in_object, int key, char *extension_key);
 121
 122 /**
 123  * @brief                       Get meta infomation of internal object
 124  * @par Usage:
 125  * @code
 126
 127  sync_agent_plugin_object_info_s *datastore_info = sync_agent_get_obj_info(FW_CONTACT);
 128  if (datastore_info != NULL) {
 129         ...
 130  }
 131
 132  * @endcode
 133  * @param[in]   content_type    service type - service data connector pluIn's ID described in F/W config file
 134  * @return                      operation result
 135  * @retval                      value_pointer                                                                           success
 136  * @retval                      0                                                                                                               fail
 137  */
 138         sync_agent_plugin_object_info_s *sync_agent_get_obj_info(int content_type);
 139
 140 /**
 141  * @brief                       Free infomation of internal object
 142  * @par Usage:
 143  * @code
 144
 145  sync_agent_plugin_object_info_s *datastore_info = sync_agent_get_obj_info(FW_CONTACT);
 146
 147  sync_agent_da_return_e result = sync_agent_free_obj_info(FW_CONTACT, datastore_info);
 148  if( result != SYNC_AGENT_DA_SUCCESS) {
 149         ...
 150  }
 151
 152  * @endcode
 153  * @param[in]   content_type    service type - service data connector pluIn's ID described in F/W config file
 154  * @param[in]   obj_info                object info
 155  * @return                      operation result
 156  * @retval                      SYNC_AGENT_DA_SUCCESS           success
 157  * @retval                      SYNC_AGENT_DA_ERRORS            fail
 158  */
 159         sync_agent_da_return_e sync_agent_free_obj_info(int content_type, sync_agent_plugin_object_info_s * obj_info);
 160
 161 /**
 162  *      @}
 163  */
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif                          /* __cplusplus */
 168 #endif                          /* CONVERTER_H_ */