caleadapter_singlethread.h 16.8 KB
Newer Older
1
/* ****************************************************************
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
 *
 * Copyright 2014 Samsung Electronics All Rights Reserved.
 *
 *
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 ******************************************************************/

/**
22 23 24
 * @file
 *
 * This file contains the APIs for LE adapters to be implemented.
25
 */
26

27 28
#ifndef CA_LEADAPTER_SINGLETHREAD_H_
#define CA_LEADAPTER_SINGLETHREAD_H_
29 30 31 32 33 34 35 36 37 38 39 40 41

#include "cacommon.h"
#include "caadapterinterface.h"

/**
 * BLE Interface APIs.
 */
#ifdef __cplusplus
extern "C"
{
#endif

/**
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 47 48 49
 */
typedef struct
{
    CARemoteEndpoint_t
    *remoteEndpoint;    /**< Remote endpoint contains the inforamtion of remote device */
50 51
    void *data;         /**< Data to be transmitted over LE tranport */
    uint32_t dataLen;   /**< Length of the data being transmitted */
52
} CALEData_t;
53

54 55 56 57 58
/**
 * @brief Initialize LE connectivity interface.
 * @param registerCallback [IN] Callback to register LE interfaces to Connectivity Abstraction Layer
 * @param reqRespCallback  [IN] Callback to notify request and response messages from server(s)
 *                              started at Connectivity Abstraction Layer.
59
 * @param netCallback      [IN] Callback to notify the network additions to Connectivity
60 61
 *                              Abstraction Layer.
 * @return  #CA_STATUS_OK or Appropriate error code
62 63 64 65 66 67
 */
CAResult_t CAInitializeLE(CARegisterConnectivityCallback registerCallback,
                          CANetworkPacketReceivedCallback reqRespCallback,
                          CANetworkChangeCallback netCallback);

/**
68 69 70
 * @brief Starting LE connectivity adapters.
 *        As its peer to peer it doesnot require to start any servers
 * @return  #CA_STATUS_OK or Appropriate error code
71 72 73 74 75 76 77
 */
CAResult_t CAStartLE();

/**
 * @brief Starting listening server for receiving multicast search requests
 * Transport Specific Behavior:
 *   LE  Starts GATT Server with prefixed UUID and Characteristics as per OIC Specification.
78
 * @return  #CA_STATUS_OK or Appropriate error code
79 80 81 82 83 84 85
 */
CAResult_t CAStartLEListeningServer();

/**
 * @brief for starting discovery servers for receiving multicast advertisements
 * Transport Specific Behavior:
 *   LE  Starts GATT Server with prefixed UUID and Characteristics as per OIC Specification.
86
 * @return  #CA_STATUS_OK or Appropriate error code
87 88 89 90 91
 */
CAResult_t CAStartLEDiscoveryServer();

/**
 * @brief Sends data to the endpoint using the adapter connectivity.
92 93 94 95
 * @param  endpoint  [IN]  Remote Endpoint information (like ipaddress , port, reference uri
 *                         and connectivity type) to which the unicast data has to be sent.
 * @param  data      [IN]  Data which required to be sent.
 * @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 101 102 103 104 105
                             uint32_t dataLen);

/**
 * @brief Sends Multicast data to the endpoint using the LE connectivity.
 * @param   data        [IN]    Data which required to be sent.
 * @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 116 117 118
 */
CAResult_t CAStartLENotifyServer();

/**
 * @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 124
 * @return  The number of bytes sent on the network. Returns 0 on error.
 * @remarks dataLen must be > 0.
125
 */
126
uint32_t CASendLENotification(const CARemoteEndpoint_t *endpoint, const void *data,
127 128 129
                              uint32_t dataLen);

/**
130
 * @brief   Get LE Connectivity network information
131 132
 * @param   info        [OUT]   Local connectivity information structures
 * @param   size        [OUT]   Number of local connectivity structures.
133
 * @return  #CA_STATUS_OK or Appropriate error code
134 135 136 137 138
 */
CAResult_t CAGetLEInterfaceInformation(CALocalConnectivity_t **info, uint32_t *size);

/**
 * @brief Read Synchronous API callback.
139
 * @return  #CA_STATUS_OK or Appropriate error code
140 141 142 143 144 145
 */
CAResult_t CAReadLEData();

/**
 * @brief Stopping the adapters and close socket connections
 *   LE Stops all GATT servers and close sockets.
146
 * @return  #CA_STATUS_OK or Appropriate error code
147 148 149 150 151 152 153 154 155
 */
CAResult_t CAStopLE();

/**
 * @brief Terminate the LE connectivity adapter.
 * Configuration information will be deleted from further use
 */
void CATerminateLE();

156 157 158 159 160 161 162 163 164 165 166 167 168
/**
 * @brief  This function will receive the data from the GattServer and add the data to
 *         the Server receiver queue.
 * @param  remoteAddress [IN] Remote address of the device from where data is received.
 * @param  serviceUUID   [IN] Uuid of the OIC service running on the remote device
 * @param  data          [IN] Actual data recevied from the remote device.
 * @param  dataLength    [IN] Length of the data received from the remote device.
 * @param  sentLength    [IN] Length of the data sent from the remote device.
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
169
CAResult_t CABLEServerReceivedData(const char *remoteAddress, const char *serviceUUID,
170
                                   const void *data, uint32_t dataLength, uint32_t *sentLength);
171

172 173 174 175 176 177 178 179 180 181 182 183 184
/**
 * @brief  This function will receive the data from the GattClient and add the data into the
 *         Client receiver queue.
 * @param  remoteAddress [IN] Remote address of the device from where data is received.
 * @param  serviceUUID   [IN] Uuid of the OIC service running on the remote device
 * @param  data          [IN] Actual data recevied from the remote device.
 * @param  dataLength    [IN] Length of the data received from the remote device.
 * @param  sentLength    [IN] Length of the data sent from the remote device.
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
185
CAResult_t CABLEClientReceivedData(const char *remoteAddress, const char *serviceUUID,
186
                                   const void *data, uint32_t dataLength, uint32_t *sentLength);
187

188 189 190 191 192 193
/**
 * @brief  This function is used to set the NetworkPacket received callback to CA layer from
 *         adapter layer.
 * @param  callback [IN] callback handle sent from the upper layer.
 * @return NONE
 */
194 195
void CASetBLEReqRespAdapterCallback(CANetworkPacketReceivedCallback callback);

196 197 198 199 200 201 202 203 204 205 206 207
/**
 * @brief  This function will push the data from CA layer to the Sender processor queue.
 *
 * @param  remoteEndpoint [IN] Remote endpoint information of the server.
 * @param  data           [IN] Data to be transmitted from LE.
 * @param  dataLen        [IN] length of the Data being transmitted.
 *
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
208
CAResult_t CABLEServerSendData(const CARemoteEndpoint_t *remoteEndpoint,
209
                               const void *data, uint32_t dataLen);
210

211 212 213 214 215 216 217 218 219 220 221 222
/**
 * @brief  This function will push the data from CA layer to the Sender processor queue.
 *
 * @param  remoteEndpoint [IN] Remote endpoint information of the server.
 * @param  data           [IN] Data to be transmitted from LE.
 * @param  dataLen        [IN] length of the Data being transmitted.
 *
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
223
CAResult_t CABLEClientSendData(const CARemoteEndpoint_t *remoteEndpoint,
224
                               const void *data, uint32_t dataLen);
225

226 227 228 229 230 231 232 233 234 235
/**
 * @brief  This function will be associated with the sender queue for GattClient.This function will
 *         fragment the data to the MTU of the transport and send the data in fragments to the
 *         adapters. The function will be blocked untill all data is sent out from the adapter.
 *
 * @param  threadData [IN] Data pushed to the queue which contains the info about RemoteEndpoint
 *                         and Data.
 *
 * @return NONE
 */
236 237
void CABLEClientSendDataThread(void *threadData);

238 239 240 241 242 243 244 245 246 247
/**
 * @brief  This function will be associated with the receiver queue of GattClient. This function
 *         will defragment the data received and will send the data UP to the CA layer only after
 *         it collects all the data from the adapter layer. Adapter Header will provide the length
 *         of the data sent from the server.
 *
 * @param  threadData [IN] Data pushed to the queue which contains the info about RemoteEndpoint
 *                         and Data.
 * @return NONE
 */
248 249
void CABLEClientDataReceiverHandler(void *threadData);

250 251 252 253 254
/**
 * @brief  This function will terminate all queues created for GattServer and GattClient. All
 *         four queues will be be terminated with this function invocations.
 * @return  NONE
 */
255 256
void CATerminateBleQueues();

257
/**
258
 * @brief  This function will initalize the Receiver queue for GattClient. This will initialize
259 260 261 262 263 264 265 266
 *         the queue to process the function CABLEClientDataReceiverHandler() when ever the task
 *         is added to this queue.
 *
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
267 268
CAResult_t CAInitBleClientReceiverQueue();

269
/**
270
 * @brief  This function will initalize the Receiver queue for GattServer. This will initialize
271 272 273 274 275 276 277 278 279
 *         the queue to process the function CABLEServerDataReceiverHandler() when ever the task
 *         is added to this queue.
 *
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 *
 */
280 281
CAResult_t CAInitBleServerReceiverQueue();

282 283 284 285 286
/**
 * @brief  This function is used to Initalize both GattServer and GattClient queues. All four
 *         queues will be initialized with this function invocations.
 * @return  NONE
 */
287 288
void CAInitBleQueues();

289 290 291 292 293 294 295 296 297
/**
 * @brief  This function will initalize the Receiver and Sender queues for GattServer. This
 *         function will inturn call the functions CAInitBleServerReceiverQueue() and
 *         CAInitBleServerSenderQueue() to initialize the queues.
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
298 299
CAResult_t CAInitBleServerQueues();

300 301 302 303 304 305 306 307 308 309 310
/**
 * @brief  This function will initalize the Receiver and Sender queues for GattClient. This
 *         function will inturn call the functions CAInitBleClientReceiverQueue() and
 *         CAInitBleClientSenderQueue() to initialize the queues.
 *
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 *
 */
311 312
CAResult_t CAInitBleClientQueues();

313
/**
314
 * @brief  This function will initalize the Receiver queue for GattServer. This will initialize
315 316 317 318 319 320 321 322
 *         the queue to process the function CABLEServerSendDataThread() when ever the task is
 *         added to this queue.
 *
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
323 324
CAResult_t CAInitBleServerSenderQueue();

325
/**
326
 * @brief  This function will initalize the Receiver queue for GattClient. This will initialize
327 328 329 330 331 332 333 334
 *         the queue to process the function CABLEClientSendDataThread() when ever the task is
 *         added to this queue.
 *
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
335 336 337
CAResult_t CAInitBleClientSenderQueue();

/**
338 339 340 341 342 343 344 345 346
 * @brief  This function will be associated with the receiver queue of GattServer. This function
 *         will defragment the data received and will send the data UP to the CA layer only after
 *         it collects all the data from the adapter layer. Adapter Header will provide the
 *         length of the data sent from the server.
 *
 * @param  context [IN] Data pushed to the queue which contains the info about RemoteEndpoint
 *                      and Data.
 *
 * @return  NONE
347 348 349 350
 */
void CABLEServerDataReceiverHandler(void *context);

/**
351 352 353 354 355 356 357 358
 * @brief  This function will be associated with the sender queue for GattServer.This function will
 *         fragment the data to the MTU of the transport and send the data in fragments to the
 *         adapters. The function will be blocked untill all data is sent out from the adapter.
 *
 * @param threadData [IN] Data pushed to the queue which contains the info about RemoteEndpoint
 *                        and Data.
 *
 * @return  NONE
359 360 361 362
 */
void CABLEServerSendDataThread(void *threadData);

/**
363 364 365 366 367 368 369 370 371 372 373
 * @brief  This function will create the Data required to send it in the queue.
 *
 * @param  remoteEndpoint [IN] Remote endpoint information of the server.
 * @param  data           [IN] Data to be transmitted from LE.
 * @param  dataLength     [IN] length of the Data being transmitted.
 *
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
374
CALEData_t *CACreateBLEData(const CARemoteEndpoint_t *remoteEndpoint, const void *data,
375
                            uint32_t dataLength);
376 377

/**
378 379 380 381
 * @brief Used to free the BLE information stored in the sender/receiver queues.
 * @param bleData [IN] Structure contains the information of a particular data segment.
 * @return NONE
 */
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 387 388 389 390 391
 * @param  adapter_state [IN] State of the adapter
 * @return NONE
 */
typedef void (*CALEDeviceStateChangedCallback)(CAAdapterState_t adapter_state);

/**
392
 * @brief This will be used to notify that network packet recieved from GATTClient to adapter layer.
393 394 395 396 397 398 399 400 401 402 403
 * @param  remoteAddress  [IN] Remote endpoint Address
 * @param  serviceUUID    [IN] Service UUID
 * @param  data           [IN] Data received
 * @param  dataLength     [IN] Length of the data received
 * @param  sentLength     [IN] Length of the data sent
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
typedef CAResult_t (*CABLEClientDataReceivedCallback)(const char *remoteAddress,
404 405
                    const char *serviceUUID, const void *data, uint32_t dataLength,
                    uint32_t *sentLength);
406 407

/**
408
 * @brief This will be used to notify that network packet recieved from GATTServer to adapter layer.
409 410 411 412 413 414 415 416 417 418 419
 * @param  remoteAddress  [IN] Remote endpoint Address
 * @param  serviceUUID    [IN] Service UUID
 * @param  data           [IN] Data received
 * @param  dataLength     [IN] Length of the data received
 * @param  sentLength     [IN] Length of the data sent
 * @return #CA_STATUS_OK or Appropriate error code
 * @retval #CA_STATUS_OK  Successful
 * @retval #CA_STATUS_INVALID_PARAM  Invalid input argumets
 * @retval #CA_STATUS_FAILED Operation failed
 */
typedef CAResult_t (*CABLEServerDataReceivedCallback)(const char *remoteAddress,
420
        const char *serviceUUID, const void *data, uint32_t dataLength, uint32_t *sentLength);
421

422 423 424 425
#ifdef __cplusplus
} /* extern "C" */
#endif

426
#endif /* CA_LEADAPTER_SINGLETHREAD_H_ */
427