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 MTU supported for BLE adapter
  37  */
  38 #define CA_SUPPORTED_BLE_MTU_SIZE  20
  39
  40 /**
  41  * The maximum port value for BLE packet format
  42  */
  43 #define CA_SUPPORTED_BLE_MAX_PORT  127
  44
  45 /**
  46  * The minimum port value for BLE packet format
  47  */
  48 #define CA_SUPPORTED_BLE_MIN_PORT  1
  49
  50 /**
  51  * The multicaset packet remote port value
  52  */
  53 #define CA_BLE_MULTICAST_PORT  0
  54
  55 /**
  56  * The header size for ble fragmentation.
  57  * Specific header descriptions are below.
  58  */
  59 #define CA_BLE_HEADER_SIZE 2
  60
  61 /**
  62  * The length header size for ble fragmentation.
  63  * Length header is embedded in first packet of entire CoAP PDU.
  64  */
  65 #define CA_BLE_LENGTH_HEADER_SIZE 4
  66
  67 /**
  68  * Current Header version.
  69  */
  70 #define HEADER_VERSION 1
  71
  72 #ifdef __cplusplus
  73 extern "C"
  74 {
  75 #endif
  76
  77 /**
  78  * This enum value is used to make the CA BLE packet header.
  79  * 1st bit is used to check whether the packet is start packet or not.
  80  * Start packet should be marked ad CA_BLE_PACKET_START(1) and any other
  81  * packet is marked as CA_BLE_PACKET_NOT_START(0).
  82  */
  83 typedef enum {
  84     CA_BLE_PACKET_NOT_START     = 0,
  85     CA_BLE_PACKET_START         = 1
  86 } CABLEPacketStart_t;
  87
  88 /**
  89  * This enum value is used to make the CA BLE packet header.
  90  * 9th bit is uesd to check the packet use secure logic(dtls) or not.
  91  * Secure packet should be marking CA_BLE_PACKET_SECURE(1) and other
  92  * packet is makred CA_BLE_PACKET_NON_SECURE(0).
  93  */
  94 typedef enum {
  95     CA_BLE_PACKET_NON_SECURE    = 0,
  96     CA_BLE_PACKET_SECURE        = 1
  97 } CABLEPacketSecure_t;
  98
  99
 100 /*****************************************************************
 101  * @file The CA Header format
 102  * CA Header will be defined by 2 bytes of Header.
 103  * First one bit : Header type that is start packet or not.
 104  * 2nd to 8th bit : Own unique port value.
 105  * 9th bit: Secure type using dtls(1) or not(0).
 106  * 10th to 16th bit : Remote endpoint unique port value.
 107  *
 108  * Start packet has additional 4 bytes size length header which
 109  * represent total packet size.
 110  *****************************************************************/
 111
 112 /**
 113  * This function is used to generate the CA BLE variable related to
 114  * maintain the fragmentation logic. The variable is used in BLE send routine.
 115  *
 116  * @param[in]   dataLength      Original packet size about data to send.
 117  * @param[out]  midPacketCount  Number of mid packet except first and last
 118  *                              packet.
 119  * @param[out]  remainingLen    Size of last packet before adding header.
 120  * @param[out]  totalLengh      The total length of the data.
 121  *
 122  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 123  *           or other error values on error.
 124  * @retval ::CA_STATUS_OK             Successful
 125  * @retval ::CA_STATUS_FAILED         Operation failed
 126  */
 127 CAResult_t CAGenerateVariableForFragmentation(size_t dataLength,
 128                                               uint32_t *midPacketCount,
 129                                               size_t *remainingLen,
 130                                               size_t *totalLength);
 131
 132 /**
 133  * This function is used to generate the CA BLE header to
 134  * maintain the fragmentation logic. The header structure explained
 135  * above will be formed and returned to the caller.
 136  *
 137  * @param[in,out] header       Pointer to the octet array that will
 138  *                             contain the generated header.
 139  * @param[in]     type         Enum value to check start packet or not.
 140  *                             it will be embedded in bit 1 of the header
 141  * @param[in]     sourcePort   Source(own) port of the unique(in device)
 142  *                             value. it will be embedded in bits 2~8 of
 143  *                             the header.
 144  * @param[in]     secure       Enum value to check whether secure or not.
 145  *                             it will be embedded in bit 9 of the header.
 146  * @param[in]     destPort     Destination(remote endpoint) port of the
 147  *                             unique(in device) value. it will be embedded
 148  *                             in bits 10~16 of the header.
 149  *
 150  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 151  *           or other error values on error.
 152  * @retval ::CA_STATUS_OK             Successful
 153  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 154  * @retval ::CA_STATUS_FAILED         Operation failed
 155  */
 156 CAResult_t CAGenerateHeader(uint8_t *header,
 157                             CABLEPacketStart_t type,
 158                             const uint8_t sourcePort,
 159                             CABLEPacketSecure_t secure,
 160                             const uint8_t destPort);
 161
 162 /**
 163  * This function is used to generate the CA BLE length header to
 164  * maintain the fragmentation logic. The header structure explained
 165  * above will be formed and returned to the caller.
 166  *
 167  * @param[in,out] header       Pointer to the octet array that will
 168  *                             contain the generated length header.
 169  * @param[in]     headerLength Length about header array. it should be
 170  *                             same as CA_BLE_LENGTH_HEADER_SIZE.
 171  * @param[in]     dataLength   The total length of data size. it will
 172  *                             be embedded in 4 bytes of the length header.
 173  *
 174  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 175  *           or other error values on error.
 176  * @retval ::CA_STATUS_OK             Successful
 177  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 178  * @retval ::CA_STATUS_FAILED         Operation failed
 179  */
 180 CAResult_t CAGenerateHeaderPayloadLength(uint8_t *header,
 181                                          size_t headerLength,
 182                                          size_t dataLength);
 183
 184 /**
 185  * This function is used to make the CA BLE first data segment to
 186  * maintain the fragmentation logic. start data segment is included
 187  * 2 bytes header, 4 bytes length header and transmit data.
 188  *
 189  * @param[out]  dataSegment    Pointer to the octet array that will
 190  *                             contain the generated data packet.
 191  * @param[in]   data           Data to the octet array that required
 192  *                             transmittin to remote device. it will
 193  *                             be embedded in 7th byte to data length.
 194  * @param[in]   dataLength     The length of data size.
 195  * @param[in]   dataHeader     Pointer to the octet array that contain
 196  *                             data header.
 197  * @param[in]   lengthHeader   Pointer to the octet array that contain
 198  *                             length header.
 199  *
 200  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 201  *           or other error values on error.
 202  * @retval ::CA_STATUS_OK             Successful
 203  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 204  * @retval ::CA_STATUS_FAILED         Operation failed
 205  */
 206 CAResult_t CAMakeFirstDataSegment(uint8_t *dataSegment,
 207                                   const uint8_t *data,
 208                                   const uint32_t dataLength,
 209                                   const uint8_t *dataHeader,
 210                                   const uint8_t *lengthHeader);
 211
 212 /**
 213  * This function is used to make the CA BLE second to end data segment
 214  * to maintain the fragmentation logic. start data segment is included
 215  * 2 bytes header and transmit data.
 216  *
 217  * @param[out]  dataSegment    Pointer to the octet array that will
 218  *                             contain the generated data packet.
 219  * @param[in]   data           Data to the octet array that required
 220  *                             transmittin to remote device. it will
 221  *                             be embedded in 7th byte to data length.
 222  * @param[in]   dataLength     The length of data size.
 223  * @param[in]   index          Index to determine whether some of the
 224  *                             total data
 225  * @param[in]   dataHeader     Pointer to the octet array that contain
 226  *                             data header.
 227  *
 228  * @return ::CA_STATUS_OK on success. One of the CA_STATUS_FAILED
 229  *           or other error values on error.
 230  * @retval ::CA_STATUS_OK             Successful
 231  * @retval ::CA_STATUS_INVALID_PARAM  Invalid input arguments
 232  * @retval ::CA_STATUS_FAILED         Operation failed
 233  */
 234 CAResult_t CAMakeRemainDataSegment(uint8_t *dataSegment,
 235                                    const uint8_t *data,
 236                                    const uint32_t dataLength,
 237                                    const uint32_t index,
 238                                    const uint8_t *dataHeader);
 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_ */