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