Public Member Functions | Static Public Member Functions

ns3::Packet Class Reference
[Packet]

network packets More...

#include <packet.h>

Inheritance diagram for ns3::Packet:
Inheritance graph
[legend]
Collaboration diagram for ns3::Packet:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 Packet ()
 Packet (const Packet &o)
Packetoperator= (const Packet &o)
 Packet (uint32_t size)
 Packet (uint8_t const *buffer, uint32_t size, bool magic)
 Packet (uint8_t const *buffer, uint32_t size)
Ptr< PacketCreateFragment (uint32_t start, uint32_t length) const
uint32_t GetSize (void) const
void AddHeader (const Header &header)
uint32_t RemoveHeader (Header &header)
uint32_t PeekHeader (Header &header) const
void AddTrailer (const Trailer &trailer)
uint32_t RemoveTrailer (Trailer &trailer)
uint32_t PeekTrailer (Trailer &trailer)
void AddAtEnd (Ptr< const Packet > packet)
void AddPaddingAtEnd (uint32_t size)
void RemoveAtEnd (uint32_t size)
void RemoveAtStart (uint32_t size)
uint8_t const * PeekData (void) const NS_DEPRECATED
uint32_t CopyData (uint8_t *buffer, uint32_t size) const
void CopyData (std::ostream *os, uint32_t size) const
Ptr< PacketCopy (void) const
uint64_t GetUid (void) const
void Print (std::ostream &os) const
PacketMetadata::ItemIterator BeginItem (void) const
uint32_t GetSerializedSize (void) const
uint32_t Serialize (uint8_t *buffer, uint32_t maxSize) const
void AddByteTag (const Tag &tag) const
ByteTagIterator GetByteTagIterator (void) const
bool FindFirstMatchingByteTag (Tag &tag) const
void RemoveAllByteTags (void)
void PrintByteTags (std::ostream &os) const
void AddPacketTag (const Tag &tag) const
bool RemovePacketTag (Tag &tag)
bool PeekPacketTag (Tag &tag) const
void RemoveAllPacketTags (void)
void PrintPacketTags (std::ostream &os) const
PacketTagIterator GetPacketTagIterator (void) const
void SetNixVector (Ptr< NixVector >)
Ptr< NixVectorGetNixVector (void) const

Static Public Member Functions

static void EnablePrinting (void)
static void EnableChecking (void)

Detailed Description

network packets

Each network packet contains a byte buffer, a set of byte tags, a set of packet tags, and metadata.

Implementing a new type of Header or Trailer for a new protocol is pretty easy and is a matter of creating a subclass of the ns3::Header or of the ns3::Trailer base class, and implementing the methods described in their respective API documentation.

Implementing a new type of Tag requires roughly the same amount of work and this work is described in the ns3::Tag API documentation.

The performance aspects of the Packet API are discussed in Packet Performance


Constructor & Destructor Documentation

ns3::Packet::Packet (  ) 

Create an empty packet with a new uid (as returned by getUid).

ns3::Packet::Packet ( uint32_t  size  ) 

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).

Parameters:
size the size of the zero-filled payload
ns3::Packet::Packet ( uint8_t const *  buffer,
uint32_t  size,
bool  magic 
)

Create a new packet from the serialized buffer. This new packet is identical to the serialized packet contained in the buffer and is magically deserialized for you

Parameters:
buffer the serialized packet to be created
size the size of the packet for deserialization
magic allows packet deserialization; asserts when set to false
ns3::Packet::Packet ( uint8_t const *  buffer,
uint32_t  size 
)

Create a packet with payload filled with the content of this buffer. The input data is copied: the input buffer is untouched.

Parameters:
buffer the data to store in the packet.
size the size of the input buffer.

Member Function Documentation

void ns3::Packet::AddAtEnd ( Ptr< const Packet packet  ) 

Concatenate the input packet at the end of the current packet. This does not alter the uid of either packet.

Parameters:
packet packet to concatenate
void ns3::Packet::AddByteTag ( const Tag tag  )  const
Parameters:
tag the new tag to add to this packet

Tag each byte included in this packet with the new tag.

Note that adding a tag is a const operation which is pretty un-intuitive. The rationale is that the content and behavior of a packet is _not_ changed when a tag is added to a packet: any code which was not aware of the new tag is going to work just the same if the new tag is added. The real reason why adding a tag was made a const operation is to allow a trace sink which gets a packet to tag the packet, even if the packet is const (and most trace sources should use const packets because it would be totally evil to allow a trace sink to modify the content of a packet).

void ns3::Packet::AddHeader ( const Header header  ) 

Add header to this packet. This method invokes the Header::GetSerializedSize and Header::Serialize methods to reserve space in the buffer and request the header to serialize itself in the packet buffer.

Parameters:
header a reference to the header to add to this packet.
void ns3::Packet::AddPacketTag ( const Tag tag  )  const
Parameters:
tag the tag to store in this packet

Add a tag to this packet. This method calls the Tag::GetSerializedSize and, then, Tag::Serialize.

Note that this method is const, that is, it does not modify the state of this packet, which is fairly un-intuitive.

void ns3::Packet::AddPaddingAtEnd ( uint32_t  size  ) 
Parameters:
size number of padding bytes to add.
void ns3::Packet::AddTrailer ( const Trailer trailer  ) 

Add trailer to this packet. This method invokes the Trailer::GetSerializedSize and Trailer::Serialize methods to reserve space in the buffer and request the trailer to serialize itself in the packet buffer.

Parameters:
trailer a reference to the trailer to add to this packet.
PacketMetadata::ItemIterator ns3::Packet::BeginItem ( void   )  const
Returns:
an iterator which points to the first 'item' stored in this buffer. Note that this iterator will point to an empty array of items if you don't call EnablePrinting or EnableChecking before.
See also:
EnablePrinting EnableChecking
Ptr<Packet> ns3::Packet::Copy ( void   )  const
Returns:
a COW copy of the packet.

The returns packet will behave like an independent copy of the original packet, even though they both share the same datasets internally.

void ns3::Packet::CopyData ( std::ostream *  os,
uint32_t  size 
) const
Parameters:
os pointer to output stream in which we want to write the packet data.
size the maximum number of bytes we want to write in the output stream.
uint32_t ns3::Packet::CopyData ( uint8_t *  buffer,
uint32_t  size 
) const
Parameters:
buffer a pointer to a byte buffer where the packet data should be copied.
size the size of the byte buffer.
Returns:
the number of bytes read from the packet

No more than size bytes will be copied by this function.

Ptr<Packet> ns3::Packet::CreateFragment ( uint32_t  start,
uint32_t  length 
) const

Create a new packet which contains a fragment of the original packet. The returned packet shares the same uid as this packet.

Parameters:
start offset from start of packet to start of fragment to create
length length of fragment to create
Returns:
a fragment of the original packet
static void ns3::Packet::EnableChecking ( void   )  [static]

The packet metadata is also used to perform extensive sanity checks at runtime when performing operations on a Packet. For example, this metadata is used to verify that when you remove a header from a packet, this same header was actually present at the front of the packet. These errors will be detected and will abort the program.

static void ns3::Packet::EnablePrinting ( void   )  [static]

By default, packets do not keep around enough metadata to perform the operations requested by the Print methods. If you want to be able to invoke any of the two Print methods, you need to invoke this method at least once during the simulation setup and before any packet is created.

bool ns3::Packet::FindFirstMatchingByteTag ( Tag tag  )  const
Parameters:
tag the tag to search in this packet
Returns:
true if the requested tag type was found, false otherwise.

If the requested tag type is found, it is copied in the user's provided tag instance.

ByteTagIterator ns3::Packet::GetByteTagIterator ( void   )  const
Returns:
an iterator over the set of byte tags included in this packet.
PacketTagIterator ns3::Packet::GetPacketTagIterator ( void   )  const
Returns:
an object which can be used to iterate over the list of packet tags.
uint32_t ns3::Packet::GetSerializedSize ( void   )  const

For packet serializtion, the total size is checked in order to determine the size of the buffer required for serialization

Returns:
number of bytes required for packet serialization
uint32_t ns3::Packet::GetSize ( void   )  const [inline]
Returns:
the size in bytes of the packet (including the zero-filled initial payload)
uint64_t ns3::Packet::GetUid ( void   )  const

A packet is allocated a new uid when it is created empty or with zero-filled payload.

Note: This uid is an internal uid and cannot be counted on to provide an accurate counter of how many "simulated packets" of a particular protocol are in the system. It is not trivial to make this uid into such a counter, because of questions such as what should the uid be when the packet is sent over broadcast media, or when fragmentation occurs. If a user wants to trace actual packet counts, he or she should look at e.g. the IP ID field or transport sequence numbers, or other packet or frame counters at other protocol layers.

Returns:
an integer identifier which uniquely identifies this packet.
uint8_t const* ns3::Packet::PeekData ( void   )  const

If you try to change the content of the buffer returned by this method, you will die. Note that this method is now deprecated and will be removed in the next version of ns-3. If you need to get access to the content of the byte buffer of a packet, you need to call ns3::Packet::CopyData to perform an explicit copy.

Returns:
a pointer to the internal buffer of the packet.
uint32_t ns3::Packet::PeekHeader ( Header header  )  const

Deserialize but does _not_ remove the header from the internal buffer. This method invokes Header::Deserialize.

Parameters:
header a reference to the header to read from the internal buffer.
Returns:
the number of bytes read from the packet.
bool ns3::Packet::PeekPacketTag ( Tag tag  )  const
Parameters:
tag the tag to search in this packet
Returns:
true if the requested tag is found, false otherwise.

Search a matching tag and call Tag::Deserialize if it is found.

uint32_t ns3::Packet::PeekTrailer ( Trailer trailer  ) 

Deserialize but does _not_ remove a trailer from the internal buffer. This method invokes the Trailer::Deserialize method.

Parameters:
trailer a reference to the trailer to read from the internal buffer.
Returns:
the number of bytes read from the end of the packet.
void ns3::Packet::Print ( std::ostream &  os  )  const
Parameters:
os output stream in which the data should be printed.

Iterate over the headers and trailers present in this packet, from the first header to the last trailer and invoke, for each of them, the user-provided method Header::DoPrint or Trailer::DoPrint methods.

void ns3::Packet::PrintByteTags ( std::ostream &  os  )  const
Parameters:
os output stream in which the data should be printed.

Iterate over the tags present in this packet, and invoke the Print method of each tag stored in the packet.

void ns3::Packet::PrintPacketTags ( std::ostream &  os  )  const
Parameters:
os the stream in which we want to print data.

Print the list of 'packet' tags.

See also:
Packet::AddPacketTag, Packet::RemovePacketTag, Packet::PeekPacketTag, Packet::RemoveAllPacketTags
void ns3::Packet::RemoveAllByteTags ( void   ) 

Remove all the tags stored in this packet.

void ns3::Packet::RemoveAllPacketTags ( void   ) 

Remove all packet tags.

void ns3::Packet::RemoveAtEnd ( 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.

Parameters:
size number of bytes from remove
void ns3::Packet::RemoveAtStart ( 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.

Parameters:
size number of bytes from remove
uint32_t ns3::Packet::RemoveHeader ( Header header  ) 

Deserialize and remove the header from the internal buffer. This method invokes Header::Deserialize.

Parameters:
header a reference to the header to remove from the internal buffer.
Returns:
the number of bytes removed from the packet.
bool ns3::Packet::RemovePacketTag ( Tag tag  ) 
Parameters:
tag the tag to remove from this packet
Returns:
true if the requested tag is found, false otherwise.

Remove a tag from this packet. This method calls Tag::Deserialize if the tag is found.

uint32_t ns3::Packet::RemoveTrailer ( Trailer trailer  ) 

Remove a deserialized trailer from the internal buffer. This method invokes the Deserialize method.

Parameters:
trailer a reference to the trailer to remove from the internal buffer.
Returns:
the number of bytes removed from the end of the packet.

The documentation for this class was generated from the following file: