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