resource/csdk/connectivity/inc/caleadapter.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 contains the APIs for LE adapters to be implemented.
  25  */
  26
  27 #ifndef CA_LEADAPTER_H_
  28 #define CA_LEADAPTER_H_
  29
  30 #include "cacommon.h"
  31 #include "caadapterinterface.h"
  32 #include "cathreadpool.h" /* for thread pool */
  33
  34 /**
  35  * BLE Interface APIs.
  36  */
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif
  41
  42 /**
  43  * @struct CALEData_t
  44  * @brief Stores the information of the Data to be sent from the queues.
  45  *        This structure will be pushed to the sender/receiver queue for processing.
  46  */
  47 typedef struct
  48 {
  49     CAEndpoint_t
  50     *remoteEndpoint;   /**< Remote endpoint contains the inforamtion of remote device */
  51     void *data;        /**< Data to be transmitted over LE tranport */
  52     uint32_t dataLen;  /**< Length of the data being transmitted */
  53 } CALEData_t;
  54
  55 /**
  56  * @brief  Initialize LE connectivity interface.
  57  * @param  registerCallback [IN] Callback to register LE interfaces to Connectivity
  58  *                               Abstraction Layer
  59  * @param  reqRespCallback  [IN] Callback to notify request and response messages from server(s)
  60  *                               started at Connectivity Abstraction Layer.
  61  * @param  netCallback      [IN] Callback to notify the network additions to Connectivity
  62  *                               Abstraction Layer.
  63  * @param  errorCallback    [IN] errorCallback to notify error to connectivity common logic
  64  *                               layer from adapter
  65  * @param  handle           [IN] Threadpool Handle
  66  * @return #CA_STATUS_OK or Appropriate error code
  67  */
  68 CAResult_t CAInitializeLE(CARegisterConnectivityCallback registerCallback,
  69                           CANetworkPacketReceivedCallback reqRespCallback,
  70                           CANetworkChangeCallback netCallback,
  71                           CAErrorHandleCallback errorCallback, ca_thread_pool_t handle);
  72
  73 /**
  74  * @brief Starting LE connectivity adapters.
  75  *        As its peer to peer it doesnot require to start any servers
  76  * @return  #CA_STATUS_OK or Appropriate error code
  77  */
  78 CAResult_t CAStartLE();
  79
  80 /**
  81  * @brief Starting listening server for receiving multicast search requests
  82  * Transport Specific Behavior:
  83  *   LE  Starts GATT Server with prefixed UUID and Characteristics as per OIC Specification.
  84  * @return  #CA_STATUS_OK or Appropriate error code
  85  */
  86 CAResult_t CAStartLEListeningServer();
  87
  88 /**
  89  * @brief for starting discovery servers for receiving multicast advertisements
  90  * Transport Specific Behavior:
  91  *   LE  Starts GATT Server with prefixed UUID and Characteristics as per OIC Specification.
  92  * @return  #CA_STATUS_OK or Appropriate error code
  93  */
  94 CAResult_t CAStartLEDiscoveryServer();
  95
  96 /**
  97  * @brief Sends data to the endpoint using the adapter connectivity.
  98  * @param   endpoint  [IN]  Remote Endpoint information (like ipaddress , port, reference uri \
  99  *                          and connectivity type) to which the unicast data has to be sent.
 100  * @param   data      [IN]  Data which required to be sent.
 101  * @param   dataLen   [IN]  Size of data to be sent.
 102  * @return  The number of bytes sent on the network. Returns -1 on error.
 103  * @remarks  dataLen must be > 0.
 104  */
 105 int32_t CASendLEUnicastData(const CAEndpoint_t *endpoint, const void *data,
 106                              uint32_t dataLen);
 107
 108 /**
 109  * @brief Sends Multicast data to the endpoint using the LE connectivity.
 110  * @param   endpoint    [IN]  Remote Endpoint information to which the unicast data has to be sent.
 111  * @param   data        [IN]  Data which required to be sent.
 112  * @param   dataLen     [IN]  Size of data to be sent.
 113  * @return  The number of bytes sent on the network. Returns -1 on error.
 114  * @remarks  dataLen must be > 0.
 115  */
 116 int32_t CASendLEMulticastData(const CAEndpoint_t *endpoint, const void *data, uint32_t dataLen);
 117
 118 /**
 119  * @brief Starts notification server on EDR adapters.
 120  * @return  #CA_STATUS_OK or Appropriate error code
 121  */
 122 CAResult_t CAStartLENotifyServer();
 123
 124 /**
 125  * @brief   Send notification information.
 126  * @param   endpoint  [IN]    Remote Endpoint information (like ipaddress , port, reference uri \
 127  *                            and connectivity type) to which the unicast data has to be sent.
 128  * @param   data      [IN]    Data which required to be sent.
 129  * @param   dataLen   [IN]    Size of data to be sent.
 130  * @return  The number of bytes sent on the network. Returns 0 on error.
 131  * @remarks dataLen must be > 0.
 132  */
 133 uint32_t CASendLENotification(const CAEndpoint_t *endpoint, const void *data,
 134                               uint32_t dataLen);
 135
 136 /**
 137  * @brief  Get LE Connectivity network information
 138  * @param  info        [OUT]   Local connectivity information structures
 139  * @param  size        [OUT]   Number of local connectivity structures.
 140  * @return #CA_STATUS_OK or Appropriate error code
 141  */
 142 CAResult_t CAGetLEInterfaceInformation(CAEndpoint_t **info, uint32_t *size);
 143
 144 /**
 145  * @brief Read Synchronous API callback.
 146  * @return  #CA_STATUS_OK or Appropriate error code
 147  */
 148 CAResult_t CAReadLEData();
 149
 150 /**
 151  * @brief Stopping the adapters and close socket connections
 152  *   LE Stops all GATT servers and GATT Clients.
 153  * @return  #CA_STATUS_OK or Appropriate error code
 154  */
 155 CAResult_t CAStopLE();
 156
 157 /**
 158  * @brief Terminate the LE connectivity adapter.
 159  * Configuration information will be deleted from further use
 160  */
 161 void CATerminateLE();
 162
 163 /**
 164  * @brief  This function will receive the data from the GattServer and add the data to
 165  *         the Server receiver queue.
 166  * @param  remoteAddress [IN] Remote address of the device from where data is received.
 167  * @param  serviceUUID   [IN] Uuid of the OIC service running on the remote device
 168  * @param  data          [IN] Actual data recevied from the remote device.
 169  * @param  dataLength    [IN] Length of the data received from the remote device.
 170  * @param  sentLength    [IN] Length of the data sent from the remote device.
 171  * @return #CA_STATUS_OK or Appropriate error code
 172  * @retval #CA_STATUS_OK  Successful
 173  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 174  * @retval #CA_STATUS_FAILED Operation failed
 175  *
 176  */
 177 CAResult_t CALEAdapterServerReceivedData(const char *remoteAddress, const char *serviceUUID,
 178                                          const void *data, uint32_t dataLength,
 179                                          uint32_t *sentLength);
 180
 181 /**
 182  * @brief  This function will receive the data from the GattClient and add the data into the
 183  *         Client receiver queue.
 184  * @param  remoteAddress [IN] Remote address of the device from where data is received.
 185  * @param  serviceUUID   [IN] Uuid of the OIC service running on the remote device
 186  * @param  data          [IN] Actual data recevied from the remote device.
 187  * @param  dataLength    [IN] Length of the data received from the remote device.
 188  * @param  sentLength    [IN] Length of the data sent from the remote device.
 189  * @return #CA_STATUS_OK or Appropriate error code
 190  * @retval #CA_STATUS_OK  Successful
 191  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 192  * @retval #CA_STATUS_FAILED Operation failed
 193  */
 194 CAResult_t CALEAdapterClientReceivedData(const char *remoteAddress, const char *serviceUUID,
 195                                          const void *data, uint32_t dataLength,
 196                                          uint32_t *sentLength);
 197
 198 /**
 199  * @brief  This function is used to set the NetworkPacket received callback to CA layer from
 200  *         adapter layer.
 201  * @param  callback [IN] callback handle sent from the upper layer.
 202  * @return NONE
 203  */
 204 void CASetLEReqRespAdapterCallback(CANetworkPacketReceivedCallback callback);
 205
 206 /**
 207  * @brief  This function will push the data from CA layer to the Sender processor queue.
 208  *
 209  * @param  remoteEndpoint [IN] Remote endpoint information of the server.
 210  * @param  data           [IN] Data to be transmitted from LE.
 211  * @param  dataLen        [IN] length of the Data being transmitted.
 212  *
 213  * @return #CA_STATUS_OK or Appropriate error code
 214  * @retval #CA_STATUS_OK  Successful
 215  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 216  * @retval #CA_STATUS_FAILED Operation failed
 217  */
 218 CAResult_t CALEAdapterServerSendData(const CAEndpoint_t *remoteEndpoint,
 219                                      const void *data, uint32_t dataLen);
 220
 221 /**
 222  * @brief  This function will push the data from CA layer to the Sender processor queue.
 223  *
 224  * @param  remoteEndpoint [IN] Remote endpoint information of the server.
 225  * @param  data           [IN] Data to be transmitted from LE.
 226  * @param  dataLen        [IN] length of the Data being transmitted.
 227  *
 228  * @return #CA_STATUS_OK or Appropriate error code
 229  * @retval #CA_STATUS_OK  Successful
 230  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 231  * @retval #CA_STATUS_FAILED Operation failed
 232  */
 233 CAResult_t CALEAdapterClientSendData(const CAEndpoint_t *remoteEndpoint,
 234                                      const void *data,  uint32_t dataLen);
 235
 236 /**
 237  * @brief  This function will be associated with the sender queue for GattServer.This function will
 238  *         fragment the data to the MTU of the transport and send the data in fragments to the
 239  *         adapters. The function will be blocked untill all data is sent out from the adapter.
 240  *
 241  * @param threadData [IN] Data pushed to the queue which contains the info about RemoteEndpoint
 242  *                        and Data.
 243  *
 244  * @return  NONE
 245  */
 246 void CALEServerSendDataThread(void *threadData);
 247
 248 /**
 249  * @brief  This function will be associated with the sender queue for GattClient.This function will
 250  *         fragment the data to the MTU of the transport and send the data in fragments to the
 251  *         adapters. The function will be blocked untill all data is sent out from the adapter.
 252  *
 253  * @param  threadData [IN] Data pushed to the queue which contains the info about RemoteEndpoint
 254  *                         and Data.
 255  *
 256  * @return NONE
 257  */
 258 void CALEClientSendDataThread(void *threadData);
 259
 260 /**
 261  * @brief  This function will be associated with the receiver queue of GattServer. This function
 262  *         will defragment the data received and will send the data UP to the CA layer only after
 263  *         it collects all the data from the adapter layer. Adapter Header will provide the
 264  *         length of the data sent from the server.
 265  *
 266  * @param  threadData [IN] Data pushed to the queue which contains the info about RemoteEndpoint
 267  *                         and Data.
 268  *
 269  * @return  NONE
 270  */
 271 void CALEServerDataReceiverHandler(void *threadData);
 272
 273 /**
 274  * @brief  This function will be associated with the receiver queue of GattClient. This function
 275  *         will defragment the data received and will send the data UP to the CA layer only after
 276  *         it collects all the data from the adapter layer. Adapter Header will provide the length
 277  *         of the data sent from the server.
 278  *
 279  * @param  threadData [IN] Data pushed to the queue which contains the info about RemoteEndpoint
 280  *                         and Data.
 281  * @return NONE
 282  */
 283 void CALEClientDataReceiverHandler(void *threadData);
 284
 285 /**
 286  * @brief  This function is used to Initalize both GattServer and GattClient queues. All four
 287  *         queues will be initialized with this function invocations.
 288  * @return  NONE
 289  */
 290 void CAInitLEQueues();
 291
 292 /**
 293  * @brief  This function will stop all queues created for GattServer and GattClient. All
 294  *         four queues will be be stopped with this function invocations.
 295  * @return  NONE
 296  */
 297 void CAStopLEQueues();
 298
 299 /**
 300  * @brief  This function will terminate all queues created for GattServer and GattClient. All
 301  *         four queues will be be terminated with this function invocations.
 302  * @return  NONE
 303  */
 304 void CATerminateLEQueues();
 305
 306 /**
 307  * @brief  This function will initalize the Receiver and Sender queues for GattServer. This
 308  *         function will inturn call the functions CAInitBleServerReceiverQueue() and
 309  *         CAInitBleServerSenderQueue() to initialize the queues.
 310  * @return #CA_STATUS_OK or Appropriate error code
 311  * @retval #CA_STATUS_OK  Successful
 312  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 313  * @retval #CA_STATUS_FAILED Operation failed
 314  */
 315 CAResult_t CAInitLEServerQueues();
 316
 317 /**
 318  * @brief  This function will initalize the Receiver and Sender queues for GattClient. This
 319  *         function will inturn call the functions CAInitBleClientReceiverQueue() and
 320  *         CAInitBleClientSenderQueue() to initialize the queues.
 321  *
 322  * @return #CA_STATUS_OK or Appropriate error code
 323  * @retval #CA_STATUS_OK  Successful
 324  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 325  * @retval #CA_STATUS_FAILED Operation failed
 326  *
 327  */
 328 CAResult_t CAInitLEClientQueues();
 329
 330 /**
 331  * @brief  This function will initalize the Receiver queue for GattServer. This will initialize
 332  *         the queue to process the function CABLEServerSendDataThread() when ever the task is
 333  *         added to this queue.
 334  *
 335  * @return #CA_STATUS_OK or Appropriate error code
 336  * @retval #CA_STATUS_OK  Successful
 337  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 338  * @retval #CA_STATUS_FAILED Operation failed
 339  */
 340 CAResult_t CAInitLEServerSenderQueue();
 341
 342 /**
 343  * @brief  This function will initalize the Receiver queue for GattClient. This will initialize
 344  *         the queue to process the function CABLEClientSendDataThread() when ever the task is
 345  *         added to this queue.
 346  *
 347  * @return #CA_STATUS_OK or Appropriate error code
 348  * @retval #CA_STATUS_OK  Successful
 349  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 350  * @retval #CA_STATUS_FAILED Operation failed
 351  */
 352 CAResult_t CAInitLEClientSenderQueue();
 353
 354 /**
 355  * @brief  This function will initalize the Receiver queue for GattServer. This will initialize
 356  *         the queue to process the function CABLEServerDataReceiverHandler() when ever the task
 357  *         is added to this queue.
 358  *
 359  * @return #CA_STATUS_OK or Appropriate error code
 360  * @retval #CA_STATUS_OK  Successful
 361  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 362  * @retval #CA_STATUS_FAILED Operation failed
 363  *
 364  */
 365 CAResult_t CAInitLEServerReceiverQueue();
 366
 367 /**
 368  * @brief  This function will initalize the Receiver queue for GattClient. This will initialize
 369  *         the queue to process the function CABLEClientDataReceiverHandler() when ever the task
 370  *         is added to this queue.
 371  *
 372  * @return #CA_STATUS_OK or Appropriate error code
 373  * @retval #CA_STATUS_OK  Successful
 374  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 375  * @retval #CA_STATUS_FAILED Operation failed
 376  */
 377 CAResult_t CAInitLEClientReceiverQueue();
 378
 379 /**
 380  * @brief  This function will create the Data required to send it in the queue.
 381  *
 382  * @param  remoteEndpoint [IN] Remote endpoint information of the server.
 383  * @param  data           [IN] Data to be transmitted from LE.
 384  * @param  dataLength     [IN] length of the Data being transmitted.
 385  *
 386  * @return #CA_STATUS_OK or Appropriate error code
 387  * @retval #CA_STATUS_OK  Successful
 388  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 389  * @retval #CA_STATUS_FAILED Operation failed
 390  */
 391 CALEData_t *CACreateLEData(const CAEndpoint_t *remoteEndpoint, const void *data,
 392                            uint32_t dataLength);
 393
 394 /**
 395  * @brief Used to free the BLE information stored in the sender/receiver queues.
 396  * @param bleData [IN] Structure contains the information of a particular data segment.
 397  * @return NONE
 398  */
 399 void CAFreeLEData(CALEData_t *bleData);
 400
 401 /**
 402  * @brief This will be used to notify device status changes to the LE adapter layer
 403  * @param  adapter_state [IN] State of the adapter
 404  * @return NONE
 405  */
 406 typedef void (*CALEDeviceStateChangedCallback)(CAAdapterState_t adapter_state);
 407
 408 /**
 409  * @brief This will be used to notify that network packet recieved from GATTClient to adapter layer.
 410  * @param  remoteAddress  [IN] Remote endpoint Address
 411  * @param  serviceUUID    [IN] Service UUID
 412  * @param  data           [IN] Data received
 413  * @param  dataLength     [IN] Length of the data received
 414  * @param  sentLength     [IN] Length of the data sent
 415  * @return #CA_STATUS_OK or Appropriate error code
 416  * @retval #CA_STATUS_OK  Successful
 417  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 418  * @retval #CA_STATUS_FAILED Operation failed
 419  */
 420 typedef CAResult_t (*CABLEClientDataReceivedCallback)(const char *remoteAddress,
 421                                                       const char *serviceUUID, const void *data,
 422                                                       uint32_t dataLength, uint32_t *sentLength);
 423
 424 /**
 425  * @brief This will be used to notify that network packet recieved from GATTServer to adapter layer.
 426  * @param  remoteAddress  [IN] Remote endpoint Address
 427  * @param  serviceUUID    [IN] Service UUID
 428  * @param  data           [IN] Data received
 429  * @param  dataLength     [IN] Length of the data received
 430  * @param  sentLength     [IN] Length of the data sent
 431  * @return #CA_STATUS_OK or Appropriate error code
 432  * @retval #CA_STATUS_OK  Successful
 433  * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 434  * @retval #CA_STATUS_FAILED Operation failed
 435  */
 436 typedef CAResult_t (*CABLEServerDataReceivedCallback)(const char *remoteAddress,
 437                                                       const char *serviceUUID, const void *data,
 438                                                       uint32_t dataLength, uint32_t *sentLength);
 439
 440 #ifdef __cplusplus
 441 } /* extern "C" */
 442 #endif
 443
 444 #endif /* CA_LEADAPTER_H_ */
 445