mbed.org local branch of microbit-dal. The real version lives in git at https://github.com/lancaster-university/microbit-dal

Dependencies:   BLE_API nRF51822 mbed-dev-bin

Dependents:   microbit Microbit IoTChallenge1 microbit ... more

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers PacketBuffer.h Source File

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