Solution for Bluetooth SIG hands-on training course
Dependencies: BLE_API mbed-dev-bin nRF51822-bluetooth-mdw
Fork of microbit-dal-bluetooth-mdw_starter by
PacketBuffer.h
00001 /* 00002 The MIT License (MIT) 00003 00004 Copyright (c) 2016 British Broadcasting Corporation. 00005 This software is provided by Lancaster University by arrangement with the BBC. 00006 00007 Permission is hereby granted, free of charge, to any person obtaining a 00008 copy of this software and associated documentation files (the "Software"), 00009 to deal in the Software without restriction, including without limitation 00010 the rights to use, copy, modify, merge, publish, distribute, sublicense, 00011 and/or sell copies of the Software, and to permit persons to whom the 00012 Software is furnished to do so, subject to the following conditions: 00013 00014 The above copyright notice and this permission notice shall be included in 00015 all copies or substantial portions of the Software. 00016 00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 00023 DEALINGS IN THE SOFTWARE. 00024 */ 00025 00026 #ifndef MICROBIT_PACKET_BUFFER_H 00027 #define MICROBIT_PACKET_BUFFER_H 00028 00029 #include "mbed.h" 00030 #include "MicroBitConfig.h" 00031 #include "RefCounted.h" 00032 00033 struct PacketData : RefCounted 00034 { 00035 uint16_t rssi; // The radio signal strength this packet was received. 00036 uint8_t length; // The length of the payload in bytes 00037 uint8_t payload[0]; // User / higher layer protocol data 00038 }; 00039 00040 /** 00041 * Class definition for a PacketBuffer. 00042 * A PacketBuffer holds a series of bytes that can be sent or received from the MicroBitRadio channel. 00043 * 00044 * @note This is a mutable, managed type. 00045 */ 00046 class PacketBuffer 00047 { 00048 PacketData *ptr; // Pointer to payload data 00049 00050 public: 00051 00052 /** 00053 * Provide a pointer to a memory location containing the packet data. 00054 * 00055 * @return The contents of this packet, as an array of bytes. 00056 */ 00057 uint8_t *getBytes(); 00058 00059 /** 00060 * Default Constructor. 00061 * Creates an empty Packet Buffer. 00062 * 00063 * @code 00064 * PacketBuffer p(); 00065 * @endcode 00066 */ 00067 PacketBuffer(); 00068 00069 /** 00070 * Constructor. 00071 * Creates a new PacketBuffer of the given size. 00072 * 00073 * @param length The length of the buffer to create. 00074 * 00075 * @code 00076 * PacketBuffer p(16); // Creates a PacketBuffer 16 bytes long. 00077 * @endcode 00078 */ 00079 PacketBuffer(int length); 00080 00081 /** 00082 * Constructor. 00083 * Creates an empty Packet Buffer of the given size, 00084 * and fills it with the data provided. 00085 * 00086 * @param data The data with which to fill the buffer. 00087 * 00088 * @param length The length of the buffer to create. 00089 * 00090 * @param rssi The radio signal strength at the time this packet was recieved. Defaults to 0. 00091 * 00092 * @code 00093 * uint8_t buf = {13,5,2}; 00094 * PacketBuffer p(buf, 3); // Creates a PacketBuffer 3 bytes long. 00095 * @endcode 00096 */ 00097 PacketBuffer(uint8_t *data, int length, int rssi = 0); 00098 00099 /** 00100 * Copy Constructor. 00101 * Add ourselves as a reference to an existing PacketBuffer. 00102 * 00103 * @param buffer The PacketBuffer to reference. 00104 * 00105 * @code 00106 * PacketBuffer p(); 00107 * PacketBuffer p2(p); // Refers to the same packet as p. 00108 * @endcode 00109 */ 00110 PacketBuffer(const PacketBuffer &buffer); 00111 00112 /** 00113 * Internal constructor-initialiser. 00114 * 00115 * @param data The data with which to fill the buffer. 00116 * 00117 * @param length The length of the buffer to create. 00118 * 00119 * @param rssi The radio signal strength at the time this packet was recieved. 00120 */ 00121 void init(uint8_t *data, int length, int rssi); 00122 00123 /** 00124 * Destructor. 00125 * 00126 * Removes buffer resources held by the instance. 00127 */ 00128 ~PacketBuffer(); 00129 00130 /** 00131 * Copy assign operation. 00132 * 00133 * Called when one PacketBuffer is assigned the value of another using the '=' operator. 00134 * 00135 * Decrements our reference count and free up the buffer as necessary. 00136 * 00137 * Then, update our buffer to refer to that of the supplied PacketBuffer, 00138 * and increase its reference count. 00139 * 00140 * @param p The PacketBuffer to reference. 00141 * 00142 * @code 00143 * uint8_t buf = {13,5,2}; 00144 * PacketBuffer p1(16); 00145 * PacketBuffer p2(buf, 3); 00146 * 00147 * p1 = p2; 00148 * @endcode 00149 */ 00150 PacketBuffer& operator = (const PacketBuffer& p); 00151 00152 /** 00153 * Array access operation (read). 00154 * 00155 * Called when a PacketBuffer is dereferenced with a [] operation. 00156 * 00157 * Transparently map this through to the underlying payload for elegance of programming. 00158 * 00159 * @code 00160 * PacketBuffer p1(16); 00161 * uint8_t data = p1[0]; 00162 * @endcode 00163 */ 00164 uint8_t operator [] (int i) const; 00165 00166 /** 00167 * Array access operation (modify). 00168 * 00169 * Called when a PacketBuffer is dereferenced with a [] operation. 00170 * 00171 * Transparently map this through to the underlying payload for elegance of programming. 00172 * 00173 * @code 00174 * PacketBuffer p1(16); 00175 * p1[0] = 42; 00176 * @endcode 00177 */ 00178 uint8_t& operator [] (int i); 00179 00180 /** 00181 * Equality operation. 00182 * 00183 * Called when one PacketBuffer is tested to be equal to another using the '==' operator. 00184 * 00185 * @param p The PacketBuffer to test ourselves against. 00186 * 00187 * @return true if this PacketBuffer is identical to the one supplied, false otherwise. 00188 * 00189 * @code 00190 * MicroBitDisplay display; 00191 * uint8_t buf = {13,5,2}; 00192 * PacketBuffer p1(); 00193 * PacketBuffer p2(); 00194 * 00195 * if(p1 == p2) // will be true 00196 * display.scroll("same!"); 00197 * @endcode 00198 */ 00199 bool operator== (const PacketBuffer& p); 00200 00201 /** 00202 * Sets the byte at the given index to value provided. 00203 * 00204 * @param position The index of the byte to change. 00205 * 00206 * @param value The new value of the byte (0-255). 00207 * 00208 * @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER. 00209 * 00210 * @code 00211 * PacketBuffer p1(16); 00212 * p1.setByte(0,255); // Sets the first byte in the buffer to the value 255. 00213 * @endcode 00214 */ 00215 int setByte(int position, uint8_t value); 00216 00217 /** 00218 * Determines the value of the given byte in the packet. 00219 * 00220 * @param position The index of the byte to read. 00221 * 00222 * @return The value of the byte at the given position, or MICROBIT_INVALID_PARAMETER. 00223 * 00224 * @code 00225 * PacketBuffer p1(16); 00226 * p1.setByte(0,255); // Sets the first byte in the buffer to the value 255. 00227 * p1.getByte(0); // Returns 255. 00228 * @endcode 00229 */ 00230 int getByte(int position); 00231 00232 /** 00233 * Gets number of bytes in this buffer 00234 * 00235 * @return The size of the buffer in bytes. 00236 * 00237 * @code 00238 * PacketBuffer p1(16); 00239 * p1.length(); // Returns 16. 00240 * @endcode 00241 */ 00242 int length(); 00243 00244 /** 00245 * Retrieves the received signal strength of this packet. 00246 * 00247 * @return The signal strength of the radio when this packet was received, in -dbM. 00248 * 00249 * @code 00250 * PacketBuffer p1(16); 00251 * p1.getRSSI(); // Returns the received signal strength. 00252 * @endcode 00253 */ 00254 int getRSSI(); 00255 00256 /** 00257 * Sets the received signal strength of this packet. 00258 * 00259 * @code 00260 * PacketBuffer p1(16); 00261 * p1.setRSSI(37); 00262 * @endcode 00263 */ 00264 void setRSSI(uint8_t rssi); 00265 00266 static PacketBuffer EmptyPacket; 00267 }; 00268 00269 #endif
Generated on Tue Jul 12 2022 20:39:13 by 1.7.2