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