/*

 * Copyright (c) 2005,2006 INRIA

 * All rights reserved.

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 *

 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>

 */

#ifndef PACKET_H

#define PACKET_H

#include <stdint.h>

#include "buffer.h"

#include "header.h"

#include "trailer.h"

#include "tags.h"

#include "ns3/callback.h"

namespace ns3 {

/**

 * \brief network packets

 *

 * Each network packet contains a byte buffer and a list of tags.

 * - The byte buffer stores the serialized content of the headers and trailers 

 * added to a packet. The serialized representation of these headers is expected

 * to match that of real network packets bit for bit (although nothing

 * forces you to do this) which means that the content of a packet buffer

 * is expected to be that of a real packet.

 * - The list of tags stores an arbitrarily large set of arbitrary 

 * user-provided data structures in the packet: only one instance of

 * each type of data structure is allowed in a list of tags. 

 * These tags typically contain per-packet cross-layer information or 

 * flow identifiers. Each tag stored in the tag list can be at most

 * 16 bytes big. Trying to attach bigger data structures will trigger

 * crashes at runtime.

 *

 * Implementing a new type of Header for a new protocol is pretty easy

 * and is a matter of creating a subclass of the ns3::Header base class,

 * and implementing the 4 pure virtual methods defined in ns3::Header.

 * Sample code which shows how to create such a new Header, how to use

 * it, and how to manipulate tags is shown below:

 * \include samples/main-packet.cc

 *

 * The current implementation of the byte buffers and tag list is based

 * on COW (Copy On Write. An introduction to COW can be found in Scott 

 * Meyer's "More Effective C++", items 17 and 29). What this means is that

 * copying packets without modifying them is very cheap (in terms of cpu

 * and memory usage) and modifying them can be also very cheap. What is 

 * key for proper COW implementations is being

 * able to detect when a given modification of the state of a packet triggers

 * a full copy of the data prior to the modification: COW systems need

 * to detect when an operation is "dirty".

 *

 * Dirty operations:

 *   - ns3::Packet::removeTag

 *   - ns3::Packet::add

 *   - both versions of ns3::Packet::addAtEnd

 *

 * Non-dirty operations:

 *   - ns3::Packet::addTag

 *   - ns3::Packet::removeAllTags

 *   - ns3::Packet::peekTag

 *   - ns3::Packet::peek

 *   - ns3::Packet::remove

 *   - ns3::Packet::createFragment

 *   - ns3::Packet::removeAtStart

 *   - ns3::Packet::removeAtEnd

 *

 * Dirty operations will always be slower than non-dirty operations,

 * sometimes by several orders of magnitude. However, even the

 * dirty operations have been optimized for common use-cases which

 * means that most of the time, these operations will not trigger

 * data copies and will thus be still very fast.

 */

class Packet {

public:

	/**

	 * Create an empty packet with a new uid (as returned

	 * by getUid).

	 */

    Packet ();

	/**

	 * Create a packet with a zero-filled payload.

	 * The memory necessary for the payload is not allocated:

	 * it will be allocated at any later point if you attempt

	 * to fragment this packet or to access the zero-filled

	 * bytes. The packet is allocated with a new uid (as 

	 * returned by getUid).

	 * 

	 * \param size the size of the zero-filled payload

	 */

    Packet (uint32_t size);

	/**

	 * Create a new packet which contains a fragment of the original

	 * packet. The returned packet shares the same uid as this packet.

	 *

	 * \param start offset from start of packet to start of fragment to create

	 * \param length length of fragment to create

	 * \returns a fragment of the original packet

	 */

    Packet createFragment (uint32_t start, uint32_t length) const;

	/**

	 * \returns the size in bytes of the packet (including the zero-filled

	 *          initial payload)

	 */

    uint32_t getSize (void) const;

	/**

	 * Add header to this packet. This method invokes the

	 * ns3::Header::serializeTo method to request the header to serialize

	 * itself in the packet buffer.

	 *

	 * \param header a reference to the header to add to this packet.

	 */

	void add (Header const &header);

	/**

	 * Deserialize header from this packet. This method invokes the

	 * ns3::Header::deserializeFrom method to request the header to deserialize

	 * itself from the packet buffer. This method does not remove

	 * the data from the buffer. It merely reads it.

	 *

	 * \param header a reference to the header to deserialize from the buffer

	 */

	void peek (Header &header);

	/**

	 * Remove a deserialized header from the internal buffer.

	 * This method removes the bytes read by Packet::peek from

	 * the packet buffer.

	 *

	 * \param header a reference to the header to remove from the internal buffer.

	 */

	void remove (Header const &header);

	/**

	 * Add trailer to this packet. This method invokes the

	 * ns3::Trailer::serializeTo method to request the trailer to serialize

	 * itself in the packet buffer.

	 *

	 * \param trailer a reference to the trailer to add to this packet.

	 */

	void add (Trailer const &trailer);

	/**

	 * Deserialize trailer from this packet. This method invokes the

	 * ns3::Trailer::deserializeFrom method to request the trailer to deserialize

	 * itself from the packet buffer. This method does not remove

	 * the data from the buffer. It merely reads it.

	 *

	 * \param trailer a reference to the trailer to deserialize from the buffer

	 */

	void peek (Trailer &trailer);

	/**

	 * Remove a deserialized trailer from the internal buffer.

	 * This method removes the bytes read by Packet::peek from

	 * the packet buffer.

	 *

	 * \param trailer a reference to the trailer to remove from the internal buffer.

	 */

	void remove (Trailer const &trailer);

	/**

	 * Attach a tag to this packet. The tag is fully copied

	 * in a packet-specific internal buffer. This operation 

	 * is expected to be really fast.

	 *

	 * \param tag a pointer to the tag to attach to this packet.

	 */

    template <typename T>

    void addTag (T const &tag);

	/**

	 * Remove a tag from this packet. The data stored internally

	 * for this tag is copied in the input tag if an instance

	 * of this tag type is present in the internal buffer. If this

	 * tag type is not present, the input tag is not modified. 

	 *

	 * This operation can be potentially slow and might trigger

	 * unexpectedly large memory allocations. It is thus

	 * usually a better idea to create a copy of this packet,

	 * and invoke removeAllTags on the copy to remove all 

	 * tags rather than remove the tags one by one from a packet.

	 *

	 * \param tag a pointer to the tag to remove from this packet

	 * \returns true if an instance of this tag type is stored

	 *          in this packet, false otherwise.

	 */

    template <typename T>

    bool removeTag (T &tag);

	/**

	 * Copy a tag stored internally to the input tag. If no instance

	 * of this tag is present internally, the input tag is not modified.

	 *

	 * \param tag a pointer to the tag to read from this packet

	 * \returns true if an instance of this tag type is stored

	 *          in this packet, false otherwise.

	 */

    template <typename T>

    bool peekTag (T &tag) const;

	/**

	 * Remove all the tags stored in this packet. This operation is

	 * much much faster than invoking removeTag n times.

	 */

    void removeAllTags (void);

	/**

	 * Concatenate the input packet at the end of the current

	 * packet. This does not alter the uid of either packet.

	 *

	 * \param packet packet to concatenate

	 */

    void addAtEnd (Packet packet);

	/**

	 * Concatenate the fragment of the input packet identified

	 * by the offset and size parameters at the end of the current

	 * packet. This does not alter the uid of either packet.

	 *

	 * \param packet to concatenate

	 * \param offset offset of fragment to copy from the start of the input packet

	 * \param size size of fragment of input packet to copy.

	 */

    void addAtEnd (Packet packet, uint32_t offset, uint32_t size);

	/** 

	 * Remove size bytes from the end of the current packet

	 * It is safe to remove more bytes that what is present in

	 * the packet.

	 *

	 * \param size number of bytes from remove

	 */

    void removeAtEnd (uint32_t size);

	/** 

	 * Remove size bytes from the start of the current packet.

	 * It is safe to remove more bytes that what is present in

	 * the packet.

	 *

	 * \param size number of bytes from remove

	 */

    void removeAtStart (uint32_t size);

	/**

	 * If you try to change the content of the buffer

	 * returned by this method, you will die.

	 *

	 * \returns a pointer to the internal buffer of the packet.

	 */

	uint8_t const *peekData (void) const;

	/**

	 * A packet is allocated a new uid when it is created

	 * empty or with zero-filled payload.

	 *

	 * \returns an integer identifier which uniquely

	 *          identifies this packet.

	 */

	uint32_t getUid (void) const;

private:

    Packet (Buffer buffer, Tags tags, uint32_t uid);

    Buffer m_buffer;

    Tags m_tags;

	uint32_t m_uid;

	static uint32_t m_global_uid;

};

}; // namespace ns3

/**************************************************

    Start of implementation of templates defined

    above

 *************************************************/

namespace ns3 {

template <typename T>

void Packet::addTag (T const& tag)

{

    m_tags.add (tag);

}

template <typename T>

bool Packet::removeTag (T & tag)

{

    return m_tags.remove (tag);

}

template <typename T>

bool Packet::peekTag (T & tag) const

{

    return m_tags.peek (tag);

}

}; // namespace ns3

#endif /* PACKET_H */