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);
 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);
 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);
 330
 331 /**
 332  * Add the block option in pdu data.
 333  * @param[in]   pdu    pdu object.
 334  * @param[out]  block    block data.
 335  * @param[in]   blockType   block option type.
 336  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 337  */
 338 CAResult_t CAAddBlockOptionImpl(coap_pdu_t *pdu, coap_block_t *block, uint8_t blockType);
 339
 340 /**
 341  * Add the size option in pdu data.
 342  * @param[in/out]   pdu    pdu object.
 343  * @param[in]   sizeType    size option type.
 344  * @param[in]   dataLength the total payload length to be sent.
 345  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 346  */
 347 CAResult_t CAAddBlockSizeOption(coap_pdu_t *pdu, uint16_t sizeType, size_t dataLength);
 348
 349 /**
 350  * Get the size option from pdu data.
 351  * @param[in]   pdu    pdu object.
 352  * @param[in]   sizeType    size option type.
 353  * @param[out]  totalPayloadLen the total payload length to be received.
 354  * @return true or false.
 355  */
 356 bool CAIsPayloadLengthInPduWithBlockSizeOption(coap_pdu_t *pdu,
 357                                                uint16_t sizeType,
 358                                                size_t *totalPayloadLen);
 359
 360 /**
 361  * update the total payload with the received payload.
 362  * @param[in]   currData    stored block data information.
 363  * @param[in]   receivedData    received CAData.
 364  * @param[in]   status  block-wise state.
 365  * @param[in]   isSizeOption    size option.
 366  * @param[in]   blockType    block option type.
 367  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 368  */
 369 CAResult_t CAUpdatePayloadData(CABlockData_t *currData, const CAData_t *receivedData,
 370                                uint8_t status, bool isSizeOption, uint16_t blockType);
 371
 372 /**
 373  * Generate CAData structure  from the given information.
 374  * @param[in]   pdu    pdu object.
 375  * @param[in]   endpoint    information of remote device.
 376  * @return generated CAData.
 377  */
 378 CAData_t* CACreateNewDataSet(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint);
 379
 380 /**
 381  * Update the block option items.
 382  * @param[in/out]   blockblock option of current message.
 383  * @param[in]   blockType   block option type.
 384  * @param[in]   responseResult  result code of pdu.
 385  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 386  */
 387 CAResult_t CAHandleBlockErrorResponse(coap_block_t *block, uint16_t blockType,
 388                                       uint32_t responseResult);
 389
 390 /**
 391  * Check the received payload and if an error happens, return error type.
 392  * @param[in/out]   currData    stored block data information.
 393  * @param[in]   receivedBlock   received block option.
 394  * @param[in]   receivedData    message type of pdu.
 395  * @param[in]   blockType   block option type.
 396  * @param[in]   dataLen received data length.
 397  * @return block state.
 398  */
 399 uint8_t CACheckBlockErrorType(CABlockData_t *currData, coap_block_t *receivedBlock,
 400                               const CAData_t *receivedData, uint16_t blockType,
 401                               size_t dataLen);
 402
 403 /**
 404  * Destroys the given CAData.
 405  * @param[in]   data    CAData to destroy.
 406  * @return generated CAData.
 407  */
 408 void CADestroyDataSet(CAData_t* data);
 409
 410 /**
 411  * Create the blockId for CABlockData.
 412  * @param[in]   token   token of current message.
 413  * @param[in]   tokenLength   token length of current message.
 414  * @param[in]   portNumber   port.
 415  * @return ID set of CABlockData.
 416  */
 417 CABlockDataID_t* CACreateBlockDatablockId(const CAToken_t token, uint8_t tokenLength,
 418                                           uint16_t portNumber);
 419
 420 /**
 421  * Destroy the blockId set.
 422  * @param[in]   blockID     ID set of CABlockData.
 423  */
 424 void CADestroyBlockID(CABlockDataID_t *blockID);
 425
 426 /**
 427  * check whether Block ID is matched or not.
 428  * @param[in]   currData    block data.
 429  * @param[in]   blockID     ID set of CABlockData.
 430  * @return true or false.
 431  */
 432 bool CABlockidMatches(const CABlockData_t *currData, const CABlockDataID_t *blockID);
 433 /**
 434  * Print the given block option information.
 435  * @param[in]   block   block option information.
 436  */
 437 void CALogBlockInfo(coap_block_t *block);
 438
 439 /**
 440  * Create new CAData structure from the input information.
 441  * @param[in]   data    CAData information that needs to be duplicated.
 442  * @return created CAData structure.
 443  */
 444 CAData_t *CACloneCAData(const CAData_t *data);
 445
 446 /**
 447  * Update payload from the input information.
 448  * @param[in]   data    CAData information that needs to be updated.
 449  * @param[in]   payload received new payload from the remote endpoint.
 450  * @param[in]   payloadLen  received full payload length.
 451  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 452  */
 453 CAResult_t CAUpdatePayloadToCAData(CAData_t *data, const CAPayload_t payload,
 454                                    size_t payloadLen);
 455
 456 /**
 457  * Get payload and payload length from the input information.
 458  * @param[in]   data    CAData information.
 459  * @param[out]  payloadLen  The payload length is stored.
 460  * @return payload.
 461  */
 462 CAPayload_t CAGetPayloadInfo(const CAData_t *data, size_t *payloadLen);
 463
 464 /**
 465  * Set the block option type.
 466  * @param[in]   blockID     ID set of CABlockData.
 467  * @param[in]   blockType   block option type.
 468  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 469  */
 470 CAResult_t CAUpdateBlockOptionType(const CABlockDataID_t *blockID,
 471                                    uint8_t blockType);
 472
 473 /**
 474  * Get the block option type from block-wise transfer list.
 475  * @param[in]   blockID     ID set of CABlockData.
 476  * @return block option type.
 477  */
 478 uint8_t CAGetBlockOptionType(const CABlockDataID_t *blockID);
 479
 480 /**
 481  * Get the block data from block-wise transfer list.
 482  * @param[in]   blockID     ID set of CABlockData.
 483  * @return CAData structure.
 484  */
 485 CAData_t *CAGetDataSetFromBlockDataList(const CABlockDataID_t *blockID);
 486
 487 /**
 488  * Get token from block-wise transfer list.
 489  * @param[in]   pdu    received pdu binary data.
 490  * @param[in]   endpoint    remote endpoint information.
 491  * @param[in]   responseInfo    received response information.
 492  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 493  */
 494 CAResult_t CAGetTokenFromBlockDataList(const coap_pdu_t *pdu, const CAEndpoint_t *endpoint,
 495                                        CAResponseInfo_t *responseInfo);
 496
 497 /**
 498  * check whether the block data is valid or not.
 499  * @param[in]   sendData    CAData information.
 500  * @param[out]  blockData   block data when it is valid.
 501  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 502  */
 503 CAResult_t CACheckBlockDataValidation(const CAData_t *sendData, CABlockData_t **blockData);
 504
 505 /**
 506  * Get the block data from block-wise transfer list.
 507  * @param[in]   blockID     ID set of CABlockData.
 508  * @return CABlockData_t structure.
 509  */
 510 CABlockData_t *CAGetBlockDataFromBlockDataList(const CABlockDataID_t *blockID);
 511
 512 /**
 513  * Get the block option from block-wise transfer list.
 514  * @param[in]   blockID     ID set of CABlockData.
 515  * @param[in]   blockType    block option type.
 516  * @return coap_block_t structure.
 517  */
 518 coap_block_t *CAGetBlockOption(const CABlockDataID_t *blockID,
 519                                uint16_t blockType);
 520
 521 /**
 522  * Get the full payload from block-wise list.
 523  * @param[in]   blockID     ID set of CABlockData.
 524  * @param[out]  fullPayloadLen  received full payload length.
 525  * @return payload.
 526  */
 527 CAPayload_t CAGetPayloadFromBlockDataList(const CABlockDataID_t *blockID,
 528                                           size_t *fullPayloadLen);
 529
 530 /**
 531  * Create the block data from given data and add the data in block-wise transfer list.
 532  * @param[in]   sendData    data to be added to a list.
 533  * @return created CABlockData_t structure.
 534  *         and NULL point will be returned if there is error case..
 535  */
 536 CABlockData_t *CACreateNewBlockData(const CAData_t *sendData);
 537
 538 /**
 539  * Remove the block data in block-wise transfer list.
 540  * @param[in]   blockID     ID set of CABlockData.
 541  * @return ::CASTATUS_OK or ERROR CODES (::CAResult_t error codes in cacommon.h).
 542  */
 543 CAResult_t CARemoveBlockDataFromList(const CABlockDataID_t *blockID);
 544
 545 /**
 546  * Check if data exist in block-wise transfer list.
 547  * @param[in]   blockID     ID set of CABlockData.
 548  * @return true or false.
 549  */
 550 bool CAIsBlockDataInList(const CABlockDataID_t *blockID);
 551
 552
 553 #ifdef __cplusplus
 554 } /* extern "C" */
 555 #endif
 556
 557 #endif  // CA_BLOCKWISETRANSFER_H_