resource/csdk/connectivity/inc/caipinterface.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 caipinterface.h
  23  * @brief This file provides APIs IP client/server/network monitor modules
  24  */
  25
  26 #ifndef CA_IP_INTERFACE_H_
  27 #define CA_IP_INTERFACE_H_
  28
  29 #include <stdbool.h>
  30
  31 #include "cacommon.h"
  32 #include "cathreadpool.h"
  33 #include "uarraylist.h"
  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  *
  54  * @param  endpoint     [IN] network endpoint description
  55  * @param  data         [IN] Data received from remote OIC device.
  56  * @param  dataLength   [IN] Length of data in bytes.
  57  *
  58  * @return NONE
  59  * @pre  Callback must be registered using CAIPSetPacketReceiveCallback()
  60  */
  61 typedef void (*CAIPPacketReceivedCallback)(const CAEndpoint_t *endpoint,
  62                                            const void *data,
  63                                            uint32_t dataLength);
  64
  65 /**
  66   * @brief Callback to notify error in the IP adapter
  67   *
  68   * @param  endpoint     [IN] [IN] network endpoint description
  69   * @param  data         [IN] Data sent/received
  70   * @param  dataLength   [IN] Length of data in bytes.
  71   * @param  result       [IN] result of request from R.I
  72   * @return NONE
  73   * @pre  Callback must be registered using CAIPSetPacketReceiveCallback()
  74  */
  75 typedef void (*CAIPErrorHandleCallback)(const CAEndpoint_t *endpoint, const void *data,
  76                                         uint32_t dataLength, CAResult_t result);
  77
  78 /**
  79  * @brief  Callback to be notified when exception occures on multicast/unicast server.
  80  * @param  type  [IN] Type of server(#CAAdapterServerType_t)
  81  * @return NONE
  82  * @pre  Callback must be registered using CAIPSetExceptionCallback()
  83  */
  84 typedef void (*CAIPExceptionCallback)(CAAdapterServerType_t type);
  85
  86 /**
  87  * @brief  Initialize IP server
  88  *
  89  * @param   threadPool  [IN] Thread pool for managing Unicast/Multicast server threads.
  90  *
  91  * @return  #CA_STATUS_OK or Appropriate error code
  92  * @retval  #CA_STATUS_OK  Successful
  93  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
  94  * @retval  #CA_STATUS_FAILED Initialization failed
  95  */
  96 CAResult_t CAIPInitializeServer(const ca_thread_pool_t threadPool);
  97
  98 /**
  99  * @brief  Terminate IP server
 100  * @return NONE
 101  */
 102 void CAIPTerminateServer();
 103
 104 /**
 105  * @brief  Start multicast server for specified multicast address and port
 106  *
 107  * @param   localAddress        [IN]      Local adapter address to which server to be binded.
 108  * @param   multicastAddress    [IN]      Multicast group address.
 109  * @param   multicastPort       [IN,OUT]  Port number on which server will be running. If binding
 110  *                                        the port failed, server starts in the next available port.
 111  *
 112  * @return  #CA_STATUS_OK or Appropriate error code
 113  * @retval  #CA_STATUS_OK  Successful
 114  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 115  * @retval  #CA_SERVER_STARTED_ALREADY Multicast server is already started and running.
 116  * @retval  #CA_STATUS_FAILED Operation failed
 117  */
 118 CAResult_t CAIPStartMulticastServer(const char *localAddress, const char *multicastAddress,
 119                                     uint16_t multicastPort);
 120
 121 /**
 122  * @brief  Start unicast server for specified local address and port
 123  *
 124  * @param  localAddress [IN]      Local adapter address to which server to be binded.
 125  * @param  port         [IN,OUT]  Port number on which server will be running. If binding
 126  *                                the port failed, server starts in the next available port.
 127  * @param  secured      [IN]      True if the secure server to be started, otherwise false.
 128  *
 129  * @return  #CA_STATUS_OK or Appropriate error code
 130  * @retval  #CA_STATUS_OK  Successful
 131  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 132  * @retval  #CA_SERVER_STARTED_ALREADY Unicast server is already started and running.
 133  * @retval  #CA_STATUS_FAILED Operation failed
 134  */
 135 CAResult_t CAIPStartUnicastServer(const char *localAddress, uint16_t *port, bool secured);
 136
 137 /**
 138  * @brief  Stop servers that are running in particular interface address.
 139  *
 140  * @param   interfaceAddress  [IN] interface address in which servers are running.
 141  *
 142  * @return  #CA_STATUS_OK or Appropriate error code
 143  * @retval  #CA_STATUS_OK  Successful
 144  * @retval  #CA_STATUS_FAILED Operation failed
 145  */
 146 CAResult_t CAIPStopServer(const char *interfaceAddress);
 147
 148 /**
 149  * @brief  Used to stop all unicast and multicast servers.
 150  *
 151  * @return  #CA_STATUS_OK or Appropriate error code
 152  * @retval  #CA_STATUS_OK  Successful
 153  * @retval  #CA_STATUS_FAILED Operation failed
 154  */
 155 CAResult_t CAIPStopAllServers();
 156
 157 /**
 158  * @brief  Used to get the socket fd based on index value of server info list.
 159  *
 160  * @param   index      [IN] Index where we need socket fd value.
 161  * @param   isSecured  [IN] For secured unicast server or normal server.
 162  *
 163  * @return  positive value on success and -1 on error.
 164  */
 165 int CAGetSocketFdFromUnicastIPServerbyIndex(int16_t index, bool isSecured);
 166
 167 /**
 168  * @brief  Used to get the number of unicast server currently running.
 169  *
 170  * @param   isSecured  [IN] To identify whether its secured unicast server or normal server.
 171  *
 172  * @return  positive value on success and -1 on error.
 173  */
 174 int16_t CAGetNumberOfUnicastIPServers(bool isSecured);
 175
 176 /**
 177  * @brief  Used to get the stored socket fd for corresponding ipAddress.
 178  *
 179  * @param   ipAddress    [IN] IpAddress of server.
 180  * @param   isSecured    [IN] Used to check the server is secured or not.
 181  * @param   isMulticast  [IN] To identify whether its for multicast or unicast.
 182  *
 183  * @return  socket fd on success and -1 on error.
 184  */
 185 int CAGetSocketFdFromUnicastIPServer(const char *ipAddress, bool isSecured, bool isMulticast);
 186
 187 /**
 188  * @brief  Used to get the port number to the corresponding ip for giving interface info.
 189  *
 190  * @param   ipAddress  [IN] IpAddress of server.
 191  * @param   isSecured  [IN] Used to check the server is secured or not.
 192  *
 193  * @return  port number on success and -1 on error.
 194  */
 195 uint16_t CAGetServerPortNum(const char *ipAddress, bool isSecured);
 196
 197 /**
 198  * @brief  Used to get the port number for corresponding ipAddress.
 199  *
 200  * @param   serverInfoList  [OUT] ServerInfoList holds unicast and multicast server informations.
 201  *
 202  * @return  #CA_STATUS_OK or Appropriate error code
 203  * @retval  #CA_STATUS_OK  Successful
 204  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 205  * @retval  #CA_STATUS_FAILED Initialization failed
 206  */
 207 CAResult_t CAGetIPServerInfoList(u_arraylist_t **serverInfoList);
 208
 209 /**
 210  * @brief  Set this callback for receiving data packets from peer devices.
 211  *
 212  * @param  callback   [IN] Callback to be notified on reception of unicast/multicast data packets.
 213  *
 214  * @return  NONE
 215  */
 216 void CAIPSetPacketReceiveCallback(CAIPPacketReceivedCallback callback);
 217
 218 /**
 219  * @brief  Set this callback for receiving exception notifications.
 220  *
 221  * @param  callback [IN] Callback to be notified on occurance of exception on running servers.
 222  *
 223  * @return  NONE
 224  */
 225 void CAIPSetExceptionCallback(CAIPExceptionCallback callback);
 226
 227 /**
 228  * @brief  Set socket description for sending unicast UDP data. Once the Unicast server is started,
 229  *         the same socket descriptor is used for sending the Unicast UDP data.
 230  *
 231  * @param  socketFD [IN]  Socket descriptor used for sending UDP data.
 232  * @return  NONE
 233  */
 234 void CAIPSetUnicastSocket(int socketFD);
 235
 236 /**
 237  * @brief  Set the port number for sending unicast UDP data
 238  * @param  port [IN] Port number used for sending UDP data.
 239  * @return NONE
 240  */
 241 void CAIPSetUnicastPort(uint16_t port);
 242
 243 /**
 244  * @brief  API to send unicast UDP data
 245  *
 246  * @param  endpoint         [IN] complete network address to send to
 247  * @param  data             [IN] Data to be send.
 248  * @param  dataLength       [IN] Length of data in bytes
 249  * @param  isMulticast      [IN] Whether data needs to be sent to multicast ip
 250  *
 251  * @return  The number of bytes sent on the network. Returns 0 on error.
 252  * @remarks isSecure will be ignored when isMulticast is true.
 253  */
 254 uint32_t CAIPSendData(const CAEndpoint_t *endpoint,
 255                       const void *data,
 256                       uint32_t dataLength,
 257                       bool isMulticast);
 258
 259 /**
 260  * @brief  Callback to be notified when IP adapter connection state changes.
 261  *
 262  * @param  ipAddress    [IN] IP address of remote OIC device.
 263  * @param  status       [IN] Connection status either #CA_INTERFACE_UP or #CA_INTERFACE_DOWN.
 264  * @return  NONE
 265  * @pre  Callback must be registered using CAIPSetConnectionStateChangeCallback()
 266  */
 267 typedef void (*CAIPConnectionStateChangeCallback)(const char *ipAddress,
 268                                                   CANetworkStatus_t status);
 269
 270 /**
 271  * @brief Initialize IP network monitor
 272  *
 273  * @param  threadPool [IN] Thread pool for managing network monitor thread.
 274  *
 275  * @return  #CA_STATUS_OK or Appropriate error code
 276  * @retval  #CA_STATUS_OK  Successful
 277  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 278  * @retval  #CA_STATUS_FAILED Initialization failed
 279  */
 280 CAResult_t CAIPInitializeNetworkMonitor(const ca_thread_pool_t threadPool);
 281
 282 /**
 283  * @brief Terminate IP network monitor by removing interface list.
 284  * @return  NONE
 285  */
 286 void CAIPTerminateNetworkMonitor();
 287
 288 /**
 289  * @brief  Start network monitoring process. It will start the monitor thread.
 290  *
 291  * @return  #CA_STATUS_OK or Appropriate error code
 292  * @retval  #CA_STATUS_OK  Successful
 293  * @retval  #CA_STATUS_FAILED Operation failed
 294  */
 295 CAResult_t CAIPStartNetworkMonitor();
 296
 297 /**
 298  * @brief  Stop network monitoring process. It will stop the monitor thread.
 299  *
 300  * @return  #CA_STATUS_OK or Appropriate error code
 301  * @retval  #CA_STATUS_OK  Successful
 302  * @retval  #CA_STATUS_FAILED Operation failed
 303  */
 304 CAResult_t CAIPStopNetworkMonitor();
 305
 306 /**
 307  * @brief  Pull the Received Data
 308  * @return NONE
 309  */
 310 void CAIPPullData();
 311
 312 /**
 313  * @brief  Get local adapter network information.
 314  *
 315  * @param  netInterfaceList [OUT] network interface information list
 316  *
 317  * @return  #CA_STATUS_OK or Appropriate error code
 318  * @retval  #CA_STATUS_OK  Successful
 319  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 320  * @retval  #CA_STATUS_FAILED Operation failed
 321  * @remarks  interfaceName and ipAddress must be freed using free().
 322  */
 323 CAResult_t CAIPGetInterfaceInfo(u_arraylist_t **netInterfaceList);
 324
 325 /**
 326  * @brief  Get local adapter network subnet mask.
 327  *
 328  * @param  ipAddress  [IN]  IpAddress which is used for getting subnet mask.
 329  * @param  subnetMask [OUT] Local adapter interface subnet mask
 330  *
 331  * @return  #CA_STATUS_OK or Appropriate error code
 332  * @retval  #CA_STATUS_OK  Successful
 333  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 334  * @retval  #CA_STATUS_FAILED Operation failed
 335  * @remarks subnetMask must be freed using free().
 336  */
 337 CAResult_t CAIPGetInterfaceSubnetMask(const char *ipAddress, char **subnetMask);
 338
 339 /**
 340  * @brief  Get IP adapter connection state.
 341  *
 342  * @return  True if IP adapter is connected, otherwise false
 343  */
 344  bool CAIPIsConnected();
 345
 346 /**
 347  * @brief  Set callback for receiving local IP adapter connection status.
 348  *
 349  * @param  callback [IN] Callback to be notified when IP adapter connection state changes.
 350  * @return NONE
 351  */
 352 void CAIPSetConnectionStateChangeCallback(CAIPConnectionStateChangeCallback callback);
 353
 354 /**
 355  * @brief  Set callback for error handling
 356  *
 357  * @param  ipErrorCallback [IN] callback to notify error to the ipadapter
 358  * @return NONE
 359  */
 360 void CAIPSetErrorHandleCallback(CAIPErrorHandleCallback ipErrorCallback);
 361
 362 #ifdef __cplusplus
 363 }
 364 #endif
 365
 366 #endif /* CA_IP_INTERFACE_H_ */