src/framework/plugin/network_access_plugin.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 NETWORK_ACCESS_PLUGIN_H_
  19 #define NETWORK_ACCESS_PLUGIN_H_
  20
  21 #include <glib.h>
  22
  23 #include "struct.h"
  24 #include "error.h"
  25 #include "network-access/property.h"
  26 #include "network-access/status.h"
  27
  28 /**
  29  * @file network_access_plugin.h
  30  * @brief       Provides function pointer manipulate operation for networ_access module
  31  */
  32
  33 /** @addtogroup plugin
  34  *      @{
  35  */
  36
  37 /**
  38  * @brief Maximum number of network-access plugin
  39  */
  40 #define PLUGIN_MAX_NETWORK_ACCESS       10
  41
  42 /**
  43  * @brief Prototype of plugin function for opening network connection
  44  * @param[in] session as returned by plugin_open_connection_cb - network session information
  45  * @param[in] proxy proxy information
  46  * @param[in] timeout user preferred time-out seconds used in sending message (ex> 30 means 30seconds)
  47  * @return 1 on success, 0 on error
  48  */
  49 typedef int (*plugin_open_connection_cb) (void **session, char *proxy, int timeout);
  50
  51 /**
  52  * @brief Prototype of plugin function for binding header information for each network protocol
  53  * @param[in] header_info header information for each network protocol
  54  * @param[in] header_binding as returned by plugin_header_binding_cb - header information bound each network protocol
  55  * @return 1 on success, 0 on error
  56  */
  57 typedef int (*plugin_header_binding_cb) (GList * header_info, void **header_binding);
  58
  59 /**
  60  * @brief Prototype of plugin function for sending message to server and receive message from the server
  61  * @param[in] session network session information
  62  * @param[in] header_binding as returned by plugin_send_message_cb - header binding information
  63  * @param[in] send_msg body message
  64  * @param[in] send_msg_length length of body message
  65  * @param[in] recv_msg_size as returned by plugin_send_message_cb - the size of received message from the server
  66  * @return 1 on success, 0 on error
  67  * @retval 0 operation failed
  68  * @retval -1 cancel message
  69  * @retval -8 try again
  70  * @retval -408 request timeout
  71  */
  72 typedef int (*plugin_send_message_cb) (void *session, void **header_binding, char *send_msg, unsigned int send_msg_length, unsigned int *recv_msg_size);
  73
  74 /**
  75  * @brief Prototype of plugin function for dividing header/body information using received message from the server
  76  * @param[in] msg received message from the server
  77  * @param[in] msg_size the size of received message from the server
  78  * @param[in] recv_header as returned by plugin_header_unbinding_cb - header information of received message from the server
  79  * @param[in] recv_msg as returned by plugin_header_unbinding_cb - information of received message from the server
  80  * @param[in] recv_msg_length as returned by plugin_header_unbinding_cb - the length of body information
  81  * @return 1 on success, 0 on error
  82  */
  83 typedef int (*plugin_header_unbinding_cb) (void *msg, unsigned int msg_size, GList ** recv_header, unsigned char **recv_msg, unsigned int *recv_msg_length);
  84
  85 /**
  86  * @brief Prototype of plugin function for closing network connection
  87  * @param[in] session network session information
  88  * @return 1 on success, 0 on error
  89  */
  90 typedef int (*plugin_close_connection_cb) (void *session);
  91
  92 /**
  93  * @brief Prototype of plugin function for cancel operation about message being sent to the server
  94  * @param[in] session network session information
  95  * @return 1 on success, 0 on error
  96  */
  97 typedef int (*plugin_cancel_message_cb) (void *session);
  98
  99 /**
 100  * @brief Prototype of plugin function for just sending message to the server (do not receive message from the server)
 101  * @param[in] session network session information
 102  * @param[in] header_binding as returned by plugin_just_send_message_cb - header binding information
 103  * @param[in] send_msg body message
 104  * @param[in] send_msg_length length of body message
 105  * @return 1 on success, 0 on error
 106  */
 107 typedef int (*plugin_just_send_message_cb) (void *session, void **header_binding, char *send_msg, unsigned int send_msg_length);
 108
 109 /**
 110  * @brief Prototype of plugin function for getting network header information about specific keyword
 111  * @param[in] header_info list of network header information (key-value pair)
 112  * @param[in] key specific keyword of header information that user want to know
 113  * @param[in] value as returned by plugin_get_header_info_cb - value for the key
 114  * @return 1 on success, 0 on error
 115  */
 116 typedef int (*plugin_get_header_info_cb) (GList * header_info, char *key, char **value);
 117
 118 /**
 119  * @brief Prototype of plugin function for setting download information(download range) to download header information of specific network protocol
 120  * @param[in] down_info download header information of specific network protocol
 121  * @param[in] current_down_range download current range
 122  * @return 1 on success, 0 on error
 123  */
 124 typedef int (*plugin_set_data_download_info_cb) (void *down_info, char *current_down_range);
 125
 126 /**
 127  * @brief Prototype of plugin function for getting download information(download range, filename) to download header information of specific network protocol
 128  * @param[in] http_req_info http request information
 129  * @param[in] down_info download header information of specific network protocol
 130  * @param[in] total_down_size as returned by plugin_get_data_download_info_cb - total download size
 131  * @param[in] current_down_range as returned by plugin_get_data_download_info_cb - current download range
 132  * @param[in] down_file_name as retured by plugin_get_data_download_info_cb - download file name
 133  * @return 1 on success, 0 on error
 134  */
 135 typedef int (*plugin_get_data_download_info_cb) (void *http_req_info, void *down_info, int *total_down_size, char **current_down_range, char **down_file_name);
 136
 137 /**
 138  * @brief Prototype of plugin function for adding user authentication information (id, password) to session and
 139  * @param[in] session network session information
 140  * @param[in] id user id
 141  * @param[in] password user password
 142  * @return 1 on success, 0 on error
 143  */
 144 typedef int (*plugin_add_authentication_info_cb) (void *session, char *id, char *password);
 145
 146 /**
 147  * @brief Prototype of plugin function for setting network communication property
 148  * @param[in] session network session information
 149  * @param[in] property network communication property (time out, retry count, ...)
 150  * @param[in] va property value
 151  * @return 1 on success, 0 on error
 152  */
 153 typedef int (*plugin_set_property_cb) (void *session, sync_agent_na_property_e property, va_list va);
 154
 155 /**
 156  * @brief Prototype of plugin function for getting network communication status
 157  * @param[in] session network session information
 158  * @param[in] status network communication status (response code, elapsed time, connection time, ...)
 159  * @param[in] va status value
 160  * @return 1 on success, 0 on error
 161  */
 162 typedef int (*plugin_get_status_cb) (void *session, sync_agent_na_status_e status, va_list va);
 163
 164 /**
 165  * @brief Prototype of plugin function for connecting service and registering to the sync-agent-framework mainloop for data connection
 166  * @param[in] data user data (meaningless value)
 167  * @return 1 on success, 0 on error
 168  */
 169 typedef void (*plugin_register_fw_mainloop_na_cb) (void *data);
 170
 171 /**
 172  * @brief Structure for network-access plugin function pointer set
 173  */
 174 typedef struct {
 175         plugin_open_connection_cb func_open_connection; /**< function pointer of plugin_open_connection_cb */
 176         plugin_header_binding_cb func_header_binding; /**< function pointer of plugin_header_binding_cb */
 177         plugin_send_message_cb func_send_message; /**< function pointer of plugin_send_message_cb */
 178         plugin_header_unbinding_cb func_header_unbinding; /**< function pointer of plugin_header_unbinding_cb */
 179         plugin_close_connection_cb func_close_connection; /**< function pointer of plugin_close_connection_cb */
 180         plugin_cancel_message_cb func_cancel_message; /**< function pointer of plugin_cancel_message_cb */
 181         plugin_just_send_message_cb func_just_send_message; /**< function pointer of plugin_just_send_message_cb */
 182         plugin_get_header_info_cb func_get_header_info; /**< function pointer of plugin_get_header_info_cb */
 183         plugin_set_data_download_info_cb func_set_data_down_info; /**< function pointer of plugin_set_data_download_info_cb */
 184         plugin_get_data_download_info_cb func_get_data_down_info; /**< function pointer of plugin_get_data_download_info_cb */
 185         plugin_add_authentication_info_cb func_add_authentication_info; /**< function pointer of plugin_add_authentication_info_cb */
 186         plugin_register_fw_mainloop_na_cb func_register_fw_mainloop_na; /**< function pointer of plugin_register_fw_mainloop_na_cb */
 187         plugin_set_property_cb func_set_property; /**< function pointer of plugin_set_property_cb */
 188         plugin_get_status_cb func_get_status; /**< function pointer of plugin_get_status_cb */
 189 } plugin_network_access_func_set_s;
 190
 191 /**
 192  * @brief Structure for network-access plugin management
 193  */
 194 typedef struct {
 195         plugin_info_s plugin_info; /**< plugin info */
 196         plugin_network_access_func_set_s func_set; /**< account plugin function pointer set */
 197         int use_network; /**< whether to use network */
 198 } plugin_network_access_s;
 199
 200 /**
 201  * @brief Get network-access plugin function pointer set
 202  * @param[in] plugin_handle handle of network-access plugin (result of dlopen for network-access plugin)
 203  * @param[in] error_code as returned by plugin_get_network_access_func_set() - plugin error
 204  * @return plugin_network_access_func_set_s instance
 205  */
 206 plugin_network_access_func_set_s plugin_get_network_access_func_set(void *plugin_handle, plugin_error_e * error_code);
 207
 208 /**
 209  * @brief Register network-access plugin instance to the network-access plugin repository being maintained as a singleton
 210  * @param[in] plugin plugin_network_access_s instance
 211  * @return PLUGIN_SUCCESS on success, otherwise on error
 212  */
 213 plugin_error_e plugin_register_plugin_network_access(plugin_network_access_s plugin);
 214
 215 /**
 216  * @brief Clear network-access plugin repository being maintained as a singleton
 217  */
 218 void plugin_clear_plugin_network_access();
 219
 220 /**
 221  * @brief Get network-access plugin repository
 222  * param[in] count as returned by plugin_get_network_access_plugin_repository() - the number of network-access plugin
 223  * @return network-access plugin repository being maintained as a singleton
 224  */
 225 const plugin_network_access_s *plugin_get_network_access_plugin_repository(int *count);
 226
 227 /**
 228  * @brief Get use_network value
 229  * @param[in] plugin plugin_network_access_s instance
 230  * @return plugin_network_access_s's use_network value on success (1 or 0), -1 on error
 231  */
 232 int plugin_use_network(int plugin_id);
 233
 234 /**
 235  * @brief Get list of network-access plugin id
 236  * @param[in] plugin_id_list as returned by plugin_get_network_access_plugin_id_list() - list of network-access plugin id
 237  * @return the number of network-access plugin on success (positive value), 0 on error
 238  */
 239 int plugin_get_network_access_plugin_id_list(int **plugin_id_list);
 240
 241 /**
 242  * @brief Get function pointer of plugin_open_connection_cb
 243  * @param[in] plugin_id network-access plugin id
 244  * @return function pointer of plugin_open_connection_cb on success, NULL on error
 245  */
 246 plugin_open_connection_cb plugin_get_function_connection(int plugin_id);
 247
 248 /**
 249  * @brief Get function pointer of plugin_header_binding_cb
 250  * @param[in] plugin_id network-access plugin id
 251  * @return function pointer of plugin_header_binding_cb on success, NULL on error
 252  */
 253 plugin_header_binding_cb plugin_get_function_header_binding(int plugin_id);
 254
 255 /**
 256  * @brief Get function pointer of plugin_send_message_cb
 257  * @param[in] plugin_id network-access plugin id
 258  * @return function pointer of plugin_send_message_cb on success, NULL on error
 259  */
 260 plugin_send_message_cb plugin_get_function_send_message(int plugin_id);
 261
 262 /**
 263  * @brief Get function pointer of plugin_header_unbinding_cb
 264  * @param[in] plugin_id network-access plugin id
 265  * @return function pointer of plugin_header_unbinding_cb on success, NULL on error
 266  */
 267 plugin_header_unbinding_cb plugin_get_function_header_unbinding(int plugin_id);
 268
 269 /**
 270  * @brief Get function pointer of plugin_close_connection_cb
 271  * @param[in] plugin_id network-access plugin id
 272  * @return function pointer of plugin_close_connection_cb on success, NULL on error
 273  */
 274 plugin_close_connection_cb plugin_get_function_close_connection(int plugin_id);
 275
 276 /**
 277  * @brief Get function pointer of plugin_cancel_message_cb
 278  * @param[in] plugin_id network-access plugin id
 279  * @return function pointer of plugin_cancel_message_cb on success, NULL on error
 280  */
 281 plugin_cancel_message_cb plugin_get_function_cancel_message(int plugin_id);
 282
 283 /**
 284  * @brief Get function pointer of plugin_just_send_message_cb
 285  * @param[in] plugin_id network-access plugin id
 286  * @return function pointer of plugin_just_send_message_cb on success, NULL on error
 287  */
 288 plugin_just_send_message_cb plugin_get_function_just_send_message(int plugin_id);
 289
 290 /**
 291  * @brief Get function pointer of plugin_get_header_info_cb
 292  * @param[in] plugin_id network-access plugin id
 293  * @return function pointer of plugin_get_header_info_cb on success, NULL on error
 294  */
 295 plugin_get_header_info_cb plugin_get_function_get_header_info(int plugin_id);
 296
 297 /**
 298  * @brief Get function pointer of plugin_set_data_download_info_cb
 299  * @param[in] plugin_id network-access plugin id
 300  * @return function pointer of plugin_set_data_download_info_cb on success, NULL on error
 301  */
 302 plugin_set_data_download_info_cb plugin_get_function_set_data_download_info(int plugin_id);
 303
 304 /**
 305  * @brief Get function pointer of plugin_get_data_download_info_cb
 306  * @param[in] plugin_id network-access plugin id
 307  * @return function pointer of plugin_get_data_download_info_cb on success, NULL on error
 308  */
 309 plugin_get_data_download_info_cb plugin_get_function_get_data_download_info(int plugin_id);
 310
 311 /**
 312  * @brief Get function pointer of plugin_add_authentication_info_cb
 313  * @param[in] plugin_id network-access plugin id
 314  * @return function pointer of plugin_add_authentication_info_cb on success, NULL on error
 315  */
 316 plugin_add_authentication_info_cb plugin_get_function_add_authentication_info(int plugin_id);
 317
 318 /**
 319  * @brief Get function pointer of plugin_register_fw_mainloop_na_cb
 320  * @param[in] plugin_id network-access plugin id
 321  * @return function pointer of plugin_register_fw_mainloop_na_cb on success, NULL on error
 322  */
 323 plugin_register_fw_mainloop_na_cb plugin_get_function_register_fw_mainloop_na(int plugin_id);
 324
 325 /**
 326  * @brief Get function pointer of plugin_set_property_cb
 327  * @param[in] plugin_id network-access plugin id
 328  * @return function pointer of plugin_set_property_cb on success, NULL on error
 329  */
 330 plugin_set_property_cb plugin_get_function_set_property(int plugin_id);
 331
 332 /**
 333  * @brief Get function pointer of plugin_get_status_cb
 334  * @param[in] plugin_id network-access plugin id
 335  * @return function pointer of plugin_get_status_cb on success, NULL on error
 336  */
 337 plugin_get_status_cb plugin_get_function_get_status(int plugin_id);
 338
 339 /**
 340  *      @}
 341  */
 342
 343 #endif                          /* NETWORK_ACCESS_PLUGIN_H_ */