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