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