PacketBuffer.cpp

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 #include "MicroBitConfig.h"
00027 #include "PacketBuffer.h"
00028 #include "ErrorNo.h"
00029 
00030 // Create the EmptyPacket reference.
00031 PacketBuffer PacketBuffer::EmptyPacket = PacketBuffer(1);
00032 
00033 /**
00034   * Default Constructor.
00035   * Creates an empty Packet Buffer.
00036   *
00037   * @code
00038   * PacketBuffer p();
00039   * @endcode
00040   */
00041 PacketBuffer::PacketBuffer()
00042 {
00043     this->init(NULL, 0, 0);
00044 }
00045 
00046 /**
00047   * Constructor.
00048   * Creates a new PacketBuffer of the given size.
00049   *
00050   * @param length The length of the buffer to create.
00051   *
00052   * @code
00053   * PacketBuffer p(16);         // Creates a PacketBuffer 16 bytes long.
00054   * @endcode
00055   */
00056 PacketBuffer::PacketBuffer(int length)
00057 {
00058     this->init(NULL, length, 0);
00059 }
00060 
00061 /**
00062   * Constructor.
00063   * Creates an empty Packet Buffer of the given size,
00064   * and fills it with the data provided.
00065   *
00066   * @param data The data with which to fill the buffer.
00067   *
00068   * @param length The length of the buffer to create.
00069   *
00070   * @param rssi The radio signal strength at the time this packet was recieved. Defaults to 0.
00071   *
00072   * @code
00073   * uint8_t buf = {13,5,2};
00074   * PacketBuffer p(buf, 3);         // Creates a PacketBuffer 3 bytes long.
00075   * @endcode
00076   */
00077 PacketBuffer::PacketBuffer(uint8_t *data, int length, int rssi)
00078 {
00079     this->init(data, length, rssi);
00080 }
00081 
00082 /**
00083   * Copy Constructor.
00084   * Add ourselves as a reference to an existing PacketBuffer.
00085   *
00086   * @param buffer The PacketBuffer to reference.
00087   *
00088   * @code
00089   * PacketBuffer p();
00090   * PacketBuffer p2(p); // Refers to the same packet as p.
00091   * @endcode
00092   */
00093 PacketBuffer::PacketBuffer(const PacketBuffer &buffer)
00094 {
00095     ptr = buffer.ptr;
00096     ptr->incr();
00097 }
00098 
00099 /**
00100   * Internal constructor-initialiser.
00101   *
00102   * @param data The data with which to fill the buffer.
00103   *
00104   * @param length The length of the buffer to create.
00105   *
00106   * @param rssi The radio signal strength at the time this packet was recieved.
00107   */
00108 void PacketBuffer::init(uint8_t *data, int length, int rssi)
00109 {
00110     if (length < 0)
00111         length = 0;
00112 
00113     ptr = (PacketData *) malloc(sizeof(PacketData) + length);
00114     ptr->init();
00115 
00116     ptr->length = length;
00117     ptr->rssi = rssi;
00118 
00119     // Copy in the data buffer, if provided.
00120     if (data)
00121         memcpy(ptr->payload, data, length);
00122 }
00123 
00124 /**
00125   * Destructor.
00126   *
00127   * Removes buffer resources held by the instance.
00128   */
00129 PacketBuffer::~PacketBuffer()
00130 {
00131     ptr->decr();
00132 }
00133 
00134 /**
00135   * Copy assign operation.
00136   *
00137   * Called when one PacketBuffer is assigned the value of another using the '=' operator.
00138   *
00139   * Decrements our reference count and free up the buffer as necessary.
00140   *
00141   * Then, update our buffer to refer to that of the supplied PacketBuffer,
00142   * and increase its reference count.
00143   *
00144   * @param p The PacketBuffer to reference.
00145   *
00146   * @code
00147   * uint8_t buf = {13,5,2};
00148   * PacketBuffer p1(16);
00149   * PacketBuffer p2(buf, 3);
00150   *
00151   * p1 = p2;
00152   * @endcode
00153   */
00154 PacketBuffer& PacketBuffer::operator = (const PacketBuffer &p)
00155 {
00156     if(ptr == p.ptr)
00157         return *this;
00158 
00159     ptr->decr();
00160     ptr = p.ptr;
00161     ptr->incr();
00162 
00163     return *this;
00164 }
00165 
00166 /**
00167   * Array access operation (read).
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   * uint8_t data = p1[0];
00176   * @endcode
00177   */
00178 uint8_t PacketBuffer::operator [] (int i) const
00179 {
00180     return ptr->payload[i];
00181 }
00182 
00183 /**
00184   * Array access operation (modify).
00185   *
00186   * Called when a PacketBuffer is dereferenced with a [] operation.
00187   *
00188   * Transparently map this through to the underlying payload for elegance of programming.
00189   *
00190   * @code
00191   * PacketBuffer p1(16);
00192   * p1[0] = 42;
00193   * @endcode
00194   */
00195 uint8_t& PacketBuffer::operator [] (int i)
00196 {
00197     return ptr->payload[i];
00198 }
00199 
00200 /**
00201   * Equality operation.
00202   *
00203   * Called when one PacketBuffer is tested to be equal to another using the '==' operator.
00204   *
00205   * @param p The PacketBuffer to test ourselves against.
00206   *
00207   * @return true if this PacketBuffer is identical to the one supplied, false otherwise.
00208   *
00209   * @code
00210   * MicroBitDisplay display;
00211   * uint8_t buf = {13,5,2};
00212   * PacketBuffer p1();
00213   * PacketBuffer p2();
00214   *
00215   * if(p1 == p2)                    // will be true
00216   *     display.scroll("same!");
00217   * @endcode
00218   */
00219 bool PacketBuffer::operator== (const PacketBuffer& p)
00220 {
00221     if (ptr == p.ptr)
00222         return true;
00223     else
00224         return (ptr->length == p.ptr->length && (memcmp(ptr->payload, p.ptr->payload, ptr->length)==0));
00225 }
00226 
00227 /**
00228   * Sets the byte at the given index to value provided.
00229   *
00230   * @param position The index of the byte to change.
00231   *
00232   * @param value The new value of the byte (0-255).
00233   *
00234   * @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.
00235   *
00236   * @code
00237   * PacketBuffer p1(16);
00238   * p1.setByte(0,255);              // Sets the first byte in the buffer to the value 255.
00239   * @endcode
00240   */
00241 int PacketBuffer::setByte(int position, uint8_t value)
00242 {
00243     if (position < ptr->length)
00244     {
00245         ptr->payload[position] = value;
00246         return MICROBIT_OK;
00247     }
00248     else
00249     {
00250         return MICROBIT_INVALID_PARAMETER;
00251     }
00252 }
00253 
00254 /**
00255   * Determines the value of the given byte in the packet.
00256   *
00257   * @param position The index of the byte to read.
00258   *
00259   * @return The value of the byte at the given position, or MICROBIT_INVALID_PARAMETER.
00260   *
00261   * @code
00262   * PacketBuffer p1(16);
00263   * p1.setByte(0,255);              // Sets the first byte in the buffer to the value 255.
00264   * p1.getByte(0);                  // Returns 255.
00265   * @endcode
00266   */
00267 int PacketBuffer::getByte(int position)
00268 {
00269     if (position < ptr->length)
00270         return ptr->payload[position];
00271     else
00272         return MICROBIT_INVALID_PARAMETER;
00273 }
00274 
00275 /**
00276   * Provide a pointer to a memory location containing the packet data.
00277   *
00278   * @return The contents of this packet, as an array of bytes.
00279   */
00280 uint8_t*PacketBuffer::getBytes()
00281 {
00282     return ptr->payload;
00283 }
00284 
00285 /**
00286   * Gets number of bytes in this buffer
00287   *
00288   * @return The size of the buffer in bytes.
00289   *
00290   * @code
00291   * PacketBuffer p1(16);
00292   * p1.length(); // Returns 16.
00293   * @endcode
00294   */
00295 int PacketBuffer::length()
00296 {
00297     return ptr->length;
00298 }
00299 
00300 /**
00301   * Retrieves the received signal strength of this packet.
00302   *
00303   * @return The signal strength of the radio when this packet was received, in -dbM.
00304   *
00305   * @code
00306   * PacketBuffer p1(16);
00307   * p1.getRSSI();                 // Returns the received signal strength.
00308   * @endcode
00309   */
00310 int PacketBuffer::getRSSI()
00311 {
00312     return ptr->rssi;
00313 }
00314 
00315 /**
00316   * Sets the received signal strength of this packet.
00317   *
00318   * @code
00319   * PacketBuffer p1(16);
00320   * p1.setRSSI(37);
00321   * @endcode
00322   */
00323 void PacketBuffer::setRSSI(uint8_t rssi)
00324 {
00325     ptr->rssi = rssi;
00326 }