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