dfx::Pcapng::Capture Class Reference

PCAPNG capture hook for dfx message traffic. More...

#include <dfx-pcapng/Capture.hpp>

Inheritance diagram for dfx::Pcapng::Capture:

Collaboration diagram for dfx::Pcapng::Capture:

Public Member Functions
	Capture (bool getHwAndOsInfo=true)
	Construct a capture hook.
	~Capture ()
	Destroy the capture hook and stop background capture work.
template<typename ... Args>
void	setFileSink (Args &&... args)
	Enable file output using a FileSink.
void	unsetFileSink ()
	Disable the file sink if enabled.
template<typename ... Args>
void	setPipeSink (Args &&... args)
	Enable pipe output using a PipeSink.
void	unsetPipeSink ()
	Disable the pipe sink if enabled.
template<typename ... Args>
void	setTcpSink (Args &&... args)
	Enable TCP output using a TcpSink.
void	unsetTcpSink ()
	Disable the TCP sink if enabled.
void	setUserAppInfo (std::string info)
	Set application-specific information to embed in the capture.
void	onMessageSent (Core::OutputPort const &port, Core::Message const &message) override
	Port hook: called when a message is sent from an output port.
void	onMessageReceived (Core::InputPort const &port, Core::Message const &message) override
	Port hook: called when a message is received by an input port.
void	onNodeCreated (Core::NodePtr node) override
	Graph hook: called when a node is created.
void	onNodeRemoved (Core::NodePtr node) override
	Graph hook: called when a node is removed.
void	onChannelCreated (Core::ChannelPtr) override
	Graph hook: channel creation is currently ignored for capture.
void	onChannelRemoved (Core::ChannelPtr) override
	Graph hook: channel removal is currently ignored for capture.

Detailed Description

PCAPNG capture hook for dfx message traffic.

Capture is a runtime hook object that can be attached to a dfx graph to export message activity to PCAPNG (Wireshark-readable) output streams.

It combines two hook roles:

• Hooks::Port : receives callbacks when messages are sent/received on ports.
• Hooks::Graph : receives callbacks when nodes are created/removed, so capture can maintain a coherent view of the graph topology over time.

Internally, Capture delegates actual encoding and I/O to a dedicated Worker, and can be connected to one or more output "sinks" (file, pipe, TCP).

Output sinks

Capture can stream PCAPNG data to different destinations:

• FileSink : write to a file (offline capture),
• PipeSink : write to a pipe (live capture, e.g. into Wireshark),
• TcpSink : stream over TCP (remote/live capture).

Sinks can be enabled/disabled at runtime with the set*Sink() / unset*Sink() APIs. The worker is responsible for orchestrating emission to the active sinks.

Capture keeps weak references to nodes it has seen via graph callbacks. These are used to emit node-related metadata consistently even if nodes are later destroyed.

Metadata

Capture can optionally include host metadata such as hardware and OS information. Additionally, user-provided application info can be included via setUserAppInfo().

Note

Port hooks may be invoked from the runtime’s execution threads. Capture is designed to forward events to an internal worker for serialization and I/O, keeping hook callbacks lightweight.

Constructor & Destructor Documentation

Capture()

dfx::Pcapng::Capture::Capture

(

bool

getHwAndOsInfo = true

)

Construct a capture hook.

Parameters

getHwAndOsInfo

If true, the capture will include host metadata such as hardware and OS information. Similar to the uname -srvm command.

~Capture()

dfx::Pcapng::Capture::~Capture

(

)

Destroy the capture hook and stop background capture work.

The destructor is responsible for stopping the internal worker and flushing/closing any active sinks, so that the capture output is finalized properly. It also deregisters it-self from all nodes that are still alive.

Member Function Documentation

onChannelCreated()

void dfx::Pcapng::Capture::onChannelCreated ( Core::ChannelPtr )

inlineoverridevirtual

Graph hook: channel creation is currently ignored for capture.

Implements dfx::Hooks::Graph.

onChannelRemoved()

void dfx::Pcapng::Capture::onChannelRemoved ( Core::ChannelPtr )

inlineoverridevirtual

Graph hook: channel removal is currently ignored for capture.

Implements dfx::Hooks::Graph.

onMessageReceived()

void dfx::Pcapng::Capture::onMessageReceived ( Core::InputPort const & port, Core::Message const & message )

overridevirtual

Port hook: called when a message is received by an input port.

The capture records the message reception event and forwards the relevant data to the internal worker for serialization into PCAPNG blocks.

Parameters

port	Input port that received the message.
message	Message being received.

Implements dfx::Hooks::Port.

onMessageSent()

void dfx::Pcapng::Capture::onMessageSent ( Core::OutputPort const & port, Core::Message const & message )

overridevirtual

Port hook: called when a message is sent from an output port.

The capture records the message emission event and forwards the relevant data to the internal worker for serialization into PCAPNG blocks.

Parameters

port	Output port that emitted the message.
message	Message being sent.

Implements dfx::Hooks::Port.

onNodeCreated()

void dfx::Pcapng::Capture::onNodeCreated ( Core::NodePtr node )

overridevirtual

Graph hook: called when a node is created.

Register this as Hooks::Port for every input and output port of the created node.

Parameters

node	Newly created node.

Implements dfx::Hooks::Graph.

onNodeRemoved()

void dfx::Pcapng::Capture::onNodeRemoved ( Core::NodePtr node )

overridevirtual

Graph hook: called when a node is removed.

Remove the internal weak pointer from the watch list.

Parameters

node	Removed node.

Implements dfx::Hooks::Graph.

setFileSink()

template<typename ... Args>

void dfx::Pcapng::Capture::setFileSink ( Args &&... args )

inline

Enable file output using a FileSink.

Creates a new FileSink and installs it as an active capture destination. If a file sink was already active, it is replaced.

Template Parameters

Args	Arguments forwarded to the FileSink constructor.

Parameters

args	Sink constructor arguments.

setPipeSink()

template<typename ... Args>

void dfx::Pcapng::Capture::setPipeSink ( Args &&... args )

inline

Enable pipe output using a PipeSink.

Creates a new PipeSink and installs it as an active capture destination. If a pipe sink was already active, it is replaced.

Template Parameters

Args	Arguments forwarded to the PipeSink constructor.

Parameters

args	Sink constructor arguments.

setTcpSink()

template<typename ... Args>

void dfx::Pcapng::Capture::setTcpSink ( Args &&... args )

inline

Enable TCP output using a TcpSink.

Creates a new TcpSink and installs it as an active capture destination. If a TCP sink was already active, it is replaced.

Template Parameters

Args	Arguments forwarded to the TcpSink constructor.

Parameters

args	Sink constructor arguments.

setUserAppInfo()

void dfx::Pcapng::Capture::setUserAppInfo

(

std::string

info

)

Set application-specific information to embed in the capture.

This information is intended to help identify the capture in tooling (e.g. Wireshark) and can include things like scenario name, version, build ID, test case, etc. The default value is "dfx-pcapng"

Parameters

info	Free-form string describing the user application / scenario.

unsetFileSink()

void dfx::Pcapng::Capture::unsetFileSink

(

)

Disable the file sink if enabled.

unsetPipeSink()

void dfx::Pcapng::Capture::unsetPipeSink

(

)

Disable the pipe sink if enabled.

unsetTcpSink()

void dfx::Pcapng::Capture::unsetTcpSink

(

)

Disable the TCP sink if enabled.

---

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

• lib/dfx-pcapng/Capture.hpp