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 for WIFI adapter - client, server, network monitor modules
  24  */
  25
  26 #ifndef _CA_WIFI_INTERFACE_H_
  27 #define _CA_WIFI_INTERFACE_H_
  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,      /**< Unicast Server */
  46     CA_MULTICAST_SERVER,        /**< Multicast Server */
  47     CA_SECURED_UNICAST_SERVER   /**< Secured Unicast Server */
  48 } CAAdapterServerType_t;
  49
  50 /**
  51  * @brief Callback to be notified on reception of any data from remote OIC devices.
  52  * @param  ipAddress    [IN] IP address of remote OIC device.
  53  * @param  port         [IN] Port number on which data is received.
  54  * @param  data         [IN] Data received from remote OIC device.
  55  * @param  dataLength   [IN] Length of data in bytes.
  56  * @param  isSecure     [IN] Indicates the data is secure or not.
  57  * @return NONE
  58  * @pre  Callback must be registered using CAWiFiSetPacketReceiveCallback()
  59  */
  60 typedef void (*CAWiFiPacketReceivedCallback)(const char *ipAddress, const uint32_t port,
  61         const void *data, const uint32_t dataLength, const CABool_t isSecure);
  62
  63 /**
  64  * @brief  Callback to be notified when exception occures on multicast/unicast server.
  65  * @param  type  [IN] Type of server(#CAAdapterServerType_t)
  66  * @return NONE
  67  * @pre  Callback must be registered using CAWiFiSetExceptionCallback()
  68  */
  69 typedef void (*CAWiFiExceptionCallback)(CAAdapterServerType_t type);
  70
  71 /**
  72  * @brief  Initialize WIFI server
  73  * @param   threadPool  [IN] Thread pool for managing Unicast/Multicast server threads.
  74  * @return  #CA_STATUS_OK or Appropriate error code
  75  * @retval  #CA_STATUS_OK  Successful
  76  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
  77  * @retval  #CA_STATUS_FAILED Initialization failed
  78  */
  79 CAResult_t CAWiFiInitializeServer(const u_thread_pool_t threadPool);
  80
  81
  82 /**
  83  * @brief  Terminate WIFI server
  84  * @return NONE
  85  */
  86 void CAWiFiTerminateServer(void);
  87
  88 /**
  89  * @brief  Start multicast server for specified multicast address and port
  90  *
  91  * @param   localAddress        [IN]      Local adapter address to which server to be binded.
  92  * @param   multicastAddress    [IN]      Multicast group address.
  93  * @param   multicastPort       [IN,OUT]  Port number on which server will be running. If binding
  94                                           the port failed, server starts in the next available port.
  95  * @param   serverFD            [OUT]     Multicast server socket FD.
  96  *
  97  * @return  #CA_STATUS_OK or Appropriate error code
  98  * @retval  #CA_STATUS_OK  Successful
  99  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 100  * @retval  #CA_SERVER_STARTED_ALREADY Multicast server is already started and running.
 101  * @retval  #CA_STATUS_FAILED Operation failed
 102  */
 103 CAResult_t CAWiFiStartMulticastServer(const char *localAddress, const char *multicastAddress,
 104                                       const int16_t multicastPort, int32_t *serverFD);
 105
 106 /**
 107  * @brief  Start unicast server for specified local address and port
 108  *
 109  * @param  localAddress [IN]      Local adapter address to which server to be binded.
 110  * @param  port         [IN,OUT]  Port number on which server will be running. If binding
 111                                   the port failed, server starts in the next available port.
 112  * @param  forceStart   [IN]      Indicate whether to start server forcesfully on specified port
 113  *                                or not.
 114  * @param  isSecured    [IN]      True if the secure server to be started, otherwise false.
 115  * @param  serverFD     [OUT]     Unicast server socket FD.
 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 Unicast server is already started and running.
 121  * @retval  #CA_STATUS_FAILED Operation failed
 122  */
 123 CAResult_t CAWiFiStartUnicastServer(const char *localAddress, int16_t *port,
 124                                     const bool forceStart, const CABool_t isSecured,
 125                                     int32_t *serverFD);
 126
 127 /**
 128  * @brief  Stop multicast server.
 129  *
 130  * @return  #CA_STATUS_OK or Appropriate error code
 131  * @retval  #CA_STATUS_OK  Successful
 132  * @retval  #CA_STATUS_FAILED Operation failed
 133  */
 134 CAResult_t CAWiFiStopMulticastServer(void);
 135
 136 /**
 137  * @brief  Stop unicast server.
 138  *
 139  * @return  #CA_STATUS_OK or Appropriate error code
 140  * @retval  #CA_STATUS_OK  Successful
 141  * @retval  #CA_STATUS_FAILED Operation failed
 142  */
 143 CAResult_t CAWiFiStopUnicastServer();
 144
 145 #ifdef __WITH_DTLS__
 146 /**
 147  * @brief  Stop secured unicast server.
 148  *
 149  * @return  #CA_STATUS_OK or Appropriate error code
 150  * @retval  #CA_STATUS_OK  Successful
 151  * @retval  #CA_STATUS_FAILED Operation failed
 152  */
 153 CAResult_t CAWiFiStopSecureUnicastServer();
 154 #endif
 155
 156 /**
 157  * @brief  Get the Unicast Server Information if it is started
 158  *
 159  * @param  isSecured    [IN] true if the secure server information needed, otherwise false.
 160  * @param  ipAddress    [OUT] IP address on which server is binded and running.
 161  * @param  port         [OUT]Port number on which server is running
 162  * @param  serverFD     [OUT]Server socket fd.
 163  *
 164  * @return  #CA_STATUS_OK or Appropriate error code
 165  * @retval  #CA_STATUS_OK  Successful
 166  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 167  * @retval  #CA_STATUS_FAILED Operation failed
 168  * @remarks  ipAddress must be freed using free().
 169  */
 170 CAResult_t CAWiFiGetUnicastServerInfo(const CABool_t isSecured, char **ipAddress, int16_t *port,
 171                                       int32_t *serverFD);
 172
 173 /**
 174  * @brief  Set this callback for receiving data packets from peer devices.
 175  *
 176  * @param  callback   [IN] Callback to be notified on reception of unicast/multicast data packets.
 177  *
 178  * @return  NONE
 179  */
 180 void CAWiFiSetPacketReceiveCallback(CAWiFiPacketReceivedCallback callback);
 181
 182 /**
 183  * @brief  Set this callback for receiving exception notifications.
 184  *
 185  * @param  callback [IN] Callback to be notified on occurance of exception on running servers.
 186  *
 187  * @return  NONE
 188  */
 189 void CAWiFiSetExceptionCallback(CAWiFiExceptionCallback callback);
 190
 191 /**
 192  * @brief  Set socket description for sending unicast UDP data. Once the Unicast server is started,
 193  *         the same socket descriptor is used for sending the Unicast UDP data.
 194  *
 195  * @param  socketFD [IN]  Socket descriptor used for sending UDP data.
 196  * @return  NONE
 197  */
 198 void CAWiFiSetUnicastSocket(const int32_t socketFD);
 199
 200 #ifdef __WITH_DTLS__
 201 /**
 202  * @brief  Set socket description for sending secured (encrypted) unicast UDP data
 203  *
 204  * @param socketFD [IN] Socket descriptor used for sending secured (encrypted) UDP data.
 205  * @return  NONE
 206  */
 207 void CAWiFiSetSecureUnicastSocket(const int32_t socketFD);
 208 #endif
 209
 210 /**
 211  * @brief  API to send unicast UDP data
 212  *
 213  * @param  remoteAddress    [IN] IP address to which data needs to be sent.
 214  * @param  port             [IN] Port to which data needs to be send.
 215  * @param  data             [IN] Data to be send.
 216  * @param  dataLength       [IN] Length of data in bytes
 217  * @param  isMulticast      [IN] Whether data needs to be sent to multicast ip
 218  * @param  isSecured        [IN] Whether data to be sent on secured channel.
 219  *
 220  * @return  The number of bytes sent on the network. Returns 0 on error.
 221  * @remarks isSecure will be ignored when isMulticast is true.
 222  */
 223 uint32_t CAWiFiSendData(const char *remoteAddress, const uint32_t port,
 224                         const void *data, const uint32_t dataLength,
 225                         CABool_t isMulticast, CABool_t isSecured);
 226
 227 /**
 228  * @brief  Callback to be notified when wifi 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 CAWiFiSetConnectionStateChangeCallback()
 234  */
 235 typedef void (*CAWiFiConnectionStateChangeCallback)(const char *ipAddress,
 236         const CANetworkStatus_t status);
 237
 238 /**
 239  * @brief Initialize Wifi network monitor
 240  *
 241  * @param  threadPool [IN] Thread pool for managing network monitor thread.
 242  *
 243  * @return  #CA_STATUS_OK or Appropriate error code
 244  * @retval  #CA_STATUS_OK  Successful
 245  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 246  * @retval  #CA_STATUS_FAILED Initialization failed
 247  */
 248 CAResult_t CAWiFiInitializeNetworkMonitor(const u_thread_pool_t threadPool);
 249
 250 /**
 251  * @brief Terminate WIFI network monitor
 252  * @return  NONE
 253  */
 254 void CAWiFiTerminateNetworkMonitor(void);
 255
 256 /**
 257  * @brief  Start network monitoring process.
 258  *
 259  * @return  #CA_STATUS_OK or Appropriate error code
 260  * @retval  #CA_STATUS_OK  Successful
 261  * @retval  #CA_STATUS_FAILED Operation failed
 262  */
 263 CAResult_t CAWiFiStartNetworkMonitor(void);
 264
 265 /**
 266  * @brief  Stop network monitoring process.
 267  *
 268  * @return  #CA_STATUS_OK or Appropriate error code
 269  * @retval  #CA_STATUS_OK  Successful
 270  * @retval  #CA_STATUS_FAILED Operation failed
 271  */
 272 CAResult_t CAWiFiStopNetworkMonitor(void);
 273
 274 /**
 275  * @brief  Get local adapter network information.
 276  *
 277  * @param  interfaceName [OUT] Local adapter interface name
 278  * @param  ipAddress     [OUT] IP address
 279  *
 280  * @return  #CA_STATUS_OK or Appropriate error code
 281  * @retval  #CA_STATUS_OK  Successful
 282  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 283  * @retval  #CA_STATUS_FAILED Operation failed
 284  * @remarks  interfaceName and ipAddress must be freed using free().
 285  */
 286 CAResult_t CAWiFiGetInterfaceInfo(char **interfaceName, char **ipAddress);
 287
 288 /**
 289  * @brief  Get local adapter network subnet mask.
 290  *
 291  * @param  subnetMask [OUT] Local adapter interface subnet mask
 292  *
 293  * @return  #CA_STATUS_OK or Appropriate error code
 294  * @retval  #CA_STATUS_OK  Successful
 295  * @retval  #CA_STATUS_INVALID_PARAM Invalid input data
 296  * @retval  #CA_STATUS_FAILED Operation failed
 297  * @remarks subnetMask must be freed using free().
 298  */
 299 CAResult_t CAWiFiGetInterfaceSubnetMask(char **subnetMask);
 300
 301 /**
 302  * @brief  Get WIFI adapter connection state.
 303  *
 304  * @return  True if WIFI adapter is connected, otherwise false
 305  */
 306 bool CAWiFiIsConnected(void);
 307
 308 /**
 309  * @brief  Set callback for receiving local wifi adapter connection status.
 310  *
 311  * @param  callback [IN] Callback to be notified when local WIFI adapter connection state changes.
 312  * @return NONE
 313  */
 314 void CAWiFiSetConnectionStateChangeCallback(CAWiFiConnectionStateChangeCallback callback);
 315
 316 #ifdef __cplusplus
 317 }
 318 #endif
 319
 320 #endif //_CA_WIFI_INTERFACE_H_