resource/csdk/connectivity/inc/caipinterface_singlethread.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_singlethread.h
  23  * @brief This file provides APIs IP client/server/network monitor modules
  24  */
  25
  26 #ifndef CA_IP_INTERFACE_SINGLETHREAD_H_
  27 #define CA_IP_INTERFACE_SINGLETHREAD_H_
  28
  29 #include <stdbool.h>
  30
  31 #include "cacommon.h"
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #endif
  37
  38 /**
  39  * @enum CAAdapterServerType_t
  40  * @brief Enum for defining different server types.
  41  */
  42 typedef enum
  43 {
  44     CA_UNICAST_SERVER = 0,      /**< Unicast Server */
  45     CA_MULTICAST_SERVER,        /**< Multicast Server */
  46     CA_SECURED_UNICAST_SERVER   /**< Secured Unicast Server */
  47 } CAAdapterServerType_t;
  48
  49 /**
  50  * @brief Callback to be notified on reception of any data from remote OIC devices.
  51  * @param  ipAddress    [IN] IP address of remote OIC device.
  52  * @param  port         [IN] Port number on which data is received.
  53  * @param  data         [IN] Data received from remote OIC device.
  54  * @param  dataLength   [IN] Length of data in bytes.
  55  * @return NONE
  56  * @pre  Callback must be registered using CAIPSetPacketReceiveCallback()
  57  */
  58 typedef void (*CAIPPacketReceivedCallback)(const char *ipAddress, uint16_t port,
  59                                                  const void *data, uint32_t dataLength);
  60
  61 /**
  62  * @brief  Callback to be notified when exception occures on multicast/unicast server.
  63  * @param  type  [IN] Type of server(#CAAdapterServerType_t)
  64  * @return NONE
  65  * @pre  Callback must be registered using CAIPSetExceptionCallback()
  66  */
  67 typedef void (*CAIPExceptionCallback)(CAAdapterServerType_t type);
  68
  69 /**
  70  * @brief  Initialize IP server
  71  * @return  #CA_STATUS_OK or Appropriate error code
  72  * @retval  #CA_STATUS_OK  Successful
  73  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
  74  * @retval  #CA_STATUS_FAILED Initialization failed
  75  */
  76 CAResult_t CAIPInitializeServer(void);
  77
  78 /**
  79  * @brief  Terminate IP server
  80  * @return NONE
  81  */
  82 void CAIPTerminateServer(void);
  83
  84 /**
  85  * @brief  Start multicast server for specified multicast address and port
  86  *
  87  * @param   localAddress        [IN]      Local adapter address to which server to be binded.
  88  * @param   multicastAddress    [IN]      Multicast group address.
  89  * @param   multicastPort       [IN,OUT]  Port number on which server will be running. If binding
  90                                           the port failed, server starts in the next available port.
  91  * @param   serverFD            [OUT]     Multicast server socket FD.
  92  *
  93  * @return  #CA_STATUS_OK or Appropriate error code
  94  * @retval  #CA_STATUS_OK  Successful
  95  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
  96  * @retval  #CA_SERVER_STARTED_ALREADY Multicast server is already started and running.
  97  * @retval  #CA_STATUS_FAILED Operation failed
  98  */
  99 CAResult_t CAIPStartMulticastServer(const char *localAddress, const char *multicastAddress,
 100                                           uint16_t multicastPort, int *serverFD);
 101
 102 /**
 103  * @brief  Start unicast server for specified local address and port
 104  *
 105  * @param  localAddress [IN]      Local adapter address to which server to be binded.
 106  * @param  port         [IN,OUT]  Port number on which server will be running. If binding
 107                                   the port failed, server starts in the next available port.
 108  * @param  forceStart   [IN]      Indicate whether to start server forcesfully on specified port
 109  *                                or not.
 110  * @param  serverFD     [OUT]     Unicast server socket FD.
 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 Unicast server is already started and running.
 116  * @retval  #CA_STATUS_FAILED Operation failed
 117  */
 118 CAResult_t CAIPStartUnicastServer(const char *localAddress, uint16_t *port,
 119                                         bool forceStart, int *serverFD);
 120
 121 /**
 122  * @brief  Stop multicast server.
 123  *
 124  * @return  #CA_STATUS_OK or Appropriate error code
 125  * @retval  #CA_STATUS_OK  Successful
 126  * @retval  #CA_STATUS_FAILED Operation failed
 127  */
 128 CAResult_t CAIPStopMulticastServer(void);
 129
 130 /**
 131  * @brief  Stop unicast server.
 132  *
 133  * @return  #CA_STATUS_OK or Appropriate error code
 134  * @retval  #CA_STATUS_OK  Successful
 135  * @retval  #CA_STATUS_FAILED Operation failed
 136  */
 137 CAResult_t CAIPStopUnicastServer();
 138
 139 #ifdef __WITH_DTLS__
 140 /**
 141  * @brief  Stop secured unicast server.
 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 CAIPStopSecureUnicastServer();
 148 #endif
 149
 150 /**
 151  * @brief  Get the Unicast Server Information if it is started
 152  * @param  ipAddress    [OUT] IP address on which server is binded and running.
 153  * @param  port         [OUT]Port number on which server is running
 154  * @param  serverFD     [OUT]Server socket fd.
 155  *
 156  * @return  #CA_STATUS_OK or Appropriate error code
 157  * @retval  #CA_STATUS_OK  Successful
 158  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 159  * @retval  #CA_STATUS_FAILED Operation failed
 160  * @remarks  ipAddress must be freed using free().
 161  */
 162 CAResult_t CAIPGetUnicastServerInfo(char **ipAddress, uint16_t *port, int *serverFD);
 163
 164 /**
 165  * @brief  Set this callback for receiving data packets from peer devices.
 166  * @param  callback   [IN] Callback to be notified on reception of unicast/multicast data packets.
 167  *
 168  * @return  NONE
 169  */
 170 void CAIPSetPacketReceiveCallback(CAIPPacketReceivedCallback callback);
 171
 172 /**
 173  * @brief  Pull the Received Data
 174  * @return NONE
 175  */
 176 void CAIPPullData();
 177
 178 /**
 179  * @brief  Set this callback for receiving exception notifications.
 180  *
 181  * @param  callback [IN] Callback to be notified on occurance of exception on running servers.
 182  *
 183  * @return  NONE
 184  */
 185 void CAIPSetExceptionCallback(CAIPExceptionCallback callback);
 186
 187 /**
 188  * @brief  Set socket description for sending unicast UDP data. Once the Unicast server is started,
 189  *         the same socket descriptor is used for sending the Unicast UDP data.
 190  *
 191  * @param  socketFD [IN]  Socket descriptor used for sending UDP data.
 192  * @return  NONE
 193  */
 194 void CAIPSetUnicastSocket(int socketFD);
 195
 196 /**
 197  * @brief  Set the port number for sending unicast UDP data
 198  * @param  port [IN] Port number used for sending UDP data.
 199  * @return NONE
 200  */
 201 void CAIPSetUnicastPort(uint16_t port);
 202
 203 #ifdef __WITH_DTLS__
 204 /**
 205  * @brief  Set socket description for sending secured (encrypted) unicast UDP data
 206  *
 207  * @param socketFD [IN] Socket descriptor used for sending secured (encrypted) UDP data.
 208  * @return  NONE
 209  */
 210 void CAIPSetSecureUnicastSocket(int socketFD);
 211 #endif
 212
 213 /**
 214  * @brief  API to send unicast UDP data
 215  *
 216  * @param  remoteAddress    [IN] IP address to which data needs to be sent.
 217  * @param  port             [IN] Port to which data needs to be send.
 218  * @param  buf              [IN] Data to be send.
 219  * @param  bufLen           [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  */
 224 uint32_t CAIPSendData(const char *remoteAddress, uint16_t port,
 225                             const char *buf, uint32_t bufLen, bool isMulticast);
 226
 227 /**
 228  * @brief  Callback to be notified when IP adapter connection state changes.
 229  *
 230  * @param  ipAddress    [IN] IP address of remote OIC device.
 231  * @param  status       [IN] Connection status either #CA_INTERFACE_UP or #CA_INTERFACE_DOWN.
 232  * @return  NONE
 233  * @pre  Callback must be registered using CAIPSetConnectionStateChangeCallback()
 234  */
 235 typedef void (*CAIPConnectionStateChangeCallback)(const char *ipAddress,
 236                                                         CANetworkStatus_t status);
 237
 238 /**
 239  * @brief Initialize IP network monitor
 240  * @return  #CA_STATUS_OK or Appropriate error code
 241  * @retval  #CA_STATUS_OK  Successful
 242  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 243  * @retval  #CA_STATUS_FAILED Initialization failed
 244  */
 245 CAResult_t CAIPInitializeNetworkMonitor(void);
 246
 247 /**
 248  * @brief Terminate IP network monitor
 249  * @return  NONE
 250  */
 251 void CAIPTerminateNetworkMonitor(void);
 252
 253 /**
 254  * @brief  Start network monitoring process.
 255  *
 256  * @return  #CA_STATUS_OK or Appropriate error code
 257  * @retval  #CA_STATUS_OK  Successful
 258  * @retval  #CA_STATUS_FAILED Operation failed
 259  */
 260 CAResult_t CAIPStartNetworkMonitor(void);
 261
 262 /**
 263  * @brief  Stop network monitoring process.
 264  *
 265  * @return  #CA_STATUS_OK or Appropriate error code
 266  * @retval  #CA_STATUS_OK  Successful
 267  * @retval  #CA_STATUS_FAILED Operation failed
 268  */
 269 CAResult_t CAIPStopNetworkMonitor(void);
 270
 271 /**
 272  * @brief  Get local adapter network information.
 273  *
 274  * @param  interfaceName [OUT] Local adapter interface name
 275  * @param  ipAddress     [OUT] IP address
 276  *
 277  * @return  #CA_STATUS_OK or Appropriate error code
 278  * @retval  #CA_STATUS_OK  Successful
 279  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 280  * @retval  #CA_STATUS_FAILED Operation failed
 281  * @remarks  interfaceName and ipAddress must be freed using free().
 282  */
 283 CAResult_t CAIPGetInterfaceInfo(char **ipAddress, char **interfaceName);
 284
 285 /**
 286  * @brief  Get Ethernet adapter connection state.
 287  *
 288  * @return  True if Ethernet adapter is connected, otherwise false
 289  */
 290 bool CAIPIsConnected(void);
 291
 292 /**
 293  * @brief  Set callback for receiving local ethernet adapter connection status.
 294  *
 295  * @param  callback [IN] Callback to be notified when local Ethernet adapter connection state
 296  *                       changes.
 297  * @return NONE
 298  */
 299 void CAIPSetConnectionStateChangeCallback
 300                 (CAIPConnectionStateChangeCallback callback);
 301
 302 #ifdef __cplusplus
 303 }
 304 #endif
 305
 306 #endif /* CA_IP_INTERFACE_SINGLETHREAD_H_ */
 307