resource/csdk/connectivity/inc/cawifiinterface.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 cawifiinterface.h
  23  * @brief This file provides APIs wifi client/server/network monitor modules
  24  */
  25
  26 #ifndef _CA_WIFI_INTERFACE_
  27 #define _CA_WIFI_INTERFACE_
  28
  29 #include <stdbool.h>
  30
  31 #include "cacommon.h"
  32 #include "uthreadpool.h"
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #endif
  38
  39 /**
  40  * @enum CAAdapterServerType_t
  41  * @brief Enum for defining different server types.
  42  */
  43 typedef enum
  44 {
  45     CA_UNICAST_SERVER = 0,
  46     CA_MULTICAST_SERVER,
  47     CA_SECURED_UNICAST_SERVER
  48 } CAAdapterServerType_t;
  49
  50 /**
  51  * @fn  CAWiFiPacketReceivedCallback
  52  * @brief  Callback to be notified on receival of any data from remote OIC devices.
  53  *
  54  * @param[in]  ipAddress  IP address of remote OIC device.
  55  * @param[in]  port  Port number on which data is received.
  56  * @param[in]  data  Data received from remote OIC device.
  57  * @param[in]  dataLength  Length of data in bytes.
  58  *
  59  * @pre  Callback must be registered using CAWiFiSetPacketReceiveCallback()
  60  */
  61 typedef void (*CAWiFiPacketReceivedCallback)(const char *ipAddress, const uint32_t port,
  62         const void *data, const uint32_t dataLength);
  63
  64 /**
  65  * @fn  CAWiFiExceptionCallback
  66  * @brief  Callback to be notified when exception occures on multicast/unicast server.
  67  *
  68  * @param[in]  type  Type of server either #CA_UNICAST_SERVER or $CA_MULTICAST_SERVER
  69  *
  70  * @pre  Callback must be registered using CAWiFiSetExceptionCallback()
  71  */
  72 typedef void (*CAWiFiExceptionCallback)(CAAdapterServerType_t type);
  73
  74 /**
  75  * @fn  CAWiFiInitializeServer
  76  * @brief  API to initialize Wifi server
  77  *
  78  * @param[in]  threadPool  Thread pool for managing Unicast/Multicast server threads.
  79  *
  80  * @return  #CA_STATUS_OK on success otherwise proper 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 CAWiFiInitializeServer(const u_thread_pool_t threadPool);
  86
  87 #ifdef ARDUINO
  88 /**
  89  * @fn  CAWiFiInitializeServer
  90  * @brief  API to initialize Wifi server
  91  *
  92  * @return  #CA_STATUS_OK on success otherwise proper error code.
  93  * @retval  #CA_STATUS_OK  Successful
  94  * @retval  #CA_STATUS_FAILED Initialization failed
  95  */
  96 CAResult_t CAWiFiInitializeServer(void);
  97 #endif //ARDUINO
  98
  99 /**
 100  * @fn  CAWiFiTerminateServer
 101  * @brief  API to terminate Wifi server
 102  */
 103 void CAWiFiTerminateServer(void);
 104
 105 /**
 106  * @fn  CAWiFiStartMulticastServer
 107  * @brief  API to start multicast server for specified multicast address and port
 108  *
 109  * @param[in]  localAddress  Local adapter address to which server to be binded.
 110  * @param[in]  multicastAddress  Multicast group address.
 111  * @param[in]  multicastPort  Port number on which server to be running.
 112  * @param[out]  serverFD  Multicast server socket FD.
 113  *
 114  * @return  #CA_STATUS_OK on success otherwise proper error code.
 115  * @retval  #CA_STATUS_OK  Successful
 116  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 117  * @retval  #CA_SERVER_STARTED_ALREADY Multicast server is already started and running.
 118  * @retval  #CA_STATUS_FAILED Operation failed
 119  */
 120 CAResult_t CAWiFiStartMulticastServer(const char *localAddress, const char *multicastAddress,
 121                                       const int16_t multicastPort, int32_t *serverFD);
 122
 123 /**
 124  * @fn  CAWiFiStartUnicastServer
 125  * @brief  API to start unicast server for specified local address and port
 126  *
 127  * @param[in]  localAddress  Local adapter address to which server to be binded.
 128  * @param[in][out]  port  Port number on which server to be running.
 129  * Port number on which server actually started will be returned.
 130  * @param[in]  forceStart  Indicate whether to start server forcesfully on specified port or not.
 131  * @param[out]  serverFD  Unicast server socket FD.
 132  *
 133  * @return  #CA_STATUS_OK on success otherwise proper error code.
 134  * @retval  #CA_STATUS_OK  Successful
 135  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 136  * @retval  #CA_SERVER_STARTED_ALREADY Unicast server is already started and running.
 137  * @retval  #CA_STATUS_FAILED Operation failed
 138  */
 139 CAResult_t CAWiFiStartUnicastServer(const char *localAddress, int16_t *port,
 140                                     const bool forceStart, int32_t *serverFD);
 141
 142 /**
 143  * @fn  CAWiFiStopMulticastServer
 144  * @brief  API to stop multicast server.
 145  *
 146  * @return  #CA_STATUS_OK on success otherwise proper error code.
 147  * @retval  #CA_STATUS_OK  Successful
 148  * @retval  #CA_STATUS_FAILED Operation failed
 149  */
 150 CAResult_t CAWiFiStopMulticastServer(void);
 151
 152 /**
 153  * @fn  CAWiFiStopUnicastServer
 154  * @brief  API to stop unicast server.
 155  *
 156  * @return  #CA_STATUS_OK on success otherwise proper error code.
 157  * @retval  #CA_STATUS_OK  Successful
 158  * @retval  #CA_STATUS_FAILED Operation failed
 159  */
 160 CAResult_t CAWiFiStopUnicastServer();
 161
 162 /**
 163  * @fn  CAWiFiGetUnicastServerInfo
 164  * @brief  API to get running unicast server information.
 165  * @remarks  @ipAddress must be freed using free().
 166  *
 167  * @param[in]  ipAddress  IP address on which server is binded and running.
 168  * @param[out]  port  Port number on which server is running
 169  * @param[out]  serverFD  Server socket fd.
 170  *
 171  * @return  #CA_STATUS_OK on success otherwise proper error code.
 172  * @retval  #CA_STATUS_OK  Successful
 173  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 174  * @retval  #CA_STATUS_FAILED Operation failed
 175  */
 176 CAResult_t CAWiFiGetUnicastServerInfo(char **ipAddress, int16_t *port, int32_t *serverFD);
 177
 178 /**
 179  * @fn  CAWiFiSetPacketReceiveCallback
 180  * @brief  API to set callback for receiving data packets from peer devices.
 181  *
 182  * @param[in]  callback Callback to be notified on receival of unicast/multicast data packets.
 183  *
 184  * @return  #CA_STATUS_OK on success otherwise proper error code.
 185  * @retval  #CA_STATUS_OK  Successful
 186  * @retval  #CA_STATUS_FAILED Operation failed
 187  */
 188 void CAWiFiSetPacketReceiveCallback(CAWiFiPacketReceivedCallback callback);
 189
 190 #ifdef ARDUINO
 191 /**
 192  * @fn  CAWiFiReadData
 193  * @brief  API to pull data
 194  */
 195 void CAWiFiPullData();
 196 #endif // ARDUINO
 197
 198 /**
 199  * @fn  CAWiFiSetExceptionCallback
 200  * @brief  API to set callback for receiving exception notifications.
 201  *
 202  * @param[in]  callback  Callback to be notified on occurance of exception running servers.
 203  *
 204  * @return  #CA_STATUS_OK on success otherwise proper error code.
 205  * @retval  #CA_STATUS_OK  Successful
 206  * @retval  #CA_STATUS_FAILED Operation failed
 207  */
 208 void CAWiFiSetExceptionCallback(CAWiFiExceptionCallback callback);
 209
 210 /**
 211  * @fn  CAWiFiSetUnicastSocket
 212  * @brief  API to set socket description for sending unicast UDP data
 213  *
 214  * @param[in]  socketFD  Socket descriptor used for sending UDP data.
 215  *
 216  */
 217 void CAWiFiSetUnicastSocket(const int32_t socketFD);
 218
 219 /**
 220  * @fn  CAWiFiSendUnicastData
 221  * @brief  API to send unicast UDP data
 222  *
 223  * @param[in]  remoteAddress  IP address to which data needs to be send.
 224  * @param[in]  port  Port to which data needs to be send.
 225  * @param[in]  data  Data to be send.
 226  * @param[in]  dataLength  Length of data in bytes
 227  * @param[in]  isMulticast  whether data needs to be sent to multicast ip
 228  * @param[out]  sentLength  Number of bytes actually sent
 229  *
 230  * @return  #CA_STATUS_OK on success otherwise proper error code.
 231  * @retval  #CA_STATUS_OK  Successful
 232  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 233  * @retval  #CA_STATUS_FAILED Operation failed
 234  */
 235 uint32_t CAWiFiSendData(const char *remoteAddress, const uint32_t port,
 236                         const void *data, const uint32_t dataLength, bool isMulticast);
 237
 238 /**
 239  * @fn  CAWiFiConnectionStateChangeCallback
 240  * @brief  Callback to be notified when wifi adapter connection state changes.
 241  *
 242  * @param[in]  ipAddress  IP address of remote OIC device.
 243  * @param[in]  status  Connection status either #CA_INTERFACE_UP or #CA_INTERFACE_DOWN.
 244  *
 245  * @pre  Callback must be registered using CAWiFiSetConnectionStateChangeCallback()
 246  */
 247 typedef void (*CAWiFiConnectionStateChangeCallback)(const char *ipAddress,
 248         const CANetworkStatus_t status);
 249
 250 /**
 251  * @fn  CAWiFiInitializeNetworkMonitor
 252  * @brief  API to initialize Wifi network monitor
 253  *
 254  * @param[in]  threadPool  Thread pool for managing network monitor thread.
 255  *
 256  * @return  #CA_STATUS_OK on success otherwise proper error code.
 257  * @retval  #CA_STATUS_OK  Successful
 258  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 259  * @retval  #CA_STATUS_FAILED Initialization failed
 260  */
 261 CAResult_t CAWiFiInitializeNetworkMonitor(const u_thread_pool_t threadPool);
 262
 263 #ifdef ARDUINO
 264 /**
 265  * @fn  CAWiFiInitializeServer
 266  * @brief  API to initialize Wifi server
 267  *
 268  * @return  #CA_STATUS_OK on success otherwise proper error code.
 269  * @retval  #CA_STATUS_OK  Successful
 270  * @retval  #CA_STATUS_FAILED Initialization failed
 271  */
 272 CAResult_t CAWiFiInitializeNetworkMonitor(void);
 273 #endif //ARDUINO
 274
 275 /**
 276  * @fn  CAWiFiTerminateNetworkMonitor
 277  * @brief  API to terminate Wifi network monitor
 278  */
 279 void CAWiFiTerminateNetworkMonitor(void);
 280
 281 /**
 282  * @fn  CAWiFiStartNetworkMonitor
 283  * @brief  API to start network monitoring process.
 284  *
 285  * @return  #CA_STATUS_OK on success otherwise proper error code.
 286  * @retval  #CA_STATUS_OK  Successful
 287  * @retval  #CA_STATUS_FAILED Operation failed
 288  */
 289 CAResult_t CAWiFiStartNetworkMonitor(void);
 290
 291 /**
 292  * @fn  CAWiFiStopNetworkMonitor
 293  * @brief  API to stop network monitoring process.
 294  *
 295  * @return  #CA_STATUS_OK on success otherwise proper error code.
 296  * @retval  #CA_STATUS_OK  Successful
 297  * @retval  #CA_STATUS_FAILED Operation failed
 298  */
 299 CAResult_t CAWiFiStopNetworkMonitor(void);
 300
 301 /**
 302  * @fn  CAWiFiGetInterfaceInfo
 303  * @brief  API to get local adapter network information.
 304  * @remarks  @interfaceName and @ipAddress must be freed using free().
 305  *
 306  * @param[out]  interfaceName  Local adapter interface name
 307  * @param[out]  ipAddress  IP address
 308  *
 309  * @return  #CA_STATUS_OK on success otherwise proper error code.
 310  * @retval  #CA_STATUS_OK  Successful
 311  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 312  * @retval  #CA_STATUS_FAILED Operation failed
 313  */
 314 CAResult_t CAWiFiGetInterfaceInfo(char **interfaceName, char **ipAddress);
 315
 316 /**
 317  * @fn  CAWiFiIsConnected
 318  * @brief  API to get wifi adapter connection state.
 319  *
 320  * @return  true if wifi adapter is connected, otherwise false
 321  */
 322 bool CAWiFiIsConnected(void);
 323
 324 /**
 325  * @fn  CAWiFiSetConnectionStateChangeCallback
 326  * @brief  API to set callback for receiving local wifi adapter connection status.
 327  *
 328  * @param[in]  callback  Callback to be notified when local wifi adapter connection state changes.
 329  *
 330  */
 331 void CAWiFiSetConnectionStateChangeCallback(CAWiFiConnectionStateChangeCallback callback);
 332
 333 #ifdef __cplusplus
 334 }
 335 #endif
 336
 337 #endif //_CA_WIFI_INTERFACE_