1 /* 2 * Copyright (C) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Bluetooth 18 * @{ 19 * 20 * @brief Bluetooth Basic tool library, This file is part of BTStack. 21 * Data Struct packet declarations. 22 * 23 * @since 1.0 24 * @version 1.0 25 */ 26 27 #ifndef PACKET_H 28 #define PACKET_H 29 30 #include "buffer.h" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 typedef struct Packet Packet; 37 typedef uint16_t (*CalCrc16)(uint8_t data, uint16_t preCrc); 38 39 /** 40 * @brief Create new specified size(headsize, tailsize, payloadsize) packet. 41 * Packet is Buffer type linked list. 42 * 43 * @param headSize Packet headSize, could be 0 or positive integer. 44 * @param tailSize Packet tailSize, could be 0 or positive integer. 45 * @param payloadSize Packet payloadSize, could be 0 or positive integer. 46 * @return Packet pointer. 47 * @since 1.0 48 * @version 1.0 49 */ 50 BTSTACK_API Packet *PacketMalloc(uint16_t headSize, uint16_t tailSize, uint32_t payloadSize); 51 52 /** 53 * @brief Copy malloc new packet by Existing packet. Do not copy data. 54 * 55 * @param pkt Existing packet pointer. 56 * @return Packet pointer. 57 * @since 1.0 58 * @version 1.0 59 */ 60 BTSTACK_API Packet *PacketRefMalloc(const Packet *pkt); 61 62 /** 63 * @brief Inherit malloc new packet by Existing packet. 64 * headSize and tailSize are added. 65 * Used in data downstream. 66 * 67 * @param pkt Packet pointer. 68 * @param headSize Packet headSize, could be 0 or positive integer. 69 * @param tailSize Packet tailSize, could be 0 or positive integer. 70 * @return Packet pointer. 71 * @since 1.0 72 * @version 1.0 73 */ 74 BTSTACK_API Packet *PacketInheritMalloc(const Packet *pkt, uint16_t headSize, uint16_t tailSize); 75 76 /** 77 * @brief Release Packet. 78 * 79 * @param pkt Packet pointer. 80 * @since 1.0 81 * @version 1.0 82 */ 83 BTSTACK_API void PacketFree(Packet *pkt); 84 85 /** 86 * @brief Get Packet head buffer. 87 * 88 * @param pkt Packet pointer. 89 * @return Packet head buffer. 90 * @since 1.0 91 * @version 1.0 92 */ 93 BTSTACK_API Buffer *PacketHead(const Packet *pkt); 94 95 /** 96 * @brief Get Packet head buffer. 97 * 98 * @param pkt Packet pointer. 99 * @return Packet head buffer. 100 * @since 1.0 101 * @version 1.0 102 */ 103 BTSTACK_API Buffer *PacketTail(const Packet *pkt); 104 105 /** 106 * @brief Get Packet payload buffer. 107 * Payload might be discontinuous, connect payload and return a continuous buffer. 108 * 109 * @param pkt Packet pointer. 110 * @return Buffer pointer. 111 * @since 1.0 112 * @version 1.0 113 */ 114 BTSTACK_API Buffer *PacketContinuousPayload(Packet *pkt); 115 116 /** 117 * @brief Get Packet payload size. 118 * 119 * @param pkt Packet pointer. 120 * @return Packet payload size. 121 * @since 1.0 122 * @version 1.0 123 */ 124 BTSTACK_API uint32_t PacketPayloadSize(const Packet *pkt); 125 126 /** 127 * @brief Read data from Packet payload. 128 * 129 * @param pkt Packet pointer. 130 * @param dst Data destination. 131 * @param offset Offset is relative to Packet's payload. 132 * @param size Read size. 133 * @return Success read size. 134 * @since 1.0 135 * @version 1.0 136 */ 137 BTSTACK_API uint32_t PacketPayloadRead(const Packet *pkt, uint8_t *dst, uint32_t offset, uint32_t size); 138 139 /** 140 * @brief Write data to Packet payload. 141 * 142 * @param pkt Packet pointer. 143 * @param src Data source. 144 * @param offset Offset is relative to Packet's payload. 145 * @param size Write size. 146 * @return Success write size. 147 * @since 1.0 148 * @version 1.0 149 */ 150 BTSTACK_API uint32_t PacketPayloadWrite(const Packet *pkt, const uint8_t *src, uint32_t offset, uint32_t size); 151 152 /** 153 * @brief Add one buffer block to Packet's payload last. (Before packet's tail) 154 * 155 * @param pkt Packet pointer. 156 * @param buf Add buffer pointer. 157 * @since 1.0 158 * @version 1.0 159 */ 160 BTSTACK_API void PacketPayloadAddLast(const Packet *pkt, const Buffer *buf); 161 162 /** 163 * @brief Get Packet size. 164 * 165 * @param pkt Packet pointer. 166 * @return Packet size. 167 * @since 1.0 168 * @version 1.0 169 */ 170 BTSTACK_API uint32_t PacketSize(const Packet *pkt); 171 172 /** 173 * @brief Read data from whole Packet. 174 * 175 * @param pkt Packet pointer. 176 * @param dst Data destination. 177 * @param offset Offset is relative to whole Packet. 178 * @param size Read size. 179 * @return Success read size. 180 * @since 1.0 181 * @version 1.0 182 */ 183 BTSTACK_API uint32_t PacketRead(const Packet *pkt, uint8_t *dst, uint32_t offset, uint32_t size); 184 185 /** 186 * @brief Extract Packet head from payload. 187 * Used in data upstream. 188 * 189 * @param pkt Packet pointer. 190 * @param data Data destination. 191 * @param size Extract size. 192 * @since 1.0 193 * @version 1.0 194 */ 195 BTSTACK_API void PacketExtractHead(Packet *pkt, uint8_t *data, uint32_t size); 196 197 /** 198 * @brief Extract Packet tail from payload. 199 * Used in data upstream. 200 * 201 * @param pkt Packet pointer. 202 * @param data Data destination. 203 * @param size Extract size. 204 * @since 1.0 205 * @version 1.0 206 */ 207 BTSTACK_API void PacketExtractTail(const Packet *pkt, uint8_t *data, uint32_t size); 208 209 /** 210 * @brief Fragment packet by fragLen. 211 * This operation will change the metadata in uplayer packet. 212 * If necessary, execute PacketRefMalloc before. 213 * Return uplayer packet remain length. 214 * Used in data downstream. 215 * 216 * @param uplayer Uplayer packet(Packet be fragmented). 217 * @param downlayer Downlayer packet(Fragmented results packet). 218 * @param fragLen Fragment length. 219 * @return Uplayer packet remain length. 220 * @since 1.0 221 * @version 1.0 222 */ 223 BTSTACK_API uint32_t PacketFragment(Packet *uplayer, const Packet *downlayer, uint32_t fragLen); 224 225 /** 226 * @brief Reassemble data packet. 227 * Used in data upstream. 228 * 229 * @param uplayer Uplayer packet(Packet assemble destination). 230 * @param downlayer Downlayer packet(Packet assemble source). 231 * @since 1.0 232 * @version 1.0 233 */ 234 BTSTACK_API void PacketAssemble(const Packet *uplayer, const Packet *downlayer); 235 236 /** 237 * @brief Packet calculate crc16. 238 * 239 * @param calCrc16 CalCrc16 algorithm. 240 * @return Computing result. 241 * @since 1.0 242 * @version 1.0 243 */ 244 BTSTACK_API uint16_t PacketCalCrc16(const Packet *pkt, CalCrc16 calCrc16); 245 246 /** 247 * @brief Packet verification crc16. 248 * 249 * @param calCrc16 CalCrc16 algorithm. 250 * @param crcVal Verification data. 251 * @return 0:success -1:failed 252 * @since 1.0 253 * @version 1.0 254 */ 255 BTSTACK_API int32_t PacketVerCrc16(const Packet *pkt, CalCrc16 calCrc16, uint16_t crcVal); 256 257 #ifdef __cplusplus 258 } 259 #endif 260 261 #endif // PACKET_H