resource/csdk/connectivity/inc/caethernetinterface.h

   1 /******************************************************************
   2 *
   3 * Copyright 2014 Samsung Electronics All Rights Reserved.
   4 *
   5 *
   6 *
   7 * Licensed under the Apache License, Version 2.0 (the "License");
   8 * you may not use this file except in compliance with the License.
   9 * You may obtain a copy of the License at
  10 *
  11 *      http://www.apache.org/licenses/LICENSE-2.0
  12 *
  13 * Unless required by applicable law or agreed to in writing, software
  14 * distributed under the License is distributed on an "AS IS" BASIS,
  15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 * See the License for the specific language governing permissions and
  17 * limitations under the License.
  18 *
  19 ******************************************************************/
  20
  21 /**
  22  * @file caethernetinterface.h
  23  * @brief This file provides APIs ethernet client/server/network monitor modules
  24  */
  25
  26 #ifndef _CA_ETHERNET_INTERFACE_H_
  27 #define _CA_ETHERNET_INTERFACE_H_
  28
  29 #include <stdbool.h>
  30
  31 #include "cacommon.h"
  32 #include "uthreadpool.h" /* for thread pool */
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #endif
  38
  39 /**
  40  * @enum CAAdapterServerType_t
  41  * @brief Enum for defining different server types.
  42  */
  43 typedef enum
  44 {
  45     CA_UNICAST_SERVER = 0,      /**< Unicast Server */
  46     CA_MULTICAST_SERVER,        /**< Multicast Server */
  47     CA_SECURED_UNICAST_SERVER   /**< Secured Unicast Server */
  48 } CAAdapterServerType_t;
  49
  50 /**
  51  * @brief Callback to be notified on reception of any data from remote OIC devices.
  52  * @param  ipAddress    [IN] IP address of remote OIC device.
  53  * @param  port         [IN] Port number on which data is received.
  54  * @param  data         [IN] Data received from remote OIC device.
  55  * @param  dataLength   [IN] Length of data in bytes.
  56  * @param  isSecured     [IN] Indicates the data is secure or not.
  57  * @return NONE
  58  * @pre  Callback must be registered using CAEthernetSetPacketReceiveCallback()
  59  */
  60 typedef void (*CAEthernetPacketReceivedCallback)(const char *ipAddress, const uint32_t port,
  61                                                  const void *data, const uint32_t dataLength,
  62                                                  const CABool_t isSecured);
  63
  64 /**
  65  * @brief  Callback to be notified when exception occures on multicast/unicast server.
  66  * @param  type  [IN] Type of server(#CAAdapterServerType_t)
  67  * @return NONE
  68  * @pre  Callback must be registered using CAEthernetSetExceptionCallback()
  69  */
  70 typedef void (*CAEthernetExceptionCallback)(CAAdapterServerType_t type);
  71
  72 /**
  73  * @brief  Initialize Ethernet server
  74  * @param   threadPool  [IN] Thread pool for managing Unicast/Multicast server threads.
  75  * @return  #CA_STATUS_OK or Appropriate error code
  76  * @retval  #CA_STATUS_OK  Successful
  77  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
  78  * @retval  #CA_STATUS_FAILED Initialization failed
  79  */
  80 CAResult_t CAEthernetInitializeServer(const u_thread_pool_t threadPool);
  81
  82 /**
  83  * @brief  Terminate Ethernet server
  84  * @return NONE
  85  */
  86 void CAEthernetTerminateServer(void);
  87
  88 /**
  89  * @brief  Start multicast server for specified multicast address and port
  90  *
  91  * @param   localAddress        [IN]      Local adapter address to which server to be binded.
  92  * @param   multicastAddress    [IN]      Multicast group address.
  93  * @param   multicastPort       [IN,OUT]  Port number on which server will be running. If binding
  94                                           the port failed, server starts in the next available port.
  95  * @param   serverFD            [OUT]     Multicast server socket FD.
  96  *
  97  * @return  #CA_STATUS_OK or Appropriate error code
  98  * @retval  #CA_STATUS_OK  Successful
  99  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 100  * @retval  #CA_SERVER_STARTED_ALREADY Multicast server is already started and running.
 101  * @retval  #CA_STATUS_FAILED Operation failed
 102  */
 103 CAResult_t CAEthernetStartMulticastServer(const char *localAddress, const char *multicastAddress,
 104                                           const int16_t multicastPort, int32_t *serverFD);
 105
 106 /**
 107  * @brief  Start unicast server for specified local address and port
 108  *
 109  * @param  localAddress [IN]      Local adapter address to which server to be binded.
 110  * @param  port         [IN,OUT]  Port number on which server will be running. If binding
 111                                   the port failed, server starts in the next available port.
 112  * @param  forceStart   [IN]      Indicate whether to start server forcesfully on specified port
 113  *                                or not.
 114  * @param  secured      [IN]      True if the secure server to be started, otherwise false.
 115  * @param  serverFD     [OUT]     Unicast server socket FD.
 116  *
 117  * @return  #CA_STATUS_OK or Appropriate error code
 118  * @retval  #CA_STATUS_OK  Successful
 119  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 120  * @retval  #CA_SERVER_STARTED_ALREADY Unicast server is already started and running.
 121  * @retval  #CA_STATUS_FAILED Operation failed
 122  */
 123 CAResult_t CAEthernetStartUnicastServer(const char *localAddress, int16_t *port,
 124                                         const bool forceStart, const bool secured, int32_t *serverFD);
 125
 126 /**
 127  * @brief  Stop multicast server.
 128  *
 129  * @return  #CA_STATUS_OK or Appropriate error code
 130  * @retval  #CA_STATUS_OK  Successful
 131  * @retval  #CA_STATUS_FAILED Operation failed
 132  */
 133 CAResult_t CAEthernetStopMulticastServer(void);
 134
 135 /**
 136  * @brief  Stop unicast server.
 137  *
 138  * @return  #CA_STATUS_OK or Appropriate error code
 139  * @retval  #CA_STATUS_OK  Successful
 140  * @retval  #CA_STATUS_FAILED Operation failed
 141  */
 142 CAResult_t CAEthernetStopUnicastServer();
 143
 144 /**
 145  * @brief  Stop secured unicast server.
 146  *
 147  * @return  #CA_STATUS_OK or Appropriate error code
 148  * @retval  #CA_STATUS_OK  Successful
 149  * @retval  #CA_STATUS_FAILED Operation failed
 150  */
 151 CAResult_t CAEthernetStopSecureUnicastServer();
 152
 153 /**
 154  * @brief  Get the Unicast Server Information if it is started
 155  *
 156  * @param  secure       [IN] True if the secure server information needed, otherwise false.
 157  * @param  ipAddress    [OUT]IP address on which server is binded and running.
 158  * @param  port         [OUT]Port number on which server is running
 159  * @param  serverFD     [OUT]Server socket fd.
 160  *
 161  * @return  #CA_STATUS_OK or Appropriate error code
 162  * @retval  #CA_STATUS_OK  Successful
 163  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 164  * @retval  #CA_STATUS_FAILED Operation failed
 165  * @remarks  ipAddress must be freed using free().
 166  */
 167 CAResult_t CAEthernetGetUnicastServerInfo(const bool secure, char **ipAddress, int16_t *port,
 168                                           int32_t *serverFD);
 169
 170 /**
 171  * @brief  Set this callback for receiving data packets from peer devices.
 172  *
 173  * @param  callback   [IN] Callback to be notified on reception of unicast/multicast data packets.
 174  *
 175  * @return  NONE
 176  */
 177 void CAEthernetSetPacketReceiveCallback(CAEthernetPacketReceivedCallback callback);
 178
 179 /**
 180  * @brief  Set this callback for receiving exception notifications.
 181  *
 182  * @param  callback [IN] Callback to be notified on occurance of exception on running servers.
 183  *
 184  * @return  NONE
 185  */
 186 void CAEthernetSetExceptionCallback(CAEthernetExceptionCallback callback);
 187
 188 /**
 189  * @brief  Set socket description for sending unicast UDP data. Once the Unicast server is started,
 190  *         the same socket descriptor is used for sending the Unicast UDP data.
 191  *
 192  * @param  socketFD [IN]  Socket descriptor used for sending UDP data.
 193  * @return  NONE
 194  */
 195 void CAEthernetSetUnicastSocket(const int32_t socketFD);
 196
 197 /**
 198  * @brief  Set the port number for sending unicast UDP data
 199  * @param  port [IN] Port number used for sending UDP data.
 200  * @return NONE
 201  */
 202 void CAEthernetSetUnicastPort(const int32_t port);
 203
 204 #ifdef __WITH_DTLS__
 205 /**
 206  * @brief  Set socket description for sending secured (encrypted) unicast UDP data
 207  *
 208  * @param socketFD [IN] Socket descriptor used for sending secured (encrypted) UDP data.
 209  * @return  NONE
 210  */
 211 void CAEthernetSetSecureUnicastSocket(const int32_t socketFD);
 212 #endif
 213
 214 /**
 215  * @brief  API to send unicast UDP data
 216  *
 217  * @param  remoteAddress    [IN] IP address to which data needs to be sent.
 218  * @param  port             [IN] Port to which data needs to be send.
 219  * @param  data             [IN] Data to be send.
 220  * @param  dataLength       [IN] Length of data in bytes
 221  * @param  isMulticast      [IN] Whether data needs to be sent to multicast ip
 222  * @param  isSecure         [IN] Whether data to be sent on secured channel.
 223  *
 224  * @return  The number of bytes sent on the network. Returns 0 on error.
 225  * @remarks isSecure will be ignored when isMulticast is true.
 226  */
 227 uint32_t CAEthernetSendData(const char *remoteAddress, const uint32_t port,
 228                             const void *data, const uint32_t dataLength,
 229                             CABool_t isMulticast, CABool_t isSecure);
 230
 231 /**
 232  * @brief  Callback to be notified when Ethernet adapter connection state changes.
 233  *
 234  * @param  ipAddress    [IN] IP address of remote OIC device.
 235  * @param  status       [IN] Connection status either #CA_INTERFACE_UP or #CA_INTERFACE_DOWN.
 236  * @return  NONE
 237  * @pre  Callback must be registered using CAEthernetSetConnectionStateChangeCallback()
 238  */
 239 typedef void (*CAEthernetConnectionStateChangeCallback)(const char *ipAddress,
 240                                                         const CANetworkStatus_t status);
 241
 242 /**
 243  * @brief Initialize Ethernet network monitor
 244  *
 245  * @param  threadPool [IN] Thread pool for managing network monitor thread.
 246  *
 247  * @return  #CA_STATUS_OK or Appropriate error code
 248  * @retval  #CA_STATUS_OK  Successful
 249  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 250  * @retval  #CA_STATUS_FAILED Initialization failed
 251  */
 252 CAResult_t CAEthernetInitializeNetworkMonitor(const u_thread_pool_t threadPool);
 253
 254 /**
 255  * @brief Terminate Ethernet network monitor
 256  * @return  NONE
 257  */
 258 void CAEthernetTerminateNetworkMonitor(void);
 259
 260 /**
 261  * @brief  Start network monitoring process.
 262  *
 263  * @return  #CA_STATUS_OK or Appropriate error code
 264  * @retval  #CA_STATUS_OK  Successful
 265  * @retval  #CA_STATUS_FAILED Operation failed
 266  */
 267 CAResult_t CAEthernetStartNetworkMonitor(void);
 268
 269 /**
 270  * @brief  Stop network monitoring process.
 271  *
 272  * @return  #CA_STATUS_OK or Appropriate error code
 273  * @retval  #CA_STATUS_OK  Successful
 274  * @retval  #CA_STATUS_FAILED Operation failed
 275  */
 276 CAResult_t CAEthernetStopNetworkMonitor(void);
 277
 278 /**
 279  * @brief  Get local adapter network information.
 280  *
 281  * @param  interfaceName [OUT] Local adapter interface name
 282  * @param  ipAddress     [OUT] IP address
 283  *
 284  * @return  #CA_STATUS_OK or Appropriate error code
 285  * @retval  #CA_STATUS_OK  Successful
 286  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 287  * @retval  #CA_STATUS_FAILED Operation failed
 288  * @remarks  interfaceName and ipAddress must be freed using free().
 289  */
 290 CAResult_t CAEthernetGetInterfaceInfo(char **interfaceName, char **ipAddress);
 291
 292 /**
 293  * @brief  Get local adapter network subnet mask.
 294  *
 295  * @param  subnetMask [OUT] Local adapter interface subnet mask
 296  *
 297  * @return  #CA_STATUS_OK or Appropriate error code
 298  * @retval  #CA_STATUS_OK  Successful
 299  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 300  * @retval  #CA_STATUS_FAILED Operation failed
 301  * @remarks subnetMask must be freed using free().
 302  */
 303 CAResult_t CAEthernetGetInterfaceSubnetMask(char **subnetMask);
 304
 305 /**
 306  * @brief  Get Ethernet adapter connection state.
 307  *
 308  * @return  True if Ethernet adapter is connected, otherwise false
 309  */
 310 bool CAEthernetIsConnected(void);
 311
 312 /**
 313  * @brief  Set callback for receiving local ethernet adapter connection status.
 314  *
 315  * @param  callback [IN] Callback to be notified when local Ethernet adapter connection state changes.
 316  * @return NONE
 317  */
 318 void CAEthernetSetConnectionStateChangeCallback(CAEthernetConnectionStateChangeCallback callback);
 319
 320 #ifdef __cplusplus
 321 }
 322 #endif
 323
 324 #endif //_CA_ETHERNET_INTERFACE_H_