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