include/engine-controller/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 ENGINE_CONTROLLER_INTERFACE_H_
  19 #define ENGINE_CONTROLLER_INTERFACE_H_
  20
  21 #include "define.h"
  22 #include "task_spec.h"
  23 #include "queuing_rule_spec.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif                          /* __cplusplus */
  28
  29 /**
  30  * @file interface.h
  31  * @brief Provides APIs to support task registration and request
  32  */
  33
  34 /** @addtogroup engine_controller
  35  *      @{
  36  */
  37
  38 /**
  39  * @brief Callback function which is called when task is finsihed
  40  * @param[in] task_error Result of the watching task
  41  * @param[in] out_param_cnt Count of out parameter of the watching task
  42  * @param[in] out_param_array Array of parameter values of the watching task
  43  * @param[in] usr_data User defined data
  44  */
  45         typedef void (*sync_agent_task_finish_cb) (sync_agent_ec_task_error_e task_error, sync_agent_ec_uint out_param_cnt, sync_agent_ec_param_param_s ** out_param_array, sync_agent_ec_pointer usr_data);
  46
  47 /**
  48  * @brief Callback function which is called when queuing rule spec registration done
  49  * @param[in] ec_error Result of the registration
  50  * @param[in] registered_id ID of the registered queuing rule spec
  51  * @param[in] usr_data User defined data
  52  */
  53         typedef void (*sync_agent_register_finish_cb) (sync_agent_ec_error_e ec_error, sync_agent_ec_uint registered_id, sync_agent_ec_pointer usr_data);
  54
  55 /* external interfaces */
  56
  57 /**
  58  * @brief Registers user created task spec
  59  * @par Usage:
  60  * @code
  61  sync_agent_ec_task_spec_s *make_synchronize_task()
  62  {
  63          sync_agent_ec_param_spec_s *pParam_spec1 = sync_agent_alloc_param_spec_int("accountId", true, false, false, 0, 0, false, 0, false, 0, 0);
  64          sync_agent_ec_param_spec_s *pParam_spec2 = sync_agent_alloc_param_spec_structure("syncMode", _string_copy_struct, free,  true, false, false, NULL, false, NULL, false, NULL);
  65          sync_agent_ec_param_spec_s *pParam_spec3 = sync_agent_alloc_param_spec_structure("sanPackage", NULL, sanPackageParserFree, true, false, false, NULL, false, NULL, false, NULL);
  66          sync_agent_ec_param_spec_s *param_spec_array[3] = {pParam_spec1, pParam_spec2, pParam_spec3};
  67
  68          sync_agent_ec_task_spec_s *pTask_spec = sync_agent_alloc_simple_task_spec("synchronize", synchronize_task_process, NULL, NULL, 3, param_spec_array);
  69
  70          sync_agent_unref_param_spec(pParam_spec1);
  71          sync_agent_unref_param_spec(pParam_spec2);
  72          sync_agent_unref_param_spec(pParam_spec3);
  73
  74          return pTask_spec;
  75  }
  76
  77  sync_operation()
  78  {
  79          sync_agent_ec_task_spec_s *pSyncTaskSpec = make_synchronize_task();
  80          sync_agent_register_task_spec(EC_MSG_TYPE_SYNC_TASK_REQUEST, EC_MSG_TYPE_NAME_SYNC_TASK_REQUEST, pSyncTaskSpec, NULL);
  81
  82          ...
  83  }
  84  * @endcode
  85  * @param[in] task_spec_id User defined task spec ID
  86  * @param[in] task_spec_name User defined task spec ID
  87  * @param[in] task_spec User created task spec in task_stpec_t type
  88  * @param[in] cal_func ID calculation func
  89  */
  90         void sync_agent_register_task_spec(sync_agent_ec_uint task_spec_id, sync_agent_ec_char * task_spec_name, sync_agent_ec_task_spec_s * task_spec, sync_agent_calculate_identifier_cb cal_func);
  91
  92 /**
  93  * @brief Registers user created asychronousqueuing rule spec
  94  * @par Usage:
  95  * @code
  96  sync_agent_ec_task_spec_s *make_synchronize_task()
  97  {
  98          sync_agent_ec_param_spec_s *pParam_spec1 = sync_agent_alloc_param_spec_int("accountId", true, false, false, 0, 0, false, 0, false, 0, 0);
  99          sync_agent_ec_param_spec_s *pParam_spec2 = sync_agent_alloc_param_spec_structure("syncMode", _string_copy_struct, free,  true, false, false, NULL, false, NULL, false, NULL);
 100          sync_agent_ec_param_spec_s *pParam_spec3 = sync_agent_alloc_param_spec_structure("sanPackage", NULL, sanPackageParserFree, true, false, false, NULL, false, NULL, false, NULL);
 101          sync_agent_ec_param_spec_s *param_spec_array[3] = {pParam_spec1, pParam_spec2, pParam_spec3};
 102
 103          sync_agent_ec_task_spec_s *pTask_spec = sync_agent_alloc_simple_task_spec("synchronize", synchronize_task_process, NULL, NULL, 3, param_spec_array);
 104
 105          sync_agent_unref_param_spec(pParam_spec1);
 106          sync_agent_unref_param_spec(pParam_spec2);
 107          sync_agent_unref_param_spec(pParam_spec3);
 108
 109          return pTask_spec;
 110  }
 111
 112  sync_operation()
 113  {
 114          sync_agent_ec_task_spec_s *pSyncTaskSpec = make_synchronize_task();
 115          sync_agent_register_task_spec(EC_MSG_TYPE_SYNC_TASK_REQUEST, EC_MSG_TYPE_NAME_SYNC_TASK_REQUEST, pSyncTaskSpec, NULL);
 116
 117          sync_agent_ec_queuing_rule_spec_s *pQueuing_rule = sync_agent_create_queuing_rule_spec_outline("sync_queueing_rule");
 118
 119          sync_agent_add_progress_blocking_element(pQueuing_rule, EC_MSG_TYPE_SYNC_TASK_REFRESH_FROM_SERVICE, pSyncTaskSpec, 0);
 120          sync_agent_add_progress_blocking_element(pQueuing_rule, EC_MSG_TYPE_SYNC_TASK_REQUEST, pSyncTaskSpec, 0);
 121          sync_agent_add_progress_blocking_element(pQueuing_rule, EC_MSG_TYPE_SYNC_TASK_RESET_ALL_DATA, pSyncTaskSpec, 0);
 122
 123          sync_agent_register_async_queuing_rule_spec(pQueuing_rule, NULL, NULL);
 124
 125          ...
 126  }
 127  * @endcode
 128  * @param[in] spec User created queuing rule spec to register
 129  * @param[in] finish_callback Callback function to be called on registration done
 130  * @param[in] usr_data User data to pass to the callback function
 131  */
 132         void sync_agent_register_async_queuing_rule_spec(sync_agent_ec_queuing_rule_spec_s * spec, sync_agent_register_finish_cb finish_callback, sync_agent_ec_pointer usr_data);
 133
 134 /**
 135  * @brief Requests task asynchronously, using task spec/param info and etc
 136  * @par Usage:
 137  * @code
 138  static void _request_manual_sync_task_finish_callback(sync_agent_ec_task_error_e task_error, unsigned int out_param_cnt, sync_agent_ec_param_param_s **out_param_spec_array, void *usr_data)
 139  {
 140         ...
 141  }
 142
 143  sync_agent_ec_task_spec_s *make_synchronize_task()
 144  {
 145          sync_agent_ec_param_spec_s *pParam_spec1 = sync_agent_alloc_param_spec_int("accountId", true, false, false, 0, 0, false, 0, false, 0, 0);
 146          sync_agent_ec_param_spec_s *pParam_spec2 = sync_agent_alloc_param_spec_structure("syncMode", _string_copy_struct, free,  true, false, false, NULL, false, NULL, false, NULL);
 147          sync_agent_ec_param_spec_s *pParam_spec3 = sync_agent_alloc_param_spec_structure("sanPackage", NULL, sanPackageParserFree, true, false, false, NULL, false, NULL, false, NULL);
 148          sync_agent_ec_param_spec_s *param_spec_array[3] = {pParam_spec1, pParam_spec2, pParam_spec3};
 149
 150          sync_agent_ec_task_spec_s *pTask_spec = sync_agent_alloc_simple_task_spec("synchronize", synchronize_task_process, NULL, NULL, 3, param_spec_array);
 151
 152          sync_agent_unref_param_spec(pParam_spec1);
 153          sync_agent_unref_param_spec(pParam_spec2);
 154          sync_agent_unref_param_spec(pParam_spec3);
 155
 156          return pTask_spec;
 157  }
 158
 159  sync_operation()
 160  {
 161          sync_agent_ec_task_spec_s *pSyncTaskSpec = make_synchronize_task();
 162          sync_agent_register_task_spec(EC_MSG_TYPE_SYNC_TASK_REQUEST, EC_MSG_TYPE_NAME_SYNC_TASK_REQUEST, pSyncTaskSpec, NULL);
 163
 164          ...
 165
 166          int account_id =  get_account_id(profile, false);
 167          char *sync_mode = strdup(DEFINE_SYNC_MODE_MANUAL);
 168
 169          void *in_param_value_array[3] = {&account_id, &sync_mode, NULL};
 170          int in_param_index_array[3] = {0, 1, 2};
 171          sync_agent_ec_value_type_e in_param_value_type_array[3] = {SYNC_AGENT_EC_VALUE_TYPE_INT, SYNC_AGENT_EC_VALUE_TYPE_STRUCT, SYNC_AGENT_EC_VALUE_TYPE_STRUCT};
 172
 173          unsigned int request_msg_id = 0;
 174          sync_agent_request_async_task(EC_MSG_TYPE_SYNC_TASK_REQUEST, 0, 3, in_param_index_array, in_param_value_type_array, in_param_value_array, _request_manual_sync_task_finish_callback, NULL, (int *)&request_msg_id);
 175
 176          ...
 177  }
 178  * @endcode
 179  * @param[in] task_spec_id User defined task spec ID
 180  * @param[in] identifier User defined task identifier
 181  * @param[in] cnt_in_param Count of input parameters
 182  * @param[in] in_param_index_array Array containing param index
 183  * @param[in] in_param_value_type_array Array containing param value type
 184  * @param[in] in_param_value_array Array containing param value
 185  * @param[in] task_finish_callback Task finish callback
 186  * @param[in] simple_task_finish_callback_usr_data User data passed to finish callback
 187  * @param[out] request_id Task request ID which Engine Controller issues
 188  */
 189         void sync_agent_request_async_task(sync_agent_ec_uint task_spec_id, sync_agent_ec_uint identifier, sync_agent_ec_int cnt_in_param, sync_agent_ec_int * in_param_index_array, sync_agent_ec_value_type_e * in_param_value_type_array,
 190                                            sync_agent_ec_pointer * in_param_value_array, sync_agent_task_finish_cb task_finish_callback, sync_agent_ec_pointer simple_task_finish_callback_usr_data, sync_agent_ec_int * request_id);
 191
 192 /**
 193  * @brief Requests task synchronously, using task spec/param info and etc
 194  * @par Usage:
 195  * @code
 196  sync_agent_ec_task_spec_s *make_reset_all_data_task()
 197  {
 198          _EXTERN_FUNC_ENTER;
 199
 200          sync_agent_ec_param_spec_s *pParam_spec1 = sync_agent_alloc_param_spec_int("result", false, true, false, 0, 0, false, 0, false, 0, 0);
 201          sync_agent_ec_param_spec_s *param_spec_array[1] = {pParam_spec1};
 202
 203          sync_agent_ec_task_spec_s *pTask_spec = sync_agent_alloc_simple_task_spec("reset_all_data",
 204                                                                                          reset_all_data_task_process, NULL, NULL,
 205                                                                                          1, param_spec_array);
 206
 207          sync_agent_unref_param_spec(pParam_spec1);
 208
 209          _EXTERN_FUNC_EXIT;
 210          return pTask_spec;
 211  }
 212
 213  reset_operation()
 214  {
 215          sync_agent_ec_task_spec_s *pResetAllDataTaskSpec = make_reset_all_data_task();
 216          sync_agent_register_task_spec(EC_MSG_TYPE_SYNC_TASK_RESET_ALL_DATA, EC_MSG_TYPE_NAME_SYNC_TASK_RESET_ALL_DATA, pResetAllDataTaskSpec, NULL);
 217
 218          ...
 219
 220          unsigned int request_msg_id = 0;
 221          sync_agent_ec_task_error_e task_error = SYNC_AGENT_EC_TASK_ERROR_NOT_YET_RUN;
 222
 223          unsigned int out_param_count;
 224          sync_agent_ec_param_param_s **param_array = NULL;
 225
 226          sync_agent_request_sync_task(EC_MSG_TYPE_SYNC_TASK_RESET_ALL_DATA, 0, 0, NULL, NULL, NULL, (int *)&request_msg_id, &task_error, &out_param_count, &param_array);
 227
 228          ...
 229  }
 230  * @endcode
 231  * @param[in] task_spec_id User defined task spec ID
 232  * @param[in] identifier User defined task identifier
 233  * @param[in] cnt_in_param Count of input parameters
 234  * @param[in] in_param_index_array Array containing param index
 235  * @param[in] in_param_value_type_array Array containing param value type
 236  * @param[in] in_param_value_array Array containing param value
 237  * @param[out] request_id Task request ID which Engine Controller issues
 238  * @param[out] task_error Result of the task
 239  * @param[out] out_param_cnt Count of output parameter of the task
 240  * @param[out] out_param_array param_t type of array containing output parameter of the task
 241  */
 242         void sync_agent_request_sync_task(sync_agent_ec_uint task_spec_id, sync_agent_ec_uint identifier, sync_agent_ec_int cnt_in_param, sync_agent_ec_int * in_param_index_array, sync_agent_ec_value_type_e * in_param_value_type_array,
 243                                           sync_agent_ec_pointer * in_param_value_array, sync_agent_ec_int * request_id, sync_agent_ec_task_error_e * task_error, sync_agent_ec_uint * out_param_cnt, sync_agent_ec_param_param_s *** out_param_array);
 244
 245 /**
 246  * @brief Cancel task which has given request ID
 247  * @par Usage:
 248  * @code
 249  ...
 250
 251  unsigned int request_msg_id = 0;
 252  sync_agent_request_sync_task(EC_MSG_TYPE_SYNC_TASK_RESET_ALL_DATA, 0, 0, NULL, NULL, NULL, (int *)&request_msg_id, &task_error, &out_param_count, &param_array);
 253
 254  ...
 255
 256  sync_agent_cancel_task(request_msg_id_to_cancel);
 257  * @endcode
 258  * @param[in] request_id_to_cancel request ID of task to cancel
 259  */
 260         void sync_agent_cancel_task(sync_agent_ec_int request_id_to_cancel);
 261
 262 /**
 263  * @brief Cancels all running task
 264  * @par Usage:
 265  * @code
 266  ...
 267
 268  sync_agent_request_async_task(EC_MSG_TYPE_SYNC_TASK_REQUEST, 0, 3, in_param_index_array, in_param_value_type_array, in_param_value_array, _request_manual_sync_task_finish_callback, NULL, (int *)&request_msg_id);
 269  sync_agent_request_sync_task(EC_MSG_TYPE_SYNC_TASK_RESET_ALL_DATA, 0, 0, NULL, NULL, NULL, (int *)&request_msg_id, &task_error, &out_param_count, &param_array);
 270
 271  ...
 272
 273  sync_agent_cancel_all_tasks();
 274  * @endcode
 275  */
 276         void sync_agent_cancel_all_tasks(void);
 277
 278 /**
 279  *      @}
 280  */
 281
 282 #ifdef __cplusplus
 283 }
 284 #endif                          /* __cplusplus */
 285 #endif                          /* ENGINE_CONTROLLER_INTERFACE_H_ */