include/plugin/network_access_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 NETWORK_ACCESS_INTERFACE_H_
  19 #define NETWORK_ACCESS_INTERFACE_H_
  20
  21 #include <glib.h>
  22 #include "network-access/property.h"
  23 #include "network-access/status.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif                          /* __cplusplus */
  28
  29 /**
  30  * @file network_access_interface.h
  31  * @brief Defines plug-in interfaces about network access
  32  */
  33
  34 /** @addtogroup plugin_networkaccess NetworkAccess Domain
  35  * @ingroup plugin
  36  *      @{
  37  */
  38
  39 /**
  40  * API to open network connection
  41  *
  42  * @param[in] session as returned by sync_agent_plugin_open_connection() - network session information
  43  * @param[in] proxy proxy information
  44  * @param[in] timeout user preferred time-out seconds used in sending message (ex> 30 means 30seconds)
  45  *
  46  * @return 1 on success, 0 on error
  47  *
  48  * @par Since:
  49  *
  50  *
  51  * @see sync_agent_open_connection(int, int, unsigned int *), _create_all_session(int)
  52  *
  53  */
  54         int sync_agent_plugin_open_connection(void **session, char *proxy, int timeout);
  55
  56 /**
  57  * API to bind header information for each network protocol
  58  *
  59  * @param[in] header_info header information for each network protocol
  60  * @param[in] header_binding as returned by sync_agent_plugin_header_binding() - header information bound each network protocol
  61  *
  62  * @return 1 on success, 0 on error
  63  *
  64  * @par Since:
  65  *
  66  *
  67  * @see sync_agent_send_msg(GList *, int, char *, unsigned int, GList **, unsigned char **, unsigned int *, sync_agent_na_send_type_e, unsigned int)
  68  *
  69  */
  70         int sync_agent_plugin_header_binding(GList * header_info, void **header_binding);
  71
  72 /**
  73  * API to send message to server and receive message from the server
  74  *
  75  * @param[in] session network session information
  76  * @param[in] header_binding as returned by sync_agent_plugin_send_message() - header binding information
  77  * @param[in] send_msg body message
  78  * @param[in] send_msg_length length of body message
  79  * @param[in] recv_msg_size as returned by sync_agent_plugin_send_message() - the size of received message from the server
  80  *
  81  * @return 1 on success, otherwise error
  82  * @retval 0 operation failed
  83  * @retval -1 cancel message
  84  * @retval -8 try again
  85  * @retval -408 request timeout
  86  *
  87  * @par Since:
  88  *
  89  *
  90  * @see sync_agent_send_msg(GList *, int, char *, unsigned int, GList **, unsigned char **, unsigned int *, sync_agent_na_send_type_e, unsigned int)
  91  *
  92  */
  93         int sync_agent_plugin_send_message(void *session, void **header_binding, char *send_msg, unsigned int send_msg_length, unsigned int *recv_msg_size);
  94
  95 /**
  96  * API to divide header/body information using received message from the server
  97  *
  98  * @param[in] msg received message from the server
  99  * @param[in] msg_size the size of received message from the server
 100  * @param[in] recv_header as returned by sync_agent_plugin_header_unbinding() - header information of received message from the server
 101  * @param[in] recv_msg as returned by sync_agent_plugin_header_unbinding() - information of received message from the server
 102  * @param[in] recv_msg_length as returned by sync_agent_plugin_header_unbinding() - the length of body information
 103  *
 104  * @return 1 on success, 0 on error
 105  *
 106  * @par Since:
 107  *
 108  *
 109  * @see sync_agent_send_msg(GList *, int, char *, unsigned int, GList **, unsigned char **, unsigned int *, sync_agent_na_send_type_e, unsigned int)
 110  *
 111  */
 112         int sync_agent_plugin_header_unbinding(void *msg, unsigned int msg_size, GList ** recv_header, unsigned char **recv_msg, unsigned int *recv_msg_length);
 113
 114 /**
 115  * API to close network connection
 116  *
 117  * @param[in] session network session information
 118  *
 119  * @return 1 on success, 0 on error
 120  *
 121  * @par Since:
 122  *
 123  *
 124  * @see sync_agent_close_connection(int, unsigned int)
 125  *
 126  */
 127         int sync_agent_plugin_close_connection(void *session);
 128
 129 /**
 130  * API to cancel operation about message being sent to the server
 131  *
 132  * @param[in] session network session information
 133  *
 134  * @return 1 on success, 0 on error
 135  *
 136  * @par Since:
 137  *
 138  *
 139  * @see sync_agent_cancel_msg(int, unsigned int)
 140  *
 141  */
 142         int sync_agent_plugin_cancel_message(void *session);
 143
 144 /**
 145  * API to just send message to the server (do not receive message from the server)
 146  *
 147  * @param[in] session network session information
 148  * @param[in] header_binding as returned by sync_agent_plugin_just_send_message() - header binding information
 149  * @param[in] send_msg Body message
 150  * @param[in] send_msg_length Length of body message
 151  *
 152  * @return 1 on success, 0 on error
 153  *
 154  * @par Since:
 155  *
 156  *
 157  * @see sync_agent_send_msg(GList *, int, char *, unsigned int, GList **, unsigned char **, unsigned int *, sync_agent_na_send_type_e, unsigned int)
 158  *
 159  */
 160         int sync_agent_plugin_just_send_message(void *session, void **header_binding, char *send_msg, unsigned int send_msg_length);
 161
 162 /**
 163  * API to get network header information about specific keyword
 164  *
 165  * @param[in] header_info list of network header information (key-value pair)
 166  * @param[in] key Specific keyword of header information that user want to know
 167  * @param[in] value as returned by sync_agent_plugin_get_header_info() - value for the key
 168  *
 169  * @return 1 on success, 0 on error
 170  *
 171  * @par Since:
 172  *
 173  *
 174  * @see sync_agent_get_header_info(int, GList *, char *, char **)
 175  *
 176  */
 177         int sync_agent_plugin_get_header_info(GList * header_info, char *key, char **value);
 178
 179 /**
 180  * API to set download information(download range) to download header information of specific network protocol
 181  *
 182  * @param[in] down_info download header information of specific network protocol
 183  * @param[in] current_down_range download current range
 184  *
 185  * @return 1 on success, 0 on error
 186  *
 187  * @par Since:
 188  *
 189  *
 190  * @see na_download_data(GList *header_info, int, unsigned char *, unsigned int, unsigned int, unsigned char **, sync_agent_na_send_type_e, unsigned int)
 191  *
 192  */
 193         int sync_agent_plugin_set_data_download_info(void *down_info, char *current_down_range);
 194
 195 /**
 196  * API to get download information(download range, filename) to download header information of specific network protocol
 197  *
 198  * @param[in] http_req_info http request information
 199  * @param[in] down_info download header information of specific network protocol
 200  * @param[in] total_down_size as returned by sync_agent_plugin_get_data_download_info() - total download size
 201  * @param[in] current_down_range as returned by sync_agent_plugin_get_data_download_info() - current download range
 202  * @param[in] down_file_name as returned by sync_agent_plugin_get_data_download_info() - download file name
 203  *
 204  * @return 1 on success, 0 on error
 205  *
 206  * @par Since:
 207  *
 208  *
 209  * @see na_download_data(GList *header_info, int, unsigned char *, unsigned int, unsigned int, unsigned char **, sync_agent_na_send_type_e, unsigned int)
 210  *
 211  */
 212         int sync_agent_plugin_get_data_download_info(void *http_req_info, void *down_info, int *total_down_size, char **current_down_range, char **down_file_name);
 213
 214 /**
 215  * API to add user authentication information (id, password) to session and
 216  * register authentication callback for 'authenticate' signal
 217  *
 218  * @param[in] session network session information
 219  * @param[in] id user id
 220  * @param[in] password user password
 221  *
 222  * @return 1 on success, 0 on error
 223  *
 224  * @par Since:
 225  *
 226  *
 227  * @see sync_agent_add_authentication_info(int, char *, char *, unsigned int)
 228  *
 229  */
 230         int sync_agent_plugin_add_authentication_info(void *session, char *id, char *password);
 231
 232 /**
 233  * API to connect service and register to the sync-agent-framework mainloop for data connection
 234  *
 235  * @param[in] data user data (meaningless value)
 236  *
 237  * @par Since:
 238  *
 239  *
 240  * @see na_init_network_access(int)
 241  *
 242  */
 243         void sync_agent_plugin_register_fw_main_loop_network_access(void *data);
 244
 245 /**
 246  * API to set network communication property
 247  *
 248  * @param[in] session network session information
 249  * @param[in] property network communication property (time out, retry count, ...)
 250  * @param[in] va property value
 251  *
 252  * @return 1 on success, 0 on error
 253  *
 254  * @par Since:
 255  *
 256  *
 257  * @see na_set_property(int, unsigned int, sync_agent_na_property_e, ...)
 258  *
 259  */
 260         int sync_agent_plugin_set_property(void *session, sync_agent_na_property_e property, va_list va);
 261
 262 /**
 263  * API to get network communication status
 264  *
 265  * @param[in] session network session information
 266  * @param[in] status network communication status (response code, elapsed time, connection time, ...)
 267  * @param[in] va status value
 268  *
 269  * @return 1 on success, 0 on error
 270  *
 271  * @par Since:
 272  *
 273  *
 274  * @see sync_agent_get_status(int, unsigned int, sync_agent_na_status_e, ...)
 275  *
 276  */
 277         int sync_agent_plugin_get_status(void *session, sync_agent_na_status_e status, va_list va);
 278
 279 /**
 280  *      @}
 281  */
 282
 283 #ifdef __cplusplus
 284 }
 285 #endif                          /* __cplusplus */
 286 #endif                          /* NETWORK_ACCESS_INTERFACE_H_ */