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