1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2 /*
3 * Copyright (c) 2005,2006 INRIA
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License version 2 as
7 * published by the Free Software Foundation;
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 *
18 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
19 */
20 #ifndef PACKET_H
21 #define PACKET_H
22
23 #include <stdint.h>
24 #include "buffer.h"
25 #include "header.h"
26 #include "trailer.h"
27 #include "packet-metadata.h"
28 #include "tag.h"
29 #include "byte-tag-list.h"
30 #include "packet-tag-list.h"
31 #include "nix-vector.h"
32 #include "ns3/mac48-address.h"
33 #include "ns3/callback.h"
34 #include "ns3/assert.h"
35 #include "ns3/ptr.h"
36 #include "ns3/deprecated.h"
37
38 namespace ns3 {
39
40 // Forward declaration
41 class Address;
42
43 /**
44 * \ingroup network
45 * \defgroup packet Packet
46 */
47
48 /**
49 * \ingroup packet
50 * \brief Iterator over the set of byte tags in a packet
51 *
52 * This is a java-style iterator.
53 */
54 class ByteTagIterator
55 {
56 public:
57 /**
58 * \brief Identifies a byte tag and a set of bytes within a packet
59 * to which the tag applies.
60 */
61 class Item
62 {
63 public:
64 /**
65 * \returns the ns3::TypeId associated to this tag.
66 */
67 TypeId GetTypeId (void) const;
68 /**
69 * \returns the index of the first byte tagged by this tag.
70 *
71 * \brief The index is an offset from the start of the packet.
72 */
73 uint32_t GetStart (void) const;
74 /**
75 * \returns the index of the last byte tagged by this tag.
76 *
77 * \brief The index is an offset from the start of the packet.
78 */
79 uint32_t GetEnd (void) const;
80 /**
81 * \brief Read the requested tag and store it in the user-provided tag instance.
82 *
83 * \param tag the user tag to which the data should be copied.
84 *
85 * This method will crash if the type of the tag provided
86 * by the user does not match the type of the underlying tag.
87 */
88 void GetTag (Tag &tag) const;
89 private:
90 /// Friend class
91 friend class ByteTagIterator;
92 /**
93 * \brief Constructor
94 * \param tid the ns3::TypeId associated to this tag.
95 * \param start the index of the first byte tagged by this tag.
96 * \param end the index of the last byte tagged by this tag.
97 * \param buffer the buffer associated with this tag.
98 */
99 Item (TypeId tid, uint32_t start, uint32_t end, TagBuffer buffer);
100
101 TypeId m_tid; //!< the ns3::TypeId associated to this tag.
102 uint32_t m_start; //!< the index of the first byte tagged by this tag.
103 uint32_t m_end; //!< the index of the last byte tagged by this tag.
104 TagBuffer m_buffer; //!< the buffer associated with this tag.
105 };
106 /**
107 * \returns true if calling Next is safe, false otherwise.
108 */
109 bool HasNext (void) const;
110 /**
111 * \returns the next item found and prepare for the next one.
112 */
113 Item Next (void);
114 private:
115 /// Friend class
116 friend class Packet;
117 /**
118 * Copy Constructor
119 * \param i object to copy
120 */
121 ByteTagIterator (ByteTagList::Iterator i);
122 ByteTagList::Iterator m_current; //!< actual position over the set of byte tags in a packet
123 };
124
125 /**
126 * \ingroup packet
127 * \brief Iterator over the set of packet tags in a packet
128 *
129 * This is a java-style iterator.
130 */
131 class PacketTagIterator
132 {
133 public:
134 /**
135 * Identifies a packet tag within a packet.
136 */
137 class Item
138 {
139 public:
140 /**
141 * \returns the ns3::TypeId associated to this tag.
142 */
143 TypeId GetTypeId (void) const;
144 /**
145 * Read the requested tag and store it in the user-provided tag instance.
146 *
147 * \param tag the user tag to which the data should be copied.
148 *
149 * This method will crash if the type of the tag provided
150 * by the user does not match the type of the underlying tag.
151 */
152 void GetTag (Tag &tag) const;
153 private:
154 /// Friend class
155 friend class PacketTagIterator;
156 /**
157 * Constructor
158 * \param data the data to copy.
159 */
160 Item (const struct PacketTagList::TagData *data);
161 const struct PacketTagList::TagData *m_data; //!< the tag data
162 };
163 /**
164 * \returns true if calling Next is safe, false otherwise.
165 */
166 bool HasNext (void) const;
167 /**
168 * \returns the next item found and prepare for the next one.
169 */
170 Item Next (void);
171 private:
172 /// Friend class
173 friend class Packet;
174 /**
175 * Constructor
176 * \param head head of the items
177 */
178 PacketTagIterator (const struct PacketTagList::TagData *head);
179 const struct PacketTagList::TagData *m_current; //!< actual position over the set of tags in a packet
180 };
181
182 /**
183 * \ingroup packet
184 * \brief network packets
185 *
186 * Each network packet contains a byte buffer, a set of byte tags, a set of
187 * packet tags, and metadata.
188 *
189 * - The byte buffer stores the serialized content of the headers and trailers
190 * added to a packet. The serialized representation of these headers is expected
191 * to match that of real network packets bit for bit (although nothing
192 * forces you to do this) which means that the content of a packet buffer
193 * is expected to be that of a real packet.
194 *
195 * - The metadata describes the type of the headers and trailers which
196 * were serialized in the byte buffer. The maintenance of metadata is
197 * optional and disabled by default. To enable it, you must call
198 * Packet::EnablePrinting and this will allow you to get non-empty
199 * output from Packet::Print. If you wish to only enable
200 * checking of metadata, and do not need any printing capability, you can
201 * call Packet::EnableChecking: its runtime cost is lower than
202 * Packet::EnablePrinting.
203 *
204 * - The set of tags contain simulation-specific information which cannot
205 * be stored in the packet byte buffer because the protocol headers or trailers
206 * have no standard-conformant field for this information. So-called
207 * 'byte' tags are used to tag a subset of the bytes in the packet byte buffer
208 * while 'packet' tags are used to tag the packet itself. The main difference
209 * between these two kinds of tags is what happens when packets are copied,
210 * fragmented, and reassembled: 'byte' tags follow bytes while 'packet' tags
211 * follow packets. Another important difference between these two kinds of tags
212 * is that byte tags cannot be removed and are expected to be written once,
213 * and read many times, while packet tags are expected to be written once,
214 * read many times, and removed exactly once. An example of a 'byte'
215 * tag is a FlowIdTag which contains a flow id and is set by the application
216 * generating traffic. An example of a 'packet' tag is a cross-layer
217 * qos class id set by an application and processed by a lower-level MAC
218 * layer.
219 *
220 * Implementing a new type of Header or Trailer for a new protocol is
221 * pretty easy and is a matter of creating a subclass of the ns3::Header
222 * or of the ns3::Trailer base class, and implementing the methods
223 * described in their respective API documentation.
224 *
225 * Implementing a new type of Tag requires roughly the same amount of
226 * work and this work is described in the ns3::Tag API documentation.
227 *
228 * The performance aspects copy-on-write semantics of the
229 * Packet API are discussed in \ref packetperf
230 */
231 class Packet : public SimpleRefCount<Packet>
232 {
233 public:
234
235 /**
236 * \brief Create an empty packet with a new uid (as returned
237 * by getUid).
238 */
239 Packet ();
240 /**
241 * \brief Copy constructor
242 * \param o object to copy
243 */
244 Packet (const Packet &o);
245 /**
246 * \brief Basic assignment
247 * \param o object to copy
248 * \return the copied object
249 */
250 Packet &operator = (const Packet &o);
251 /**
252 * \brief Create a packet with a zero-filled payload.
253 *
254 * The memory necessary for the payload is not allocated:
255 * it will be allocated at any later point if you attempt
256 * to fragment this packet or to access the zero-filled
257 * bytes. The packet is allocated with a new uid (as
258 * returned by getUid).
259 *
260 * \param size the size of the zero-filled payload
261 */
262 Packet (uint32_t size);
263 /**
264 * \brief Create a new packet from the serialized buffer.
265 *
266 * This new packet
267 * is identical to the serialized packet contained in the buffer
268 * and is magically deserialized for you
269 *
270 * \param buffer the serialized packet to be created
271 * \param size the size of the packet for deserialization
272 * \param magic allows packet deserialization;
273 * asserts when set to false
274 */
275 Packet (uint8_t const*buffer, uint32_t size, bool magic);
276 /**
277 * \brief Create a packet with payload filled with the content
278 * of this buffer.
279 *
280 * The input data is copied: the input
281 * buffer is untouched.
282 *
283 * \param buffer the data to store in the packet.
284 * \param size the size of the input buffer.
285 */
286 Packet (uint8_t const*buffer, uint32_t size);
287 /**
288 * \brief Create a new packet which contains a fragment of the original
289 * packet.
290 *
291 * The returned packet shares the same uid as this packet.
292 *
293 * \param start offset from start of packet to start of fragment to create
294 * \param length length of fragment to create
295 * \returns a fragment of the original packet
296 */
297 Ptr<Packet> CreateFragment (uint32_t start, uint32_t length) const;
298 /**
299 * \brief Returns the the size in bytes of the packet (including the zero-filled
300 * initial payload).
301 *
302 * \returns the size in bytes of the packet
303 */
304 inline uint32_t GetSize (void) const;
305 /**
306 * \brief Add header to this packet.
307 *
308 * This method invokes the
309 * Header::GetSerializedSize and Header::Serialize
310 * methods to reserve space in the buffer and request the
311 * header to serialize itself in the packet buffer.
312 *
313 * \param header a reference to the header to add to this packet.
314 */
315 void AddHeader (const Header & header);
316 /**
317 * \brief Deserialize and remove the header from the internal buffer.
318 *
319 * This method invokes Header::Deserialize (begin) and should be used for
320 * fixed-length headers.
321 *
322 * \param header a reference to the header to remove from the internal buffer.
323 * \returns the number of bytes removed from the packet.
324 */
325 uint32_t RemoveHeader (Header &header);
326 /**
327 * \brief Deserialize and remove the header from the internal buffer.
328 *
329 * This method invokes Header::Deserialize (begin, end) and should be
330 * used for variable-length headers (where the size is determined somehow
331 * by the caller).
332 *
333 * \param header a reference to the header to remove from the internal buffer.
334 * \param size number of bytes to deserialize
335 * \returns the number of bytes removed from the packet.
336 */
337 uint32_t RemoveHeader (Header &header, uint32_t size);
338 /**
339 * \brief Deserialize but does _not_ remove the header from the internal buffer.
340 * s
341 * This method invokes Header::Deserialize.
342 *
343 * \param header a reference to the header to read from the internal buffer.
344 * \returns the number of bytes read from the packet.
345 */
346 uint32_t PeekHeader (Header &header) const;
347 /**
348 * \brief Deserialize but does _not_ remove the header from the internal buffer.
349 * s
350 * This method invokes Header::Deserialize (begin, end) and should be used
351 * for variable-length headers (where the size is determined somehow
352 * by the caller).
353 *
354 * \param header a reference to the header to read from the internal buffer.
355 * \param size number of bytes to deserialize
356 * \returns the number of bytes read from the packet.
357 */
358 uint32_t PeekHeader (Header &header, uint32_t size) const;
359 /**
360 * \brief Add trailer to this packet.
361 *
362 * This method invokes the
363 * Trailer::GetSerializedSize and Trailer::Serialize
364 * methods to reserve space in the buffer and request the trailer
365 * to serialize itself in the packet buffer.
366 *
367 * \param trailer a reference to the trailer to add to this packet.
368 */
369 void AddTrailer (const Trailer &trailer);
370 /**
371 * \brief Remove a deserialized trailer from the internal buffer.
372 *
373 * This method invokes the Deserialize method.
374 *
375 * \param trailer a reference to the trailer to remove from the internal buffer.
376 * \returns the number of bytes removed from the end of the packet.
377 */
378 uint32_t RemoveTrailer (Trailer &trailer);
379 /**
380 * \brief Deserialize but does _not_ remove a trailer from the internal buffer.
381 *
382 * This method invokes the Trailer::Deserialize method.
383 *
384 * \param trailer a reference to the trailer to read from the internal buffer.
385 * \returns the number of bytes read from the end of the packet.
386 */
387 uint32_t PeekTrailer (Trailer &trailer);
388
389 /**
390 * \brief Concatenate the input packet at the end of the current
391 * packet.
392 *
393 * This does not alter the uid of either packet.
394 *
395 * \param packet packet to concatenate
396 */
397 void AddAtEnd (Ptr<const Packet> packet);
398 /**
399 * \brief Add a zero-filled padding to the packet.
400 *
401 * \param size number of padding bytes to add.
402 */
403 void AddPaddingAtEnd (uint32_t size);
404 /**
405 * \brief Remove size bytes from the end of the current packet.
406 *
407 * It is safe to remove more bytes than are present in
408 * the packet.
409 *
410 * \param size number of bytes from remove
411 */
412 void RemoveAtEnd (uint32_t size);
413 /**
414 * \brief Remove size bytes from the start of the current packet.
415 *
416 * It is safe to remove more bytes than are present in
417 * the packet.
418 *
419 * \param size number of bytes from remove
420 */
421 void RemoveAtStart (uint32_t size);
422
423 /**
424 * \brief Copy the packet contents to a byte buffer.
425 *
426 * \param buffer a pointer to a byte buffer where the packet data
427 * should be copied.
428 * \param size the size of the byte buffer.
429 * \returns the number of bytes read from the packet
430 *
431 * No more than \b size bytes will be copied by this function.
432 */
433 uint32_t CopyData (uint8_t *buffer, uint32_t size) const;
434
435 /**
436 * \brief Copy the packet contents to an output stream.
437 *
438 * \param os pointer to output stream in which we want
439 * to write the packet data.
440 * \param size the maximum number of bytes we want to write
441 * in the output stream.
442 */
443 void CopyData (std::ostream *os, uint32_t size) const;
444
445 /**
446 * \brief performs a COW copy of the packet.
447 *
448 * \returns a COW copy of the packet.
449 *
450 * The returns packet will behave like an independent copy of
451 * the original packet, even though they both share the
452 * same datasets internally.
453 */
454 Ptr<Packet> Copy (void) const;
455
456 /**
457 * \brief Returns the packet's Uid.
458 *
459 * A packet is allocated a new uid when it is created
460 * empty or with zero-filled payload.
461 *
462 * Note: This uid is an internal uid and cannot be counted on to
463 * provide an accurate counter of how many "simulated packets" of a
464 * particular protocol are in the system. It is not trivial to make
465 * this uid into such a counter, because of questions such as what
466 * should the uid be when the packet is sent over broadcast media, or
467 * when fragmentation occurs. If a user wants to trace actual packet
468 * counts, he or she should look at e.g. the IP ID field or transport
469 * sequence numbers, or other packet or frame counters at other
470 * protocol layers.
471 *
472 * \returns an integer identifier which uniquely
473 * identifies this packet.
474 */
475 uint64_t GetUid (void) const;
476
477 /**
478 * \brief Print the packet contents.
479 *
480 * \param os output stream in which the data should be printed.
481 *
482 * Iterate over the headers and trailers present in this packet,
483 * from the first header to the last trailer and invoke, for
484 * each of them, the user-provided method Header::DoPrint or
485 * Trailer::DoPrint methods.
486 */
487 void Print (std::ostream &os) const;
488
489 /**
490 * \brief Return a string representation of the packet
491 *
492 * An empty string is returned if you haven't called EnablePrinting ()
493 *
494 * \return String representation
495 */
496 std::string ToString (void) const;
497
498 /**
499 * \brief Returns an iterator which points to the first 'item'
500 * stored in this buffer.
501 *
502 * Note that this iterator will point
503 * to an empty array of items if you don't call EnablePrinting
504 * or EnableChecking before.
505 *
506 * \returns an iterator
507 *
508 * \sa EnablePrinting EnableChecking
509 */
510 PacketMetadata::ItemIterator BeginItem (void) const;
511
512 /**
513 * \brief Enable printing packets metadata.
514 *
515 * By default, packets do not keep around enough metadata to
516 * perform the operations requested by the Print methods. If you
517 * want to be able the Packet::Print method,
518 * you need to invoke this method at least once during the
519 * simulation setup and before any packet is created.
520 */
521 static void EnablePrinting (void);
522 /**
523 * \brief Enable packets metadata checking.
524 *
525 * The packet metadata is also used to perform extensive
526 * sanity checks at runtime when performing operations on a
527 * Packet. For example, this metadata is used to verify that
528 * when you remove a header from a packet, this same header
529 * was actually present at the front of the packet. These
530 * errors will be detected and will abort the program.
531 */
532 static void EnableChecking (void);
533
534 /**
535 * \brief Returns number of bytes required for packet
536 * serialization.
537 *
538 * \returns number of bytes required for packet
539 * serialization
540 *
541 * For packet serialization, the total size is checked
542 * in order to determine the size of the buffer
543 * required for serialization
544 */
545 uint32_t GetSerializedSize (void) const;
546
547 /**
548 * \brief Serialize a packet, tags, and metadata into a byte buffer.
549 *
550 * \param buffer a raw byte buffer to which the packet will be serialized
551 * \param maxSize the max size of the buffer for bounds checking
552 *
553 * \returns one if all data were serialized, zero if buffer size was too small.
554 */
555 uint32_t Serialize (uint8_t* buffer, uint32_t maxSize) const;
556
557 /**
558 * \brief Tag each byte included in this packet with a new byte tag.
559 *
560 * \param tag the new tag to add to this packet
561 *
562 * Note that adding a tag is a const operation which is pretty
563 * un-intuitive. The rationale is that the content and behavior of
564 * a packet is _not_ changed when a tag is added to a packet: any
565 * code which was not aware of the new tag is going to work just
566 * the same if the new tag is added. The real reason why adding a
567 * tag was made a const operation is to allow a trace sink which gets
568 * a packet to tag the packet, even if the packet is const (and most
569 * trace sources should use const packets because it would be
570 * totally evil to allow a trace sink to modify the content of a
571 * packet).
572 */
573 void AddByteTag (const Tag &tag) const;
574
575 /**
576 * \brief Tag the indicated byte range of this packet with a new byte tag.
577 *
578 * As parameters for this method, we do not use indexes, but byte position.
579 * Moreover, as there is no 0-th position, the first position is 1.
580 *
581 * As example, if you want to tag the first 10 bytes, you have to call
582 * the method in this way:
583 *
584 * \code{.cpp}
585 Ptr<Packet> p = ... ;
586 SomeTag tag;
587 p->AddByteTag (tag, 1, 10);
588 \endcode
589 *
590 * \param tag the new tag to add to this packet
591 * \param start the position of the first byte tagged by this tag
592 * \param end the position of the last byte tagged by this tag
593 */
594 void AddByteTag (const Tag &tag, uint32_t start, uint32_t end) const;
595 /**
596 * \brief Returns an iterator over the set of byte tags included in this packet
597 *
598 * \returns an iterator over the set of byte tags included in this packet.
599 */
600 ByteTagIterator GetByteTagIterator (void) const;
601 /**
602 * \brief Finds the first tag matching the parameter Tag type
603 *
604 * \param tag the byte tag type to search in this packet
605 * \returns true if the requested tag type was found, false otherwise.
606 *
607 * If the requested tag type is found, it is copied in the user's
608 * provided tag instance.
609 */
610 bool FindFirstMatchingByteTag (Tag &tag) const;
611
612 /**
613 * \brief Remove all byte tags stored in this packet.
614 */
615 void RemoveAllByteTags (void);
616
617 /**
618 * \param os output stream in which the data should be printed.
619 *
620 * \brief Iterate over the byte tags present in this packet, and
621 * invoke the Print method of each tag stored in the packet.
622 */
623 void PrintByteTags (std::ostream &os) const;
624
625 /**
626 * \brief Add a packet tag.
627 *
628 * \param tag the packet tag type to add.
629 *
630 * Note that this method is const, that is, it does not
631 * modify the state of this packet, which is fairly
632 * un-intuitive. See AddByteTag"()" discussion.
633 */
634 void AddPacketTag (const Tag &tag) const;
635 /**
636 * \brief Remove a packet tag.
637 *
638 * \param tag the packet tag type to remove from this packet.
639 * The tag parameter is set to the value of the tag found.
640 * \returns true if the requested tag is found, false
641 * otherwise.
642 */
643 bool RemovePacketTag (Tag &tag);
644 /**
645 * \brief Replace the value of a packet tag.
646 *
647 * \param tag the packet tag type to replace. To get the old
648 * value of the tag, use PeekPacketTag first.
649 * \returns true if the requested tag is found, false otherwise.
650 * If the tag isn't found, Add is performed instead (so
651 * the packet is guaranteed to have the new tag value
652 * either way).
653 */
654 bool ReplacePacketTag (Tag & tag);
655 /**
656 * \brief Search a matching tag and call Tag::Deserialize if it is found.
657 *
658 * \param tag the tag to search in this packet
659 * \returns true if the requested tag is found, false
660 * otherwise.
661 */
662 bool PeekPacketTag (Tag &tag) const;
663 /**
664 * \brief Remove all packet tags.
665 */
666 void RemoveAllPacketTags (void);
667
668 /**
669 * \brief Print the list of packet tags.
670 *
671 * \param os the stream on which to print the tags.
672 *
673 * \sa Packet::AddPacketTag, Packet::RemovePacketTag, Packet::PeekPacketTag,
674 * Packet::RemoveAllPacketTags
675 */
676 void PrintPacketTags (std::ostream &os) const;
677
678 /**
679 * \brief Returns an object which can be used to iterate over the list of
680 * packet tags.
681 *
682 * \returns an object which can be used to iterate over the list of
683 * packet tags.
684 */
685 PacketTagIterator GetPacketTagIterator (void) const;
686
687 /**
688 * \brief Set the packet nix-vector.
689 *
690 * Note: This function supports a temporary solution
691 * to a specific problem in this generic class, i.e.
692 * how to associate something specific like nix-vector
693 * with a packet. This design methodology
694 * should _not_ be followed, and is only here as an
695 * impetus to fix this general issue.
696 *
697 * \param nixVector the nix vector
698 */
699 void SetNixVector (Ptr<NixVector> nixVector);
700 /**
701 * \brief Get the packet nix-vector.
702 *
703 * See the comment on SetNixVector
704 *
705 * \returns the Nix vector
706 */
707 Ptr<NixVector> GetNixVector (void) const;
708
709 /**
710 * TracedCallback signature for Ptr<Packet>
711 *
712 * \param [in] packet The packet.
713 */
714 typedef void (* TracedCallback) (Ptr<const Packet> packet);
715
716 /**
717 * TracedCallback signature for packet and Address.
718 *
719 * \param [in] packet The packet.
720 * \param [in] address The address.
721 */
722 typedef void (* AddressTracedCallback)
723 (Ptr<const Packet> packet, const Address &address);
724
725 /**
726 * TracedCallback signature for packet and source/destination addresses.
727 *
728 * \param [in] packet The packet.
729 * \param [in] srcAddress The source address.
730 * \param [in] destAddress The destination address.
731 */
732 typedef void (* TwoAddressTracedCallback)
733 (const Ptr<const Packet> packet, const Address &srcAddress, const Address &destAddress);
734
735 /**
736 * TracedCallback signature for packet and Mac48Address.
737 *
738 * \param [in] packet The packet.
739 * \param [in] mac The Mac48Address.
740 */
741 typedef void (* Mac48AddressTracedCallback)
742 (Ptr<const Packet> packet, Mac48Address mac);
743
744 /**
745 * TracedCallback signature for changes in packet size.
746 *
747 * \param [in] oldSize The previous packet's size.
748 * \param [in] newSize The actual packet's size.
749 */
750 typedef void (* SizeTracedCallback)
751 (uint32_t oldSize, uint32_t newSize);
752
753 /**
754 * TracedCallback signature for packet and SINR.
755 *
756 * \param [in] packet The packet.
757 * \param [in] sinr The received SINR.
758 */
759 typedef void (* SinrTracedCallback)
760 (Ptr<const Packet> packet, double sinr);
761
762
763 private:
764 /**
765 * \brief Constructor
766 * \param buffer the packet buffer
767 * \param byteTagList the ByteTag list
768 * \param packetTagList the packet's Tag list
769 * \param metadata the packet's metadata
770 */
771 Packet (const Buffer &buffer, const ByteTagList &byteTagList,
772 const PacketTagList &packetTagList, const PacketMetadata &metadata);
773
774 /**
775 * \brief Deserializes a packet.
776 * \param [in] buffer the input buffer.
777 * \param [in] size the buffer size.
778 * \returns the number of deserialized bytes.
779 */
780 uint32_t Deserialize (uint8_t const*buffer, uint32_t size);
781
782 Buffer m_buffer; //!< the packet buffer (it's actual contents)
783 ByteTagList m_byteTagList; //!< the ByteTag list
784 PacketTagList m_packetTagList; //!< the packet's Tag list
785 PacketMetadata m_metadata; //!< the packet's metadata
786
787 /* Please see comments above about nix-vector */
788 Ptr<NixVector> m_nixVector; //!< the packet's Nix vector
789
790 static uint32_t m_globalUid; //!< Global counter of packets Uid
791 };
792
793 /**
794 * \brief Stream insertion operator.
795 *
796 * \param os the stream
797 * \param packet the packet
798 * \returns a reference to the stream
799 */
800 std::ostream& operator<< (std::ostream& os, const Packet &packet);
801
802 /**
803 * \ingroup network
804 * \defgroup packetperf Packet Performance
805 * The current implementation of the byte buffers and tag list is based
806 * on COW (Copy On Write. An introduction to COW can be found in Scott
807 * Meyer's "More Effective C++", items 17 and 29). What this means is that
808 * copying packets without modifying them is very cheap (in terms of cpu
809 * and memory usage) and modifying them can be also very cheap. What is
810 * key for proper COW implementations is being
811 * able to detect when a given modification of the state of a packet triggers
812 * a full copy of the data prior to the modification: COW systems need
813 * to detect when an operation is "dirty".
814 *
815 * Dirty operations:
816 * - ns3::Packet::AddHeader
817 * - ns3::Packet::AddTrailer
818 * - both versions of ns3::Packet::AddAtEnd
819 * - ns3::Packet::RemovePacketTag
820 * - ns3::Packet::ReplacePacketTag
821 *
822 * Non-dirty operations:
823 * - ns3::Packet::AddPacketTag
824 * - ns3::Packet::PeekPacketTag
825 * - ns3::Packet::RemoveAllPacketTags
826 * - ns3::Packet::AddByteTag
827 * - ns3::Packet::FindFirstMatchingByteTag
828 * - ns3::Packet::RemoveAllByteTags
829 * - ns3::Packet::RemoveHeader
830 * - ns3::Packet::RemoveTrailer
831 * - ns3::Packet::CreateFragment
832 * - ns3::Packet::RemoveAtStart
833 * - ns3::Packet::RemoveAtEnd
834 * - ns3::Packet::CopyData
835 *
836 * Dirty operations will always be slower than non-dirty operations,
837 * sometimes by several orders of magnitude. However, even the
838 * dirty operations have been optimized for common use-cases which
839 * means that most of the time, these operations will not trigger
840 * data copies and will thus be still very fast.
841 */
842
843 } // namespace ns3
844
845 /****************************************************
846 * Implementation of inline methods for performance
847 ****************************************************/
848
849 namespace ns3 {
850
851 uint32_t
GetSize(void)852 Packet::GetSize (void) const
853 {
854 return m_buffer.GetSize ();
855 }
856
857 } // namespace ns3
858
859 #endif /* PACKET_H */
860