resource/csdk/connectivity/inc/cablockwisetransfer.h

   1 /* *****************************************************************
   2  *
   3  * Copyright 2015 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  * This file contains common function for block messages.
  24  */
  25
  26 #ifndef CA_BLOCKWISETRANSFER_H_
  27 #define CA_BLOCKWISETRANSFER_H_
  28
  29 #include <stdint.h>
  30
  31 #include "coap.h"
  32 #include "cathreadpool.h"
  33 #include "camutex.h"
  34 #include "uarraylist.h"
  35 #include "cacommon.h"
  36 #include "caprotocolmessage.h"
  37
  38 /**
  39  * Callback to send block data
  40  * @param[in]   data    send data
  41  */
  42 typedef void (*CASendThreadFunc)(CAData_t *data);
  43
  44 /**
  45  * Callback to notify received data from the remote endpoint
  46  * @param[in]   data    received data
  47  */
  48 typedef void (*CAReceiveThreadFunc)(CAData_t *data);
  49
  50 typedef struct
  51 {
  52     /** send method for block data **/
  53     CASendThreadFunc sendThreadFunc;
  54
  55     /** callback function for received message **/
  56     CAReceiveThreadFunc receivedThreadFunc;
  57
  58     /** array list on which the thread is operating. **/
  59     u_arraylist_t *dataList;
  60
  61     /** data list mutex for synchronization **/
  62     ca_mutex blockDataListMutex;
  63
  64     /** sender mutex for synchronization **/
  65     ca_mutex blockDataSenderMutex;
  66 } CABlockWiseContext_t;
  67
  68 typedef struct
  69 {
  70     coap_block_t block;                 /**< block option */
  71     uint16_t type;                      /**< block option type */
  72     CAToken_t token;                    /**< token for CA */
  73     uint8_t tokenLength;                /**< token length*/
  74     CAData_t *sentData;                 /**< sent request or response data information */
  75     CAPayload_t payload;                /**< payload buffer  */
  76     size_t payloadLength;               /**< the total payload length to be received  */
  77     size_t receivedPayloadLen;          /**< currently received payload length  */
  78 } CABlockData_t;
  79
  80 /**
  81  * CABlockState_t
  82  * state of received block message from remote endpoint
  83  */
  84 typedef enum
  85 {
  86     CA_BLOCK_UNKNOWN = 0,
  87     CA_OPTION1_ACK,
  88     CA_OPTION1_NO_ACK_LAST_BLOCK,
  89     CA_OPTION1_NO_ACK_BLOCK,
  90     CA_OPTION2_FIRST_BLOCK,
  91     CA_OPTION2_LAST_BLOCK,
  92     CA_OPTION2_ACK,
  93     CA_OPTION2_NON,
  94     CA_OPTION2_CON,
  95     CA_SENT_PREVIOUS_NON_MSG,
  96     CA_BLOCK_INCOMPLETE,
  97     CA_BLOCK_TOO_LARGE,
  98     CA_BLOCK_RECEIVED_ALREADY
  99 } CABlockState_t;
 100
 101 #ifdef __cplusplus
 102 extern "C"
 103 {
 104 #endif
 105
 106 /**
 107  * Initializes the block-wise transfer context
 108  * @param[in]  CASendThreadFunc    function point to add data in send queue thread
 109  * @param[in]  CAReceiveThreadFunc function point to add data in receive queue thread
 110  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 111  */
 112 CAResult_t CAInitializeBlockWiseTransfer(CASendThreadFunc blockSendMethod,
 113                                          CAReceiveThreadFunc receivedDataCallback);
 114
 115 /**
 116  * Terminate the block-wise transfer context
 117  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 118  */
 119 CAResult_t CATerminateBlockWiseTransfer();
 120
 121 /**
 122  * initialize mutex
 123  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 124  */
 125 CAResult_t CAInitBlockWiseMutexVariables();
 126
 127 /**
 128  * terminate mutex
 129  */
 130 void CATerminateBlockWiseMutexVariables();
 131
 132 /**
 133  * Pass the bulk data. if block-wise transfer process need,
 134  *          bulk data will be sent to block messages.
 135  * @param[in]   data    data for sending
 136  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 137  */
 138 CAResult_t CASendBlockWiseData(const CAData_t *data);
 139
 140 /**
 141  * Add the data to send thread queue
 142  * @param[in]   sendData    data for sending
 143  * @param[in]   token   token of current message
 144  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 145  */
 146 CAResult_t CAAddSendThreadQueue(const CAData_t *sendData, const unsigned char* token);
 147
 148 /**
 149  * Check the block option type. If it has to be sent to a block,
 150  *          block option will be set.
 151  * @param[in]   currData    block data
 152  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 153  */
 154 CAResult_t CACheckBlockOptionType(CABlockData_t *currData);
 155
 156 /**
 157  * Pass the received pdu data. and check if block option is set.
 158  * @param[in]   pdu received pdu binary data
 159  * @param[in]   endpoint    information of remote device
 160  * @param[in]   receivedData    received CAData
 161  * @param[in]   dataLen    received data length
 162  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 163  */
 164 CAResult_t CAReceiveBlockWiseData(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
 165                                   const CAData_t *receivedData, size_t dataLen);
 166
 167 /**
 168  * process next step by block-wise state
 169  * @param[in]   pdu received pdu binary data
 170  * @param[in]   receivedData    received CAData
 171  * @param[in]   blockWiseStatus    block-wise state to move next step
 172  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 173  */
 174 CAResult_t CAProcessNextStep(const coap_pdu_t *pdu, const CAData_t *receivedData,
 175                              uint8_t blockWiseStatus);
 176
 177 /**
 178  * send block message to remote device
 179  * @param[in]   pdu received pdu binary data
 180  * @param[in]   msgType the message type of the block
 181  * @param[in]   status  block-wise state to move next step
 182  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 183  */
 184 CAResult_t CASendBlockMessage(const coap_pdu_t *pdu, CAMessageType_t msgType, uint8_t status);
 185
 186 /**
 187  * send error message to remote device
 188  * @param[in]   pdu received pdu binary data
 189  * @param[in]   status  block-wise state to move next step
 190  * @param[in]   responseResult  response result code
 191  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 192  */
 193 CAResult_t CASendErrorMessage(const coap_pdu_t *pdu, uint8_t status,
 194                               CAResponseResult_t responseResult);
 195
 196 /**
 197  * receive last block data
 198  * @param[in]   pdu received pdu binary data
 199  * @param[in]   receivedData    received CAData
 200  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 201  */
 202 CAResult_t CAReceiveLastBlock(const coap_pdu_t *pdu, const CAData_t *receivedData);
 203
 204 /**
 205  * set next block option 1
 206  * @param[in]   pdu received pdu binary data
 207  * @param[in]   endpoint  information of remote device
 208  * @param[in]   receivedData    received CAData
 209  * @param[in]   block   block option data
 210  * @param[in]   dataLen received data length
 211  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 212  */
 213 CAResult_t CASetNextBlockOption1(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
 214                                  const CAData_t *receivedData, coap_block_t block,
 215                                  size_t dataLen);
 216
 217 /**
 218  * set next block option 2
 219  * @param[in]   pdu received pdu binary data
 220  * @param[in]   endpoint    information of remote device
 221  * @param[in]   receivedData    received CAData
 222  * @param[in]   block   block option data
 223  * @param[in]   dataLen received data length
 224  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 225  */
 226 CAResult_t CASetNextBlockOption2(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
 227                                  const CAData_t *receivedData, coap_block_t block,
 228                                  size_t dataLen);
 229
 230 /**
 231  * Update the block option in block-wise transfer list
 232  * @param[in]   currData   stored block data information
 233  * @param[in]   block   block option to update
 234  * @param[in]   msgType message type of pdu
 235  * @param[in]   blockType   block option type
 236  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 237  */
 238 CAResult_t CANegotiateBlockSize(CABlockData_t *currData, coap_block_t *block,
 239                                 CAMessageType_t msgType, uint16_t blockType);
 240
 241 /**
 242  * Update the block option in block-wise transfer list
 243  * @param[in]   currData    stored block data information
 244  * @param[in]   block   block option of current message
 245  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 246  */
 247 CAResult_t CAUpdateBlockData(CABlockData_t *currData, coap_block_t block);
 248
 249 /**
 250  * Update the messageId in block-wise transfer list
 251  * @param[in]   currData    stored block data information
 252  * @param[in]   block block option of current message
 253  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 254  */
 255 CAResult_t CAUpdateMessageId(coap_pdu_t *pdu);
 256
 257 /**
 258  * Update the block option items
 259  * @param[in]   currData    stored block data information
 260  * @param[in]   pdu received pdu binary data
 261  * @param[in/out]   block   block option of current message
 262  * @param[in]   blockType  block option type
 263  * @param[in]   status  current flow status for block-wise transfer
 264  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 265  */
 266 CAResult_t CAUpdateBlockOptionItems(CABlockData_t *currData, const coap_pdu_t *pdu,
 267                                     coap_block_t *block, uint16_t blockType,
 268                                     uint32_t status);
 269 /**
 270  * Set the M-bit of block option
 271  * @param[in]   payloadLen  payload length of current bulk data
 272  * @param[out]  block   block option
 273  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 274  */
 275 CAResult_t CAGetMoreBitFromBlock(size_t payloadLen, coap_block_t *block);
 276
 277 /**
 278  * check the block option what kind of option have to set.
 279  * @param[out]  pdu pdu object
 280  * @param[in]   info    information of the request/response
 281  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 282  */
 283 CAResult_t CAAddBlockOption(coap_pdu_t **pdu, CAInfo_t info);
 284
 285 /**
 286  * Write the block option2 in pdu binary data.
 287  * @param[out]  pdu pdu object
 288  * @param[in]   info    information of the request/response
 289  * @param[in]   dataLength  length of payload
 290  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 291  */
 292 CAResult_t CAAddBlockOption2(coap_pdu_t **pdu, CAInfo_t info, size_t dataLength);
 293
 294 /**
 295  * Write the block option1 in pdu binary data.
 296  * @param[out]  pdu pdu object
 297  * @param[in]   info    information of the request/response
 298  * @param[in]   dataLength length of payload
 299  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 300  */
 301 CAResult_t CAAddBlockOption1(coap_pdu_t **pdu, CAInfo_t info, size_t dataLength);
 302
 303 /**
 304  * Add the block option in pdu data
 305  * @param[in]   pdu pdu object
 306  * @param[out]  block block data
 307  * @param[in]   blockType   block option type
 308  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 309  */
 310 CAResult_t CAAddBlockOptionImpl(coap_pdu_t *pdu, coap_block_t *block, uint8_t blockType);
 311
 312 /**
 313  * Add the size option in pdu data
 314  * @param[in/out]   pdu pdu object
 315  * @param[in]   sizeType    size option type
 316  * @param[in]   dataLength the total payload length to be sent
 317  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 318  */
 319 CAResult_t CAAddBlockSizeOption(coap_pdu_t *pdu, uint16_t sizeType, size_t dataLength);
 320
 321 /**
 322  * Get the size option from pdu data
 323  * @param[in]   pdu pdu object
 324  * @param[in]   sizeType    size option type
 325  * @param[out]  totalPayloadLen the total payload length to be received
 326  * @return true or false
 327  */
 328 bool CAIsPayloadLengthInPduWithBlockSizeOption(const coap_pdu_t *pdu,
 329                                                uint16_t sizeType,
 330                                                size_t *totalPayloadLen);
 331
 332 /**
 333  * update the total payload with the received payload
 334  * @param[in]   currData    stored block data information
 335  * @param[in]   receivedData    received CAData
 336  * @param[in]   status  block-wise state
 337  * @param[in]   isSizeOption    size option
 338  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 339  */
 340 CAResult_t CAUpdatePayloadData(CABlockData_t *currData, const CAData_t *receivedData,
 341                                uint8_t status, bool isSizeOption);
 342
 343 /**
 344  * Generate CAData structure  from the given information.
 345  * @param[in]   pdu pdu object
 346  * @param[in]   endpoint    information of remote device
 347  * @return generated CAData
 348  */
 349 CAData_t* CACreateNewDataSet(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint);
 350
 351 /**
 352  * Update the block option items
 353  * @param[in/out]   blockblock option of current message
 354  * @param[in]   blockType   block option type
 355  * @param[in]   responseResult  result code of pdu
 356  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 357  */
 358 CAResult_t CAHandleBlockErrorResponse(coap_block_t *block, uint16_t blockType,
 359                                       uint32_t responseResult);
 360
 361 /**
 362  * Check the received payload and if an error happens, return error type
 363  * @param[in/out]   currData    stored block data information
 364  * @param[in]   receivedBlock   received block option
 365  * @param[in]   receivedData    message type of pdu
 366  * @param[in]   blockType   block option type
 367  * @param[in]   dataLen received data length
 368  * @return block state
 369  */
 370 uint8_t CACheckBlockErrorType(CABlockData_t *currData, coap_block_t *receivedBlock,
 371                               const CAData_t *receivedData, uint16_t blockType,
 372                               size_t dataLen);
 373
 374 /**
 375  * Destroys the given CAData
 376  * @param[in]   data    CAData to destroy
 377  * @return generated CAData
 378  */
 379 void CADestroyDataSet(CAData_t* data);
 380
 381 /**
 382  * Print the given block option information
 383  * @param[in]   block   block option information
 384  */
 385 void CALogBlockInfo(coap_block_t *block);
 386
 387 /**
 388  * Create new CAData structure from the input information
 389  * @param[in]   data    CAData information that needs to be duplicated
 390  * @return created CAData structure
 391  */
 392 CAData_t *CACloneCAData(const CAData_t *data);
 393
 394 /**
 395  * Update payload from the input information
 396  * @param[in]   data    CAData information that needs to be updated
 397  * @param[in]   payload received new payload from the remote endpoint
 398  * @param[in]   payloadLen  received full payload length
 399  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 400  */
 401 CAResult_t CAUpdatePayloadToCAData(CAData_t *data, const CAPayload_t payload,
 402                                    size_t payloadLen);
 403
 404 /**
 405  * Get payload and payload length from the input information
 406  * @param[in]   data    CAData information
 407  * @param[out]  payloadLen  The payload length is stored.
 408  * @return payload
 409  */
 410 CAPayload_t CAGetPayloadInfo(const CAData_t *data, size_t *payloadLen);
 411
 412 /**
 413  * Set the block option type
 414  * @param[in]   token   token of current message
 415  * @param[in]   blockType   block option type
 416  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 417  */
 418 CAResult_t CAUpdateBlockOptionType(const unsigned char* token, uint8_t blockType);
 419
 420 /**
 421  * Get the block option type from block-wise transfer list
 422  * @param[in]   token   token of current message
 423  * @return block option type
 424  */
 425 uint8_t CAGetBlockOptionType(const unsigned char* token);
 426
 427 /**
 428  * Get the block data from block-wise transfer list
 429  * @param[in]   token   token of current message
 430  * @return CAData structure
 431  */
 432 CAData_t *CAGetDataSetFromBlockDataList(const unsigned char* token);
 433
 434 /**
 435  * Get token from block-wise transfer list
 436  * @param[in]   pdu received pdu binary data
 437  * @param[in]   endpoint    remote endpoint information
 438  * @param[in]   responseInfo    received response information
 439  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 440  */
 441 CAResult_t CAGetTokenFromBlockDataList(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
 442                                        CAResponseInfo_t *responseInfo);
 443
 444 /**
 445  * check whether the block data is valid or not
 446  * @param[in]   sendData    CAData information
 447  * @param[out]  blockData   block data when it is valid
 448  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 449  */
 450 CAResult_t CACheckBlockDataValidation(const CAData_t *sendData, CABlockData_t **blockData);
 451
 452 /**
 453  * Get the block data from block-wise transfer list
 454  * @param[in]   token   token of current message
 455  * @return CABlockData_t structure
 456  */
 457 CABlockData_t *CAGetBlockDataFromBlockDataList(const unsigned char* token);
 458
 459 /**
 460  * Get the block option from block-wise transfer list
 461  * @param[in]   token   token of current message
 462  * @return coap_block_t structure
 463  */
 464 coap_block_t *CAGetBlockOption(const unsigned char* token);
 465
 466 /**
 467  * Get the full payload from block-wise list
 468  * @param[in]   token   token of current message
 469  * @param[out]  fullPayloadLen  received full payload length
 470  * @return payload
 471  */
 472 CAPayload_t CAGetPayloadFromBlockDataList(const unsigned char* token, size_t *fullPayloadLen);
 473
 474 /**
 475  * Create the block data from given data and add the data in block-wise transfer list
 476  * @param[in]   sendData    data to be added to a list
 477  * @return created CABlockData_t structure
 478  *         and NULL point will be returned if there is error case.
 479  */
 480 CABlockData_t *CACreateNewBlockData(const CAData_t *sendData);
 481
 482 /**
 483  * Remove the block data in block-wise transfer list
 484  * @param[in]   token   token of current message
 485  * @return CA_STATUS_OK or ERROR CODES (CAResult_t error codes in cacommon.h)
 486  */
 487 CAResult_t CARemoveBlockDataFromList(const unsigned char* token);
 488
 489 /**
 490  * Check if data exist in block-wise transfer list.
 491  * @param[in]   pdu pdu object
 492  * @return true or false
 493  */
 494 bool CAIsBlockDataInList(const coap_pdu_t *pdu);
 495
 496
 497 #ifdef __cplusplus
 498 } /* extern "C" */
 499 #endif
 500
 501 #endif  // CA_BLOCKWISETRANSFER_H_