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