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