A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
trace-helper.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2010 University of Washington
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 */
6
7#ifndef TRACE_HELPER_H
8#define TRACE_HELPER_H
9
11#include "node-container.h"
12
13#include "ns3/assert.h"
14#include "ns3/output-stream-wrapper.h"
15#include "ns3/pcap-file-wrapper.h"
16#include "ns3/simulator.h"
17
18namespace ns3
19{
20
21/**
22 * \brief Manage pcap files for device models
23 *
24 * Handling pcap files is a common operation for ns-3 devices. It is useful to
25 * provide a common base class for dealing with these ops.
26 */
27
29{
30 public:
31 /**
32 * This enumeration holds the data link types that will be written to the pcap file.
33 *
34 * We don't include pcap-bpf.h to avoid an explicit dependency on the real pcap
35 * and we don't make an enumeration of all of the values to make it easy to
36 * pass new values in.
37 *
38 * For a list of Data Link Types see http://www.tcpdump.org/linktypes.html
39 */
54
55 /**
56 * @brief Create a pcap helper.
57 */
58 PcapHelper();
59
60 /**
61 * @brief Destroy a pcap helper.
62 */
64
65 /**
66 * @brief Let the pcap helper figure out a reasonable filename to use for a
67 * pcap file associated with a device.
68 *
69 * @param prefix prefix string
70 * @param device NetDevice
71 * @param useObjectNames use node and device names instead of indexes
72 * @returns file name
73 */
74 std::string GetFilenameFromDevice(std::string prefix,
75 Ptr<NetDevice> device,
76 bool useObjectNames = true);
77
78 /**
79 * @brief Let the pcap helper figure out a reasonable filename to use for the
80 * pcap file associated with a node.
81 *
82 * @param prefix prefix string
83 * @param object interface (such as Ipv4Interface or Ipv6Interface)
84 * @param interface interface id
85 * @param useObjectNames use node and device names instead of indexes
86 * @returns file name
87 */
88 std::string GetFilenameFromInterfacePair(std::string prefix,
89 Ptr<Object> object,
90 uint32_t interface,
91 bool useObjectNames = true);
92
93 /**
94 * @brief Create and initialize a pcap file.
95 *
96 * @param filename file name
97 * @param filemode file mode
98 * @param dataLinkType data link type of packet data
99 * @param snapLen maximum length of packet data stored in records
100 * @param tzCorrection time zone correction to be applied to timestamps of packets
101 * @returns a smart pointer to the Pcap file
102 */
103 Ptr<PcapFileWrapper> CreateFile(std::string filename,
104 std::ios::openmode filemode,
105 DataLinkType dataLinkType,
106 uint32_t snapLen = std::numeric_limits<uint32_t>::max(),
107 int32_t tzCorrection = 0);
108 /**
109 * @brief Hook a trace source to the default trace sink
110 *
111 * @param object object
112 * @param traceName trace source name
113 * @param file file wrapper
114 */
115 template <typename T>
116 void HookDefaultSink(Ptr<T> object, std::string traceName, Ptr<PcapFileWrapper> file);
117
118 private:
119 /**
120 * The basic default trace sink.
121 *
122 * This one just writes the packet to the pcap
123 * file which is good enough for most kinds of captures.
124 *
125 * @param file the file to write to
126 * @param p the packet to write
127 */
129
130 /**
131 * This trace sink passes a header separately from the packet to prevent creating a new packet
132 * (for performance reasons)
133 *
134 * @param file the file to write to
135 * @param header header of the packet
136 * @param p the packet to write
137 *
138 * @see DefaultSink
139 */
140 static void SinkWithHeader(Ptr<PcapFileWrapper> file,
141 const Header& header,
143};
144
145template <typename T>
146void
147PcapHelper::HookDefaultSink(Ptr<T> object, std::string tracename, Ptr<PcapFileWrapper> file)
148{
149 bool result =
150 object->TraceConnectWithoutContext(tracename, MakeBoundCallback(&DefaultSink, file));
151 NS_ASSERT_MSG(result == true,
152 "PcapHelper::HookDefaultSink(): Unable to hook \"" << tracename << "\"");
153}
154
155/**
156 * \brief Manage ASCII trace files for device models
157 *
158 * Handling ascii trace files is a common operation for ns-3 devices. It is
159 * useful to provide a common base class for dealing with these ops.
160 */
161
163{
164 public:
165 /**
166 * @brief Create an ascii trace helper.
167 */
169
170 /**
171 * @brief Destroy an ascii trace helper.
172 */
174
175 /**
176 * @brief Let the ascii trace helper figure out a reasonable filename to use
177 * for an ascii trace file associated with a device.
178 *
179 * @param prefix prefix string
180 * @param device NetDevice
181 * @param useObjectNames use node and device names instead of indexes
182 * @returns file name
183 */
184 std::string GetFilenameFromDevice(std::string prefix,
185 Ptr<NetDevice> device,
186 bool useObjectNames = true);
187
188 /**
189 * @brief Let the ascii trace helper figure out a reasonable filename to use
190 * for an ascii trace file associated with a node.
191 *
192 * @param prefix prefix string
193 * @param object interface (such as Ipv4Interface or Ipv6Interface)
194 * @param interface interface id
195 * @param useObjectNames use node and device names instead of indexes
196 * @returns file name
197 */
198 std::string GetFilenameFromInterfacePair(std::string prefix,
199 Ptr<Object> object,
200 uint32_t interface,
201 bool useObjectNames = true);
202
203 /**
204 * @brief Create and initialize an output stream object we'll use to write the
205 * traced bits.
206 *
207 * One of the common issues users run into when trying to use tracing in ns-3
208 * is actually a design decision made in the C++ stream library. It is not
209 * widely known that copy and assignment of iostreams is forbidden by
210 * std::basic_ios<>. This is because it is not possible to predict the
211 * semantics of the stream desired by a user.
212 *
213 * The tempting ns-3 idiom when tracing to a file is to create a bound callback
214 * with an ofstream as the bound object. Unfortunately, this implies a copy
215 * construction in order to get the ofstream object into the callback. This
216 * operation, as mentioned above, is forbidden by the STL. You could use a
217 * global ostream and pass a pointer to it, but that is pretty ugly. You
218 * could create an ostream on the stack and pass a pointer to it, but you may
219 * run into object lifetime issues. Ns-3 has a nice reference counted object
220 * that can solve the problem so we use one of those to carry the stream
221 * around and deal with the lifetime issues.
222 *
223 * @param filename file name
224 * @param filemode file mode
225 * @returns a smart pointer to the output stream
226 */
227 Ptr<OutputStreamWrapper> CreateFileStream(std::string filename,
228 std::ios::openmode filemode = std::ios::out);
229
230 /**
231 * @brief Hook a trace source to the default enqueue operation trace sink that
232 * does not accept nor log a trace context.
233 *
234 * @param object object
235 * @param traceName trace source name
236 * @param stream output stream wrapper
237 */
238 template <typename T>
240 std::string traceName,
242
243 /**
244 * @brief Hook a trace source to the default enqueue operation trace sink that
245 * does accept and log a trace context.
246 *
247 * @param object object
248 * @param context context string
249 * @param traceName trace source name
250 * @param stream output stream wrapper
251 */
252 template <typename T>
254 std::string context,
255 std::string traceName,
257
258 /**
259 * @brief Hook a trace source to the default drop operation trace sink that
260 * does not accept nor log a trace context.
261 *
262 * @param object object
263 * @param traceName trace source name
264 * @param stream output stream wrapper
265 */
266 template <typename T>
268 std::string traceName,
270
271 /**
272 * @brief Hook a trace source to the default drop operation trace sink that
273 * does accept and log a trace context.
274 *
275 * @param object object
276 * @param context context string
277 * @param traceName trace source name
278 * @param stream output stream wrapper
279 */
280 template <typename T>
282 std::string context,
283 std::string traceName,
285
286 /**
287 * @brief Hook a trace source to the default dequeue operation trace sink
288 * that does not accept nor log a trace context.
289 *
290 * @param object object
291 * @param traceName trace source name
292 * @param stream output stream wrapper
293 */
294 template <typename T>
296 std::string traceName,
298
299 /**
300 * @brief Hook a trace source to the default dequeue operation trace sink
301 * that does accept and log a trace context.
302 *
303 * @param object object
304 * @param context context string
305 * @param traceName trace source name
306 * @param stream output stream wrapper
307 */
308 template <typename T>
310 std::string context,
311 std::string traceName,
313
314 /**
315 * @brief Hook a trace source to the default receive operation trace sink
316 * that does not accept nor log a trace context.
317 *
318 * @param object object
319 * @param traceName trace source name
320 * @param stream output stream wrapper
321 */
322 template <typename T>
324 std::string traceName,
326
327 /**
328 * @brief Hook a trace source to the default receive operation trace sink
329 * that does accept and log a trace context.
330 *
331 * @param object object
332 * @param context context string
333 * @param traceName trace source name
334 * @param stream output stream wrapper
335 */
336 template <typename T>
338 std::string context,
339 std::string traceName,
341
342 /**
343 * @brief Basic Enqueue default trace sink.
344 *
345 * When a packet has been sent to a device for transmission, the device is
346 * expected to place the packet onto a transmit queue even if it does not
347 * have to delay the packet at all, if only to trigger this event. This
348 * event will eventually translate into a '+' operation in the trace file.
349 *
350 * This is typically implemented by hooking the "TxQueue/Enqueue" trace hook
351 * in the device (actually the Queue in the device).
352 *
353 * @param file the output file
354 * @param p the packet
355 */
358
359 /**
360 * @brief Basic Enqueue default trace sink.
361 *
362 * When a packet has been sent to a device for transmission, the device is
363 * expected to place the packet onto a transmit queue even if it does not
364 * have to delay the packet at all, if only to trigger this event. This
365 * event will eventually translate into a '+' operation in the trace file.
366 *
367 * This is typically implemented by hooking the "TxQueue/Enqueue" trace hook
368 * in the device (actually the Queue in the device).
369 *
370 * @param file the output file
371 * @param context the context
372 * @param p the packet
373 */
375 std::string context,
377
378 /**
379 * @brief Basic Drop default trace sink.
380 *
381 * When a packet has been sent to a device for transmission, the device is
382 * expected to place the packet onto a transmit queue. If this queue is
383 * full the packet will be dropped. The device is expected to trigger an
384 * event to indicate that an outbound packet is being dropped. This event
385 * will eventually translate into a 'd' operation in the trace file.
386 *
387 * This is typically implemented by hooking the "TxQueue/Drop" trace hook
388 * in the device (actually the Queue in the device).
389 *
390 * @param file the output file
391 * @param p the packet
392 */
394
395 /**
396 * @brief Basic Drop default trace sink.
397 *
398 * When a packet has been sent to a device for transmission, the device is
399 * expected to place the packet onto a transmit queue. If this queue is
400 * full the packet will be dropped. The device is expected to trigger an
401 * event to indicate that an outbound packet is being dropped. This event
402 * will eventually translate into a 'd' operation in the trace file.
403 *
404 * This is typically implemented by hooking the "TxQueue/Drop" trace hook
405 * in the device (actually the Queue in the device).
406 *
407 * @param file the output file
408 * @param context the context
409 * @param p the packet
410 */
412 std::string context,
414
415 /**
416 * @brief Basic Dequeue default trace sink.
417 *
418 * When a packet has been sent to a device for transmission, the device is
419 * expected to place the packet onto a transmit queue even if it does not
420 * have to delay the packet at all. The device removes the packet from the
421 * transmit queue when the packet is ready to send, and this dequeue will
422 * fire a corresponding event. This event will eventually translate into a
423 * '-' operation in the trace file.
424 *
425 * This is typically implemented by hooking the "TxQueue/Dequeue" trace hook
426 * in the device (actually the Queue in the device).
427 *
428 * @param file the output file
429 * @param p the packet
430 */
433
434 /**
435 * @brief Basic Dequeue default trace sink.
436 *
437 * When a packet has been sent to a device for transmission, the device is
438 * expected to place the packet onto a transmit queue even if it does not
439 * have to delay the packet at all. The device removes the packet from the
440 * transmit queue when the packet is ready to send, and this dequeue will
441 * fire a corresponding event. This event will eventually translate into a
442 * '-' operation in the trace file.
443 *
444 * This is typically implemented by hooking the "TxQueue/Dequeue" trace hook
445 * in the device (actually the Queue in the device).
446 *
447 * @param file the output file
448 * @param context the context
449 * @param p the packet
450 */
452 std::string context,
454
455 /**
456 * @brief Basic Receive default trace sink.
457 *
458 * When a packet is received by a device for transmission, the device is
459 * expected to trigger this event to indicate the reception has occurred.
460 * This event will eventually translate into an 'r' operation in the trace
461 * file.
462 *
463 * This is typically implemented by hooking the "MacRx" trace hook in the
464 * device.
465 *
466 * @param file the output file
467 * @param p the packet
468 */
471
472 /**
473 * @brief Basic Receive default trace sink.
474 *
475 * When a packet is received by a device for transmission, the device is
476 * expected to trigger this event to indicate the reception has occurred.
477 * This event will eventually translate into an 'r' operation in the trace
478 * file.
479 *
480 * This is typically implemented by hooking the "MacRx" trace hook in the
481 * device.
482 *
483 * @param file the output file
484 * @param context the context
485 * @param p the packet
486 */
488 std::string context,
490};
491
492template <typename T>
493void
495 std::string tracename,
497{
498 bool result = object->TraceConnectWithoutContext(
499 tracename,
501 NS_ASSERT_MSG(result == true,
502 "AsciiTraceHelper::HookDefaultEnqueueSinkWithoutContext(): Unable to hook \""
503 << tracename << "\"");
504}
505
506template <typename T>
507void
509 std::string context,
510 std::string tracename,
512{
513 bool result = object->TraceConnect(tracename,
514 context,
516 NS_ASSERT_MSG(result == true,
517 "AsciiTraceHelper::HookDefaultEnqueueSinkWithContext(): Unable to hook \""
518 << tracename << "\"");
519}
520
521template <typename T>
522void
524 std::string tracename,
526{
527 bool result =
528 object->TraceConnectWithoutContext(tracename,
530 NS_ASSERT_MSG(result == true,
531 "AsciiTraceHelper::HookDefaultDropSinkWithoutContext(): Unable to hook \""
532 << tracename << "\"");
533}
534
535template <typename T>
536void
538 std::string context,
539 std::string tracename,
541{
542 bool result = object->TraceConnect(tracename,
543 context,
545 NS_ASSERT_MSG(result == true,
546 "AsciiTraceHelper::HookDefaultDropSinkWithContext(): Unable to hook \""
547 << tracename << "\"");
548}
549
550template <typename T>
551void
553 std::string tracename,
555{
556 bool result = object->TraceConnectWithoutContext(
557 tracename,
559 NS_ASSERT_MSG(result == true,
560 "AsciiTraceHelper::HookDefaultDequeueSinkWithoutContext(): Unable to hook \""
561 << tracename << "\"");
562}
563
564template <typename T>
565void
567 std::string context,
568 std::string tracename,
570{
571 bool result = object->TraceConnect(tracename,
572 context,
574 NS_ASSERT_MSG(result == true,
575 "AsciiTraceHelper::HookDefaultDequeueSinkWithContext(): Unable to hook \""
576 << tracename << "\"");
577}
578
579template <typename T>
580void
582 std::string tracename,
584{
585 bool result = object->TraceConnectWithoutContext(
586 tracename,
588 NS_ASSERT_MSG(result == true,
589 "AsciiTraceHelper::HookDefaultReceiveSinkWithoutContext(): Unable to hook \""
590 << tracename << "\"");
591}
592
593template <typename T>
594void
596 std::string context,
597 std::string tracename,
599{
600 bool result = object->TraceConnect(tracename,
601 context,
603 NS_ASSERT_MSG(result == true,
604 "AsciiTraceHelper::HookDefaultReceiveSinkWithContext(): Unable to hook \""
605 << tracename << "\"");
606}
607
608/**
609 * \brief Base class providing common user-level pcap operations for helpers
610 * representing net devices.
611 */
613{
614 public:
615 /**
616 * @brief Construct a PcapHelperForDevice
617 */
619 {
620 }
621
622 /**
623 * @brief Destroy a PcapHelperForDevice
624 */
626 {
627 }
628
629 /**
630 * @brief Enable pcap output the indicated net device.
631 *
632 * @param prefix Filename prefix to use for pcap files.
633 * @param nd Net device for which you want to enable tracing.
634 * @param promiscuous If true capture all possible packets available at the device.
635 * @param explicitFilename Treat the prefix as an explicit filename if true
636 */
637 virtual void EnablePcapInternal(std::string prefix,
639 bool promiscuous,
640 bool explicitFilename) = 0;
641
642 /**
643 * @brief Enable pcap output the indicated net device.
644 *
645 * @param prefix Filename prefix to use for pcap files.
646 * @param nd Net device for which you want to enable tracing.
647 * @param promiscuous If true capture all possible packets available at the device.
648 * @param explicitFilename Treat the prefix as an explicit filename if true
649 */
650 void EnablePcap(std::string prefix,
652 bool promiscuous = false,
653 bool explicitFilename = false);
654
655 /**
656 * @brief Enable pcap output the indicated net device using a device previously
657 * named using the ns-3 object name service.
658 *
659 * @param prefix filename prefix to use for pcap files.
660 * @param ndName The name of the net device in which you want to enable tracing.
661 * @param promiscuous If true capture all possible packets available at the device.
662 * @param explicitFilename Treat the prefix as an explicit filename if true
663 */
664 void EnablePcap(std::string prefix,
665 std::string ndName,
666 bool promiscuous = false,
667 bool explicitFilename = false);
668
669 /**
670 * @brief Enable pcap output on each device in the container which is of the
671 * appropriate type.
672 *
673 * @param prefix Filename prefix to use for pcap files.
674 * @param d container of devices of type ns3::CsmaNetDevice
675 * @param promiscuous If true capture all possible packets available at the device.
676 */
677 void EnablePcap(std::string prefix, NetDeviceContainer d, bool promiscuous = false);
678
679 /**
680 * @brief Enable pcap output on each device (which is of the appropriate type)
681 * in the nodes provided in the container.
682 *
683 * \param prefix Filename prefix to use for pcap files.
684 * \param n container of nodes.
685 * \param promiscuous If true capture all possible packets available at the device.
686 */
687 void EnablePcap(std::string prefix, NodeContainer n, bool promiscuous = false);
688
689 /**
690 * @brief Enable pcap output on the device specified by a global node-id (of
691 * a previously created node) and associated device-id.
692 *
693 * @param prefix Filename prefix to use for pcap files.
694 * @param nodeid the node id
695 * @param deviceid the device id
696 * @param promiscuous If true capture all possible packets available at the device.
697 */
698 void EnablePcap(std::string prefix,
699 uint32_t nodeid,
700 uint32_t deviceid,
701 bool promiscuous = false);
702
703 /**
704 * @brief Enable pcap output on each device (which is of the appropriate type)
705 * in the set of all nodes created in the simulation.
706 *
707 * @param prefix Filename prefix to use for pcap files.
708 * @param promiscuous If true capture all possible packets available at the device.
709 */
710 void EnablePcapAll(std::string prefix, bool promiscuous = false);
711};
712
713/**
714 * \brief Base class providing common user-level ascii trace operations for helpers
715 * representing net devices.
716 */
718{
719 public:
720 /**
721 * @brief Construct an AsciiTraceHelperForDevice.
722 */
726
727 /**
728 * @brief Destroy an AsciiTraceHelperForDevice.
729 */
731 {
732 }
733
734 /**
735 * @brief Enable ascii trace output on the indicated net device.
736 *
737 * The implementation is expected to use a provided Ptr<OutputStreamWrapper>
738 * if it is non-null. If the OutputStreamWrapper is null, the implementation
739 * is expected to use a provided prefix to construct a new file name for
740 * each net device using the rules described in the class overview.
741 *
742 * If the prefix is provided, there will be one file per net device created.
743 * In this case, adding a trace context to the file would be pointless, so
744 * the device implementation is expected to TraceConnectWithoutContext.
745 *
746 * If the output stream object is provided, there may be many different
747 * devices writing to a single file. In this case, the device adding a
748 * trace context could be important, so the device implementation is
749 * expected to TraceConnect.
750 *
751 * @param stream An OutputStreamWrapper representing an existing file to use
752 * when writing trace data.
753 * @param prefix Filename prefix to use for ascii trace files.
754 * @param nd Net device for which you want to enable tracing
755 * @param explicitFilename Treat the prefix as an explicit filename if true
756 */
758 std::string prefix,
760 bool explicitFilename) = 0;
761
762 /**
763 * @brief Enable ascii trace output on the indicated net device.
764 *
765 * @param prefix Filename prefix to use for ascii files.
766 * @param nd Net device for which you want to enable tracing.
767 * @param explicitFilename Treat the prefix as an explicit filename if true
768 */
769 void EnableAscii(std::string prefix, Ptr<NetDevice> nd, bool explicitFilename = false);
770
771 /**
772 * @brief Enable ascii trace output on the indicated net device.
773 *
774 * @param stream An OutputStreamWrapper representing an existing file to use
775 * when writing trace data.
776 * @param nd Net device for which you want to enable tracing.
777 */
779
780 /**
781 * @brief Enable ascii trace output the indicated net device using a device
782 * previously named using the ns-3 object name service.
783 *
784 * @param prefix filename prefix to use for ascii files.
785 * @param ndName The name of the net device in which you want to enable tracing.
786 * @param explicitFilename Treat the prefix as an explicit filename if true
787 */
788 void EnableAscii(std::string prefix, std::string ndName, bool explicitFilename = false);
789
790 /**
791 * @brief Enable ascii trace output the indicated net device using a device
792 * previously named using the ns-3 object name service.
793 *
794 * @param stream An OutputStreamWrapper representing an existing file to use
795 * when writing trace data.
796 * @param ndName The name of the net device in which you want to enable tracing.
797 */
798 void EnableAscii(Ptr<OutputStreamWrapper> stream, std::string ndName);
799
800 /**
801 * @brief Enable ascii trace output on each device in the container which is
802 * of the appropriate type.
803 *
804 * @param prefix Filename prefix to use for ascii files.
805 * @param d container of devices
806 */
807 void EnableAscii(std::string prefix, NetDeviceContainer d);
808
809 /**
810 * @brief Enable ascii trace output on each device in the container which is
811 * of the appropriate type.
812 *
813 * @param stream An OutputStreamWrapper representing an existing file to use
814 * when writing trace data.
815 * @param d container of devices
816 */
818
819 /**
820 * @brief Enable ascii trace output on each device (which is of the
821 * appropriate type) in the nodes provided in the container.
822 *
823 * \param prefix Filename prefix to use for ascii files.
824 * \param n container of nodes.
825 */
826 void EnableAscii(std::string prefix, NodeContainer n);
827
828 /**
829 * @brief Enable ascii trace output on each device (which is of the
830 * appropriate type) in the nodes provided in the container.
831 *
832 * @param stream An OutputStreamWrapper representing an existing file to use
833 * when writing trace data.
834 * \param n container of nodes.
835 */
837
838 /**
839 * @brief Enable ascii trace output on each device (which is of the
840 * appropriate type) in the set of all nodes created in the simulation.
841 *
842 * @param prefix Filename prefix to use for ascii files.
843 */
844 void EnableAsciiAll(std::string prefix);
845
846 /**
847 * @brief Enable ascii trace output on each device (which is of the
848 * appropriate type) in the set of all nodes created in the simulation.
849 *
850 * @param stream An OutputStreamWrapper representing an existing file to use
851 * when writing trace data.
852 */
854
855 /**
856 * @brief Enable ascii trace output on the device specified by a global
857 * node-id (of a previously created node) and associated device-id.
858 *
859 * @param prefix Filename prefix to use when creating ascii trace files
860 * @param nodeid The node identifier/number of the node on which to enable
861 * ascii tracing
862 * @param deviceid The device identifier/index of the device on which to enable
863 * ascii tracing
864 * @param explicitFilename Treat the prefix as an explicit filename if true
865 */
866 void EnableAscii(std::string prefix, uint32_t nodeid, uint32_t deviceid, bool explicitFilename);
867
868 /**
869 * @brief Enable ascii trace output on the device specified by a global
870 * node-id (of a previously created node) and associated device-id.
871 *
872 * @param stream An OutputStreamWrapper representing an existing file to use
873 * when writing trace data.
874 * @param nodeid The node identifier/number of the node on which to enable
875 * ascii tracing
876 * @param deviceid The device identifier/index of the device on which to enable
877 * ascii tracing
878 */
879 void EnableAscii(Ptr<OutputStreamWrapper> stream, uint32_t nodeid, uint32_t deviceid);
880
881 private:
882 /**
883 * @brief Enable ascii trace output on the device specified by a global
884 * node-id (of a previously created node) and associated device-id (implementation)
885 *
886 * @param stream An OutputStreamWrapper representing an existing file to use
887 * when writing trace data.
888 * @param prefix Filename prefix to use for ascii trace files.
889 * @param nodeid The node identifier/number of the node on which to enable
890 * ascii tracing
891 * @param deviceid The device identifier/index of the device on which to enable
892 * ascii tracing
893 * @param explicitFilename Treat the prefix as an explicit filename if true
894 */
895
897 std::string prefix,
898 uint32_t nodeid,
899 uint32_t deviceid,
900 bool explicitFilename);
901
902 /**
903 * @brief Enable ascii trace output on each device (which is of the
904 * appropriate type) in the nodes provided in the container (implementation).
905 *
906 * @param stream An OutputStreamWrapper representing an existing file to use
907 * when writing trace data.
908 * @param prefix Filename prefix to use for ascii files.
909 * @param n container of nodes.
910 */
911 void EnableAsciiImpl(Ptr<OutputStreamWrapper> stream, std::string prefix, NodeContainer n);
912
913 /**
914 * @brief Enable ascii trace output on each device in the container which is
915 * of the appropriate type (implementation).
916 *
917 * @param stream An OutputStreamWrapper representing an existing file to use
918 * when writing trace data.
919 * @param prefix Filename prefix to use for ascii files.
920 * @param d container of devices
921 */
922 void EnableAsciiImpl(Ptr<OutputStreamWrapper> stream, std::string prefix, NetDeviceContainer d);
923
924 /**
925 * @brief Enable ascii trace output the indicated net device using a device
926 * previously named using the ns-3 object name service (implementation).
927 *
928 * @param stream An OutputStreamWrapper representing an existing file to use
929 * when writing trace data.
930 * @param prefix filename prefix to use for ascii files.
931 * @param ndName The name of the net device in which you want to enable tracing.
932 * @param explicitFilename Treat the prefix as an explicit filename if true
933 */
935 std::string prefix,
936 std::string ndName,
937 bool explicitFilename);
938
939 /**
940 * @brief Enable ascii trace output the indicated net device (implementation).
941 *
942 * @param stream An OutputStreamWrapper representing an existing file to use
943 * when writing trace data.
944 * @param prefix filename prefix to use for ascii files.
945 * @param nd Net device for which you want to enable tracing
946 * @param explicitFilename Treat the prefix as an explicit filename if true
947 */
949 std::string prefix,
951 bool explicitFilename);
952};
953
954} // namespace ns3
955
956#endif /* TRACE_HELPER_H */
Base class providing common user-level ascii trace operations for helpers representing net devices.
virtual ~AsciiTraceHelperForDevice()
Destroy an AsciiTraceHelperForDevice.
void EnableAsciiImpl(Ptr< OutputStreamWrapper > stream, std::string prefix, uint32_t nodeid, uint32_t deviceid, bool explicitFilename)
Enable ascii trace output on the device specified by a global node-id (of a previously created node) ...
void EnableAscii(std::string prefix, Ptr< NetDevice > nd, bool explicitFilename=false)
Enable ascii trace output on the indicated net device.
void EnableAsciiAll(std::string prefix)
Enable ascii trace output on each device (which is of the appropriate type) in the set of all nodes c...
AsciiTraceHelperForDevice()
Construct an AsciiTraceHelperForDevice.
virtual void EnableAsciiInternal(Ptr< OutputStreamWrapper > stream, std::string prefix, Ptr< NetDevice > nd, bool explicitFilename)=0
Enable ascii trace output on the indicated net device.
void EnableAsciiImpl(Ptr< OutputStreamWrapper > stream, std::string prefix, Ptr< NetDevice > nd, bool explicitFilename)
Enable ascii trace output the indicated net device (implementation).
Manage ASCII trace files for device models.
void HookDefaultDropSinkWithoutContext(Ptr< T > object, std::string traceName, Ptr< OutputStreamWrapper > stream)
Hook a trace source to the default drop operation trace sink that does not accept nor log a trace con...
std::string GetFilenameFromDevice(std::string prefix, Ptr< NetDevice > device, bool useObjectNames=true)
Let the ascii trace helper figure out a reasonable filename to use for an ascii trace file associated...
static void DefaultDropSinkWithContext(Ptr< OutputStreamWrapper > file, std::string context, Ptr< const Packet > p)
Basic Drop default trace sink.
std::string GetFilenameFromInterfacePair(std::string prefix, Ptr< Object > object, uint32_t interface, bool useObjectNames=true)
Let the ascii trace helper figure out a reasonable filename to use for an ascii trace file associated...
static void DefaultReceiveSinkWithContext(Ptr< OutputStreamWrapper > file, std::string context, Ptr< const Packet > p)
Basic Receive default trace sink.
void HookDefaultDequeueSinkWithContext(Ptr< T > object, std::string context, std::string traceName, Ptr< OutputStreamWrapper > stream)
Hook a trace source to the default dequeue operation trace sink that does accept and log a trace cont...
Ptr< OutputStreamWrapper > CreateFileStream(std::string filename, std::ios::openmode filemode=std::ios::out)
Create and initialize an output stream object we'll use to write the traced bits.
void HookDefaultEnqueueSinkWithoutContext(Ptr< T > object, std::string traceName, Ptr< OutputStreamWrapper > stream)
Hook a trace source to the default enqueue operation trace sink that does not accept nor log a trace ...
void HookDefaultEnqueueSinkWithContext(Ptr< T > object, std::string context, std::string traceName, Ptr< OutputStreamWrapper > stream)
Hook a trace source to the default enqueue operation trace sink that does accept and log a trace cont...
void HookDefaultReceiveSinkWithContext(Ptr< T > object, std::string context, std::string traceName, Ptr< OutputStreamWrapper > stream)
Hook a trace source to the default receive operation trace sink that does accept and log a trace cont...
void HookDefaultReceiveSinkWithoutContext(Ptr< T > object, std::string traceName, Ptr< OutputStreamWrapper > stream)
Hook a trace source to the default receive operation trace sink that does not accept nor log a trace ...
AsciiTraceHelper()
Create an ascii trace helper.
static void DefaultDequeueSinkWithoutContext(Ptr< OutputStreamWrapper > file, Ptr< const Packet > p)
Basic Dequeue default trace sink.
static void DefaultEnqueueSinkWithContext(Ptr< OutputStreamWrapper > file, std::string context, Ptr< const Packet > p)
Basic Enqueue default trace sink.
void HookDefaultDequeueSinkWithoutContext(Ptr< T > object, std::string traceName, Ptr< OutputStreamWrapper > stream)
Hook a trace source to the default dequeue operation trace sink that does not accept nor log a trace ...
void HookDefaultDropSinkWithContext(Ptr< T > object, std::string context, std::string traceName, Ptr< OutputStreamWrapper > stream)
Hook a trace source to the default drop operation trace sink that does accept and log a trace context...
static void DefaultDropSinkWithoutContext(Ptr< OutputStreamWrapper > file, Ptr< const Packet > p)
Basic Drop default trace sink.
static void DefaultDequeueSinkWithContext(Ptr< OutputStreamWrapper > file, std::string context, Ptr< const Packet > p)
Basic Dequeue default trace sink.
static void DefaultEnqueueSinkWithoutContext(Ptr< OutputStreamWrapper > file, Ptr< const Packet > p)
Basic Enqueue default trace sink.
~AsciiTraceHelper()
Destroy an ascii trace helper.
static void DefaultReceiveSinkWithoutContext(Ptr< OutputStreamWrapper > file, Ptr< const Packet > p)
Basic Receive default trace sink.
Protocol header serialization and deserialization.
Definition header.h:33
holds a vector of ns3::NetDevice pointers
keep track of a set of node pointers.
Base class providing common user-level pcap operations for helpers representing net devices.
void EnablePcapAll(std::string prefix, bool promiscuous=false)
Enable pcap output on each device (which is of the appropriate type) in the set of all nodes created ...
void EnablePcap(std::string prefix, Ptr< NetDevice > nd, bool promiscuous=false, bool explicitFilename=false)
Enable pcap output the indicated net device.
virtual void EnablePcapInternal(std::string prefix, Ptr< NetDevice > nd, bool promiscuous, bool explicitFilename)=0
Enable pcap output the indicated net device.
virtual ~PcapHelperForDevice()
Destroy a PcapHelperForDevice.
PcapHelperForDevice()
Construct a PcapHelperForDevice.
Manage pcap files for device models.
std::string GetFilenameFromDevice(std::string prefix, Ptr< NetDevice > device, bool useObjectNames=true)
Let the pcap helper figure out a reasonable filename to use for a pcap file associated with a device.
Ptr< PcapFileWrapper > CreateFile(std::string filename, std::ios::openmode filemode, DataLinkType dataLinkType, uint32_t snapLen=std::numeric_limits< uint32_t >::max(), int32_t tzCorrection=0)
Create and initialize a pcap file.
DataLinkType
This enumeration holds the data link types that will be written to the pcap file.
static void SinkWithHeader(Ptr< PcapFileWrapper > file, const Header &header, Ptr< const Packet > p)
This trace sink passes a header separately from the packet to prevent creating a new packet (for perf...
void HookDefaultSink(Ptr< T > object, std::string traceName, Ptr< PcapFileWrapper > file)
Hook a trace source to the default trace sink.
std::string GetFilenameFromInterfacePair(std::string prefix, Ptr< Object > object, uint32_t interface, bool useObjectNames=true)
Let the pcap helper figure out a reasonable filename to use for the pcap file associated with a node.
~PcapHelper()
Destroy a pcap helper.
static void DefaultSink(Ptr< PcapFileWrapper > file, Ptr< const Packet > p)
The basic default trace sink.
PcapHelper()
Create a pcap helper.
Smart pointer class similar to boost::intrusive_ptr.
#define NS_ASSERT_MSG(condition, message)
At runtime, in debugging builds, if this condition is not true, the program prints the message to out...
Definition assert.h:75
auto MakeBoundCallback(R(*fnPtr)(Args...), BArgs &&... bargs)
Make Callbacks with varying number of bound arguments.
Definition callback.h:745
Every class exported by the ns3 library is enclosed in the ns3 namespace.