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