35 class PacketPrinter; |
35 class PacketPrinter; |
36 |
36 |
37 /** |
37 /** |
38 * \brief network packets |
38 * \brief network packets |
39 * |
39 * |
40 * Each network packet contains a byte buffer and a list of tags. |
40 * Each network packet contains a byte buffer, a list of tags, and |
|
41 * metadata. |
|
42 * |
41 * - The byte buffer stores the serialized content of the headers and trailers |
43 * - The byte buffer stores the serialized content of the headers and trailers |
42 * added to a packet. The serialized representation of these headers is expected |
44 * added to a packet. The serialized representation of these headers is expected |
43 * to match that of real network packets bit for bit (although nothing |
45 * to match that of real network packets bit for bit (although nothing |
44 * forces you to do this) which means that the content of a packet buffer |
46 * forces you to do this) which means that the content of a packet buffer |
45 * is expected to be that of a real packet. |
47 * is expected to be that of a real packet. |
|
48 * |
46 * - The list of tags stores an arbitrarily large set of arbitrary |
49 * - The list of tags stores an arbitrarily large set of arbitrary |
47 * user-provided data structures in the packet: only one instance of |
50 * user-provided data structures in the packet: only one instance of |
48 * each type of data structure is allowed in a list of tags. |
51 * each type of data structure is allowed in a list of tags. |
49 * These tags typically contain per-packet cross-layer information or |
52 * These tags typically contain per-packet cross-layer information or |
50 * flow identifiers. Each tag stored in the tag list can be at most |
53 * flow identifiers. Each tag stored in the tag list can be at most |
51 * 16 bytes big. Trying to attach bigger data structures will trigger |
54 * 16 bytes big. Trying to attach bigger data structures will trigger |
52 * crashes at runtime. |
55 * crashes at runtime. |
53 * |
56 * |
54 * Implementing a new type of Header for a new protocol is pretty easy |
57 * - The metadata describes the type of the headers and trailers which |
55 * and is a matter of creating a subclass of the ns3::Header base class, |
58 * were serialized in the byte buffer. The maintenance of metadata is |
56 * and implementing the 4 pure virtual methods defined in ns3::Header. |
59 * optional and disabled by default. To enable it, you must call |
57 * Sample code which shows how to create such a new Header, how to use |
60 * Packet::EnableMetadata and this will allow you to get non-empty |
58 * it, and how to manipulate tags is shown below: |
61 * output from Packet::Print and Packet::PrintDefault. |
59 * \include samples/main-packet.cc |
62 * |
|
63 * Implementing a new type of Header or Trailer for a new protocol is |
|
64 * pretty easy and is a matter of creating a subclass of the ns3::Header |
|
65 * or of the ns3::Trailer base class, and implementing the 4 pure virtual |
|
66 * methods defined in either of the two base classes. Users _must_ |
|
67 * also implement a static public method named GetUid which is |
|
68 * expected to return a unique string which uniquely identifies the |
|
69 * user's new header or trailer. |
|
70 * |
|
71 * Sample code which shows how to create a new Header, and how to use it, |
|
72 * is shown in the sample file samples/main-header.cc |
|
73 * |
|
74 * Implementing a new type of Tag requires roughly the same amount of |
|
75 * work: |
60 * |
76 * |
61 * The current implementation of the byte buffers and tag list is based |
77 * The current implementation of the byte buffers and tag list is based |
62 * on COW (Copy On Write. An introduction to COW can be found in Scott |
78 * on COW (Copy On Write. An introduction to COW can be found in Scott |
63 * Meyer's "More Effective C++", items 17 and 29). What this means is that |
79 * Meyer's "More Effective C++", items 17 and 29). What this means is that |
64 * copying packets without modifying them is very cheap (in terms of cpu |
80 * copying packets without modifying them is very cheap (in terms of cpu |
68 * a full copy of the data prior to the modification: COW systems need |
84 * a full copy of the data prior to the modification: COW systems need |
69 * to detect when an operation is "dirty". |
85 * to detect when an operation is "dirty". |
70 * |
86 * |
71 * Dirty operations: |
87 * Dirty operations: |
72 * - ns3::Packet::RemoveTag |
88 * - ns3::Packet::RemoveTag |
73 * - ns3::Packet::Add |
89 * - ns3::Packet::AddHeader |
|
90 * - ns3::Packet::AddTrailer |
74 * - both versions of ns3::Packet::AddAtEnd |
91 * - both versions of ns3::Packet::AddAtEnd |
75 * |
92 * |
76 * Non-dirty operations: |
93 * Non-dirty operations: |
77 * - ns3::Packet::AddTag |
94 * - ns3::Packet::AddTag |
78 * - ns3::Packet::RemoveAllTags |
95 * - ns3::Packet::RemoveAllTags |
79 * - ns3::Packet::PeekTag |
96 * - ns3::Packet::PeekTag |
80 * - ns3::Packet::Peek |
97 * - ns3::Packet::RemoveHeader |
81 * - ns3::Packet::Remove |
98 * - ns3::Packet::RemoveTrailer |
82 * - ns3::Packet::CreateFragment |
99 * - ns3::Packet::CreateFragment |
83 * - ns3::Packet::RemoveAtStart |
100 * - ns3::Packet::RemoveAtStart |
84 * - ns3::Packet::RemoveAtEnd |
101 * - ns3::Packet::RemoveAtEnd |
85 * |
102 * |
86 * Dirty operations will always be slower than non-dirty operations, |
103 * Dirty operations will always be slower than non-dirty operations, |