Packet.h

00001 /*
00002  * Copyright (c) 2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef WIZFI310_PACKET_H__
00018 #define WIZFI310_PACKET_H__
00019 
00020 #include "mbed.h"
00021 
00022 /** Received packet.
00023  *
00024  * @warning Packets keep a reference into their source network interface.
00025  * They shall never outlive this interface.
00026  */
00027 class Packet {
00028 public:
00029     /**
00030      * Creates a new packet tracking memory usage in heap_usage.
00031      *
00032      * @param size          Size of the packet.
00033      * @param heap_usage    reference to a volatile long integer thread safely
00034      *                      keeping track of the memory usage.
00035      * @return A new packet or NULL on failure.
00036      */
00037     static Packet *new_packet(uint32_t size, volatile uint32_t &heap_usage);
00038 
00039     /**
00040      * Size of the packet.
00041      */
00042     uint32_t size() const
00043     {
00044         return m_size;
00045     }
00046     /**
00047      * Amount of data store in the packet.
00048      */
00049     uint32_t len() const
00050     {
00051         return m_len;
00052     }
00053     /**
00054      * Pointer to the internal buffer.
00055      */
00056     const char *data() const
00057     {
00058         return m_data;
00059     }
00060     /**
00061      * Pointer to the next packet in the chain or NULL if none.
00062      */
00063     Packet *next() const
00064     {
00065         return m_next;
00066     }
00067 
00068     /**
00069      * Appends up to `len` bytes from `data` into this packet and returns
00070      * the number of bytes copied.
00071      * @param   data    Source buffer.
00072      * @param   len     Source length.
00073      * @return number of bytes copied.
00074      */
00075     uint32_t append(const char *data, uint32_t len);
00076     /**
00077      * Consumes up to `len` bytes from this packet in to `data`.
00078      * @param   data    Output buffer.
00079      * @param   len     Output buffer length.
00080      * @return number of bytes copied into `data`.
00081      */
00082     uint32_t consume(char *data, uint32_t len);
00083     /**
00084      * Sets the pointer to next target.
00085      * @note Setting to NULL will not delete the next packet but simply detach it.
00086      */
00087     void set_next(Packet *next);
00088 
00089     /**
00090      * Deletes this packet and its following packets in the chain.
00091      * @warning it is unsafe to delete a packet that is referenced by another packet.
00092      */
00093     ~Packet();
00094 
00095 private:
00096     Packet *m_next;
00097     // packet's payload len.
00098     uint32_t m_len;
00099     // packet's size/capacity
00100     uint32_t m_size;
00101     // packet's payload.
00102     char *m_data;
00103     volatile uint32_t &m_ref_heap_usage;
00104 
00105     Packet(uint32_t size, volatile uint32_t &heap_usage): m_next(NULL), m_len(0), m_size(size), m_data(NULL), m_ref_heap_usage(heap_usage)
00106     {
00107         // this construct also prevents public from
00108         // using new by disabling generic constructors.
00109     }
00110 };
00111 
00112 #endif