21 #ifndef PACKET_H |
21 #ifndef PACKET_H |
22 #define PACKET_H |
22 #define PACKET_H |
23 |
23 |
24 #include <stdint.h> |
24 #include <stdint.h> |
25 #include "buffer.h" |
25 #include "buffer.h" |
26 #include "chunk.h" |
|
27 #include "header.h" |
26 #include "header.h" |
28 #include "tags.h" |
27 #include "tags.h" |
29 #include "ns3/callback.h" |
28 #include "ns3/callback.h" |
30 |
29 |
31 namespace ns3 { |
30 namespace ns3 { |
32 |
31 |
33 /** |
32 /** |
34 * \brief network packets |
33 * \brief network packets |
35 * |
34 * |
36 * Each network packet contains a byte buffer and a list of tags. |
35 * Each network packet contains a byte buffer and a list of tags. |
37 * - The byte buffer stores the serialized content of the chunks added |
36 * - The byte buffer stores the serialized content of the headers and trailers |
38 * to a packet. The serialized representation of these chunks is expected |
37 * added to a packet. The serialized representation of these headers is expected |
39 * to match that of real network packets bit for bit (although nothing |
38 * to match that of real network packets bit for bit (although nothing |
40 * forces you to do this) which means that the content of a packet buffer |
39 * forces you to do this) which means that the content of a packet buffer |
41 * is expected to be that of a real packet. |
40 * is expected to be that of a real packet. |
42 * - The list of tags stores an arbitrarily large set of arbitrary |
41 * - The list of tags stores an arbitrarily large set of arbitrary |
43 * user-provided data structures in the packet: only one instance of |
42 * user-provided data structures in the packet: only one instance of |
45 * These tags typically contain per-packet cross-layer information or |
44 * These tags typically contain per-packet cross-layer information or |
46 * flow identifiers. Each tag stored in the tag list can be at most |
45 * flow identifiers. Each tag stored in the tag list can be at most |
47 * 16 bytes big. Trying to attach bigger data structures will trigger |
46 * 16 bytes big. Trying to attach bigger data structures will trigger |
48 * crashes at runtime. |
47 * crashes at runtime. |
49 * |
48 * |
50 * Implementing a new type of Chunk for a new protocol is pretty easy |
49 * Implementing a new type of Header for a new protocol is pretty easy |
51 * and is a matter of creating a subclass of the ns3::Chunk base class, |
50 * and is a matter of creating a subclass of the ns3::Header base class, |
52 * and implementing the 4 pure virtual methods defined in ns3::Chunk. |
51 * and implementing the 4 pure virtual methods defined in ns3::Header. |
53 * Sample code which shows how to create such a new Chunk, how to use |
52 * Sample code which shows how to create such a new Header, how to use |
54 * it, and how to manipulate tags is shown below: |
53 * it, and how to manipulate tags is shown below: |
55 * \include samples/main-packet.cc |
54 * \include samples/main-packet.cc |
56 * |
55 * |
57 * The current implementation of the byte buffers and tag list is based |
56 * The current implementation of the byte buffers and tag list is based |
58 * on COW (Copy On Write. An introduction to COW can be found in Scott |
57 * on COW (Copy On Write. An introduction to COW can be found in Scott |
116 * \returns the size in bytes of the packet (including the zero-filled |
115 * \returns the size in bytes of the packet (including the zero-filled |
117 * initial payload) |
116 * initial payload) |
118 */ |
117 */ |
119 uint32_t getSize (void) const; |
118 uint32_t getSize (void) const; |
120 /** |
119 /** |
121 * Add chunk to this packet. This method invokes the |
120 * Add header to this packet. This method invokes the |
122 * ns3::Chunk::addTo method to request the chunk to serialize |
121 * ns3::Header::serializeTo method to request the header to serialize |
123 * itself in the packet buffer. |
122 * itself in the packet buffer. |
124 * |
123 * |
125 * \param chunk a pointer to the chunk to add to this packet. |
124 * \param header a reference to the header to add to this packet. |
126 */ |
125 */ |
127 void add (Chunk const&chunk); |
126 void add (Header const &header); |
128 /** |
127 /** |
129 * Deserialize chunk from this packet. This method invokes the |
128 * Deserialize header from this packet. This method invokes the |
130 * ns3::Chunk::peekFrom method to request the chunk to deserialize |
129 * ns3::Header::deserializeFrom method to request the header to deserialize |
131 * itself from the packet buffer. This method does not remove |
130 * itself from the packet buffer. This method does not remove |
132 * the chunk from the buffer. |
131 * the data from the buffer. It merely reads it. |
133 * |
132 * |
134 * \param chunk a pointer to the chunk to deserialize from the buffer |
133 * \param header a reference to the header to deserialize from the buffer |
135 */ |
134 */ |
136 void peek (Chunk &chunk) const; |
|
137 /** |
|
138 * Remove a deserialized chunk from the internal buffer. |
|
139 * This method invokes ns3::Chunk::removeFrom to complete |
|
140 * the work initiated by Packet::peek and ns3::Chunk::peekFrom. |
|
141 * |
|
142 * \param chunk a pointer to the chunk to remove from the internal buffer. |
|
143 */ |
|
144 void remove (Chunk &chunk); |
|
145 void add (Header const &header); |
|
146 void peek (Header &header); |
135 void peek (Header &header); |
|
136 /** |
|
137 * Remove a deserialized header from the internal buffer. |
|
138 * This method removes the bytes read by Packet::peek from |
|
139 * the packet buffer. |
|
140 * |
|
141 * \param header a reference to the header to remove from the internal buffer. |
|
142 */ |
147 void remove (Header const &header); |
143 void remove (Header const &header); |
148 /** |
144 /** |
149 * Attach a tag to this packet. The tag is fully copied |
145 * Attach a tag to this packet. The tag is fully copied |
150 * in a packet-specific internal buffer. This operation |
146 * in a packet-specific internal buffer. This operation |
151 * is expected to be really fast. |
147 * is expected to be really fast. |