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