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