resource/csdk/connectivity/inc/cafragmentation.h

   1 /* ****************************************************************
   2  *
   3  * Copyright 2016 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  *
  24  * This file contains common utility functions to manage the CA msg
  25  * fragmentation and reassemebly.
  26  */
  27
  28
  29 #ifndef CA_FRAGMENTATION_H_
  30 #define CA_FRAGMENTATION_H_
  31
  32 #include "cacommon.h"
  33 #include "logger.h"
  34
  35 /**
  36  * The maximum port value for BLE packet format
  37  */
  38 #define CA_SUPPORTED_BLE_MAX_PORT  127
  39
  40 /**
  41  * The minimum port value for BLE packet format
  42  */
  43 #define CA_SUPPORTED_BLE_MIN_PORT  1
  44
  45 /**
  46  * The multicaset packet remote port value
  47  */
  48 #define CA_BLE_MULTICAST_PORT  0
  49
  50 /**
  51  * The header size for ble fragmentation.
  52  * Specific header descriptions are below.
  53  */
  54 #define CA_BLE_HEADER_SIZE 2
  55
  56 /**
  57  * The length header size for ble fragmentation.
  58  * Length header is embedded in first packet of entire CoAP PDU.
  59  */
  60 #define CA_BLE_LENGTH_HEADER_SIZE 4
  61
  62 /**
  63  * Current Header version.
  64  */
  65 #define HEADER_VERSION 1
  66
  67 #ifdef __cplusplus
  68 extern "C"
  69 {
  70 #endif
  71
  72 /**
  73  * This enum value is used to make the CA BLE packet header.
  74  * 1st bit is used to check whether the packet is start packet or not.
  75  * Start packet should be marked ad CA_BLE_PACKET_START(1) and any other
  76  * packet is marked as CA_BLE_PACKET_NOT_START(0).
  77  */
  78 typedef enum {
  79     CA_BLE_PACKET_NOT_START     = 0,
  80     CA_BLE_PACKET_START         = 1
  81 } CABLEPacketStart_t;
  82
  83 /**
  84  * This enum value is used to make the CA BLE packet header.
  85  * 9th bit is uesd to check the packet use secure logic(dtls) or not.
  86  * Secure packet should be marking CA_BLE_PACKET_SECURE(1) and other
  87  * packet is makred CA_BLE_PACKET_NON_SECURE(0).
  88  */
  89 typedef enum {
  90     CA_BLE_PACKET_NON_SECURE    = 0,
  91     CA_BLE_PACKET_SECURE        = 1
  92 } CABLEPacketSecure_t;
  93
  94
  95 /*****************************************************************
  96  * @file The CA Header format
  97  * CA Header will be defined by 2 bytes of Header.
  98  * First one bit : Header type that is start packet or not.
  99  * 2nd to 8th bit : Own unique port value.
 100  * 9th bit: Secure type using dtls(1) or not(0).
 101  * 10th to 16th bit : Remote endpoint unique port value.
 102  *
 103  * Start packet has additional 4 bytes size length header which
 104  * represent total packet size.
 105  *****************************************************************/
 106
 107 /**
 108  * This function is used to generate the CA BLE variable related to
 109  * maintain the fragmentation logic. The variable is used in BLE send routine.
 110  *
 111  * @param[in]   dataLength      Original packet size about data to send.
 112  * @param[out]  midPacketCount  Number of mid packet except first and last
 113  *                              packet.
 114  * @param[out]  remainingLen    Size of last packet before adding header.
 115  * @param[out]  totalLengh      The total length of the data.
 116  *
 117  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 118  *           or other error values on error.
 119  * @retval ::CA_STATUS_OK             Successful
 120  * @retval ::CA_STATUS_FAILED         Operation failed
 121  */
 122 CAResult_t CAGenerateVariableForFragmentation(size_t dataLength,
 123                                               uint32_t *midPacketCount,
 124                                               size_t *remainingLen,
 125                                               size_t *totalLength,
 126                                               uint16_t mtuSize);
 127
 128 /**
 129  * This function is used to generate the CA BLE header to
 130  * maintain the fragmentation logic. The header structure explained
 131  * above will be formed and returned to the caller.
 132  *
 133  * @param[in,out] header       Pointer to the octet array that will
 134  *                             contain the generated header.
 135  * @param[in]     type         Enum value to check start packet or not.
 136  *                             it will be embedded in bit 1 of the header
 137  * @param[in]     sourcePort   Source(own) port of the unique(in device)
 138  *                             value. it will be embedded in bits 2~8 of
 139  *                             the header.
 140  * @param[in]     secure       Enum value to check whether secure or not.
 141  *                             it will be embedded in bit 9 of the header.
 142  * @param[in]     destPort     Destination(remote endpoint) port of the
 143  *                             unique(in device) value. it will be embedded
 144  *                             in bits 10~16 of the header.
 145  *
 146  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 147  *           or other error values on error.
 148  * @retval ::CA_STATUS_OK             Successful
 149  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 150  * @retval ::CA_STATUS_FAILED         Operation failed
 151  */
 152 CAResult_t CAGenerateHeader(uint8_t *header,
 153                             CABLEPacketStart_t type,
 154                             const uint8_t sourcePort,
 155                             CABLEPacketSecure_t secure,
 156                             const uint8_t destPort);
 157
 158 /**
 159  * This function is used to generate the CA BLE length header to
 160  * maintain the fragmentation logic. The header structure explained
 161  * above will be formed and returned to the caller.
 162  *
 163  * @param[in,out] header       Pointer to the octet array that will
 164  *                             contain the generated length header.
 165  * @param[in]     headerLength Length about header array. it should be
 166  *                             same as CA_BLE_LENGTH_HEADER_SIZE.
 167  * @param[in]     dataLength   The total length of data size. it will
 168  *                             be embedded in 4 bytes of the length header.
 169  *
 170  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 171  *           or other error values on error.
 172  * @retval ::CA_STATUS_OK             Successful
 173  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 174  * @retval ::CA_STATUS_FAILED         Operation failed
 175  */
 176 CAResult_t CAGenerateHeaderPayloadLength(uint8_t *header,
 177                                          size_t headerLength,
 178                                          size_t dataLength);
 179
 180 /**
 181  * This function is used to make the CA BLE first data segment to
 182  * maintain the fragmentation logic. start data segment is included
 183  * 2 bytes header, 4 bytes length header and transmit data.
 184  *
 185  * @param[out]  dataSegment    Pointer to the octet array that will
 186  *                             contain the generated data packet.
 187  * @param[in]   data           Data to the octet array that required
 188  *                             transmittin to remote device. it will
 189  *                             be embedded in 7th byte to data length.
 190  * @param[in]   dataLength     The length of data size.
 191  * @param[in]   dataHeader     Pointer to the octet array that contain
 192  *                             data header.
 193  * @param[in]   lengthHeader   Pointer to the octet array that contain
 194  *                             length header.
 195  *
 196  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 197  *           or other error values on error.
 198  * @retval ::CA_STATUS_OK             Successful
 199  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 200  * @retval ::CA_STATUS_FAILED         Operation failed
 201  */
 202 CAResult_t CAMakeFirstDataSegment(uint8_t *dataSegment,
 203                                   const uint8_t *data,
 204                                   const uint32_t dataLength,
 205                                   const uint8_t *dataHeader,
 206                                   const uint8_t *lengthHeader);
 207
 208 /**
 209  * This function is used to make the CA BLE second to end data segment
 210  * to maintain the fragmentation logic. start data segment is included
 211  * 2 bytes header and transmit data.
 212  *
 213  * @param[out]  dataSegment            Pointer to the octet array that will
 214  *                                     contain the generated data packet.
 215  * @param[in]   segmentPayloadLength   The length of data segment payload.
 216  * @param[in]   sourceData             Data to the octet array that required
 217  *                                     transmission to remote device. it will
 218  *                                     be embedded in 7th byte to data length.
 219  * @param[in]   sourceDataLength       The length of total data.
 220  * @param[in]   segmentNum             Index to determine whether some of the
 221  *                                     total data
 222  * @param[in]   dataHeader             Pointer to the octet array that contain
 223  *                                     data header.
 224  * @param[in]   mtuSize                MTU size.
 225  *
 226  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 227  *           or other error values on error.
 228  * @retval ::CA_STATUS_OK             Successful
 229  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 230  * @retval ::CA_STATUS_FAILED         Operation failed
 231  */
 232 CAResult_t CAMakeRemainDataSegment(uint8_t *dataSegment,
 233                                    const uint32_t segmentPayloadLength,
 234                                    const uint8_t *sourceData,
 235                                    const uint32_t sourceDataLength,
 236                                    const uint32_t segmentNum,
 237                                    const uint8_t *dataHeader,
 238                                    uint16_t mtuSize);
 239
 240 /**
 241  * This function is used to parse the header in the receiver end. This
 242  * function will provide the information of the type of the packet, source(remote) /
 243  * destination port info and secure infomation.
 244  *
 245  * @param[in]   header      Pointer to the octet array data which contains
 246  *                          the header information.  Note that pointer should
 247  *                          point to two bytes of data header which needs to
 248  *                          be parsed.
 249  * @param[out]  type        Enum value to check start packet or not.
 250  *                          it will be embedded in bit 1 of the header
 251  * @param[out]  sourcePort  Source(own) port of the unique(in device)
 252  *                          value. it will be embedded in bits 2~8 of
 253  *                          the header.
 254  * @param[out]  secure      Enum value to check whether secure or not.
 255  *                          it will be embedded in bit 9 of the header.
 256  * @param[out]  destPort    Destination(remote endpoint) port of the
 257  *                          unique(in device) value. it will be embedded
 258  *                          in bits 10~16 of the header.
 259  *
 260  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 261  *           or other error values on error.
 262  * @retval ::CA_STATUS_OK             Successful
 263  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 264  * @retval ::CA_STATUS_FAILED         Operation failed
 265  */
 266 CAResult_t CAParseHeader(const uint8_t *header,
 267                          CABLEPacketStart_t *startFlag,
 268                          uint16_t *sourcePort,
 269                          CABLEPacketSecure_t *secureFlag,
 270                          uint16_t *destPort);
 271
 272 /**
 273  * This function is used to parse the length header in the receiver end. This
 274  * function will provide the total data length about defragmented data.
 275  *
 276  * @param[in]   header        Pointer to the octet array that will
 277  *                            contain length infomation.
 278  * @param[out]  headerLength  Length about header array. it should be
 279  *                            same as CA_BLE_LENGTH_HEADER_SIZE.
 280  * @param[out]  dataLength    The total length of data size. it will
 281  *                            be embedded in 4 bytes of the length header.
 282  *
 283  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 284  *           or other error values on error.
 285  * @retval ::CA_STATUS_OK             Successful
 286  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 287  * @retval ::CA_STATUS_FAILED         Operation failed
 288  */
 289 CAResult_t CAParseHeaderPayloadLength(uint8_t *header,
 290                                       size_t headerLength,
 291                                       uint32_t *dataLength);
 292
 293 #ifdef __cplusplus
 294 } /* extern "C" */
 295 #endif
 296
 297 #endif  /* CA_FRAGMENTATION_H_ */