/src/PcapPlusPlus/Packet++/header/Layer.h

Source (jump to first uncovered line)
#pragma once

#include <stdint.h>
#include <stdio.h>
#include "ProtocolType.h"
#include <string>
#include <stdexcept>
#include <utility>

/// @file

/// @namespace pcpp
/// @brief The main namespace for the PcapPlusPlus lib
namespace pcpp
{

  /// @class IDataContainer
  /// An interface (virtual abstract class) that indicates an object that holds a pointer to a buffer data. The Layer
  /// class is an example of such object, hence it inherits this interface
  class IDataContainer
  {
  public:
    /// Get a pointer to the data
    /// @param[in] offset Get a pointer in a certain offset. Default is 0 - get a pointer to start of data
    /// @return A pointer to the data
    virtual uint8_t* getDataPtr(size_t offset = 0) const = 0;

    virtual ~IDataContainer() = default;
  };

  class Packet;

  /// @class Layer
  /// Layer is the base class for all protocol layers. Each protocol supported in PcapPlusPlus has a class that
  /// inherits Layer.
  /// The protocol layer class expose all properties and methods relevant for viewing and editing protocol fields.
  /// For example: a pointer to a structured header (e.g tcphdr, iphdr, etc.), protocol header size, payload size,
  /// compute fields that can be automatically computed, print protocol data to string, etc.
  /// Each protocol instance is obviously part of a protocol stack (which construct a packet). This protocol stack is
  /// represented in PcapPlusPlus in a linked list, and each layer is an element in this list. That's why each layer
  /// has properties to the next and previous layer in the protocol stack. The Layer class, as a base class, is
  /// abstract and the user can't create an instance of it (it has a private constructor). Each layer holds a pointer
  /// to the relevant place in the packet. The layer sees all the data from this pointer forward until the end of the
  /// packet. Here is an example packet showing this concept:
  ///
  /// @code{.unparsed}
  /// ====================================================
  /// |Eth       |IPv4       |TCP       |Packet          |
  /// |Header    |Header     |Header    |Payload         |
  /// ====================================================
  ///
  /// |--------------------------------------------------|
  /// EthLayer data
  ///            |---------------------------------------|
  ///            IPv4Layer data
  ///                        |---------------------------|
  ///                        TcpLayer data
  ///                                   |----------------|
  ///                                   PayloadLayer data
  /// @endcode
  class Layer : public IDataContainer
  {
    friend class Packet;

  public:
    /// A destructor for this class. Frees the data if it was allocated by the layer constructor (see
    /// isAllocatedToPacket() for more info)
    ~Layer() override;

    /// @return A pointer to the next layer in the protocol stack or nullptr if the layer is the last one
    Layer* getNextLayer() const
    {
      return m_NextLayer;
    }

    /// @return A pointer to the previous layer in the protocol stack or nullptr if the layer is the first one
    Layer* getPrevLayer() const
    {
      return m_PrevLayer;
    }

    /// @return The protocol enum
    ProtocolType getProtocol() const
    {
      return m_Protocol;
    }

    /// Check if the layer's protocol matches a protocol family
    /// @param protocolTypeFamily The protocol family to check
    /// @return True if the layer's protocol matches the protocol family, false otherwise
    bool isMemberOfProtocolFamily(ProtocolTypeFamily protocolTypeFamily) const;

    /// @return A pointer to the layer raw data. In most cases it'll be a pointer to the first byte of the header
    uint8_t* getData() const
    {
      return m_Data;
    }

    /// @return The length in bytes of the data from the first byte of the header until the end of the packet
    size_t getDataLen() const
    {
      return m_DataLen;
    }

    /// @return A pointer for the layer payload, meaning the first byte after the header
    uint8_t* getLayerPayload() const
    {
      return m_Data + getHeaderLen();
    }

    /// @return The size in bytes of the payload
    size_t getLayerPayloadSize() const
    {
      return m_DataLen - getHeaderLen();
    }

    /// Raw data in layers can come from one of sources:
    /// 1. from an existing packet - this is the case when parsing packets received from files or the network. In
    /// this case the data was already allocated by someone else, and layer only holds the pointer to the relevant
    /// place inside this data
    /// 2. when creating packets, data is allocated when layer is created. In this case the layer is responsible for
    /// freeing it as well
    ///
    /// @return Returns true if the data was allocated by an external source (a packet) or false if it was allocated
    /// by the layer itself
    bool isAllocatedToPacket() const
    {
      return m_Packet != nullptr;
    }

    /// Copy the raw data of this layer to another array
    /// @param[out] toArr The destination byte array
    void copyData(uint8_t* toArr) const;

    // implement abstract methods

    uint8_t* getDataPtr(size_t offset = 0) const override
    {
      return static_cast<uint8_t*>(m_Data + offset);
    }

    // abstract methods

    /// Each layer is responsible for parsing the next layer
    virtual void parseNextLayer() = 0;

    /// @return The header length in bytes
    virtual size_t getHeaderLen() const = 0;

    /// Each layer can compute field values automatically using this method. This is an abstract method
    virtual void computeCalculateFields() = 0;

    /// @return A string representation of the layer most important data (should look like the layer description in
    /// Wireshark)
    virtual std::string toString() const = 0;

    /// @return The OSI Model layer this protocol belongs to
    virtual OsiModelLayer getOsiModelLayer() const = 0;

  protected:
    uint8_t* m_Data;
    size_t m_DataLen;
    Packet* m_Packet;
    ProtocolType m_Protocol;
    Layer* m_NextLayer;
    Layer* m_PrevLayer;
    bool m_IsAllocatedInPacket;

    Layer()
        : m_Data(nullptr), m_DataLen(0), m_Packet(nullptr), m_Protocol(UnknownProtocol), m_NextLayer(nullptr),
          m_PrevLayer(nullptr), m_IsAllocatedInPacket(false)
    {}

    Layer(uint8_t* data, size_t dataLen, Layer* prevLayer, Packet* packet, ProtocolType protocol = UnknownProtocol)
        : m_Data(data), m_DataLen(dataLen), m_Packet(packet), m_Protocol(protocol), m_NextLayer(nullptr),
          m_PrevLayer(prevLayer), m_IsAllocatedInPacket(false)
    {}

    // Copy c'tor
    Layer(const Layer& other);
    Layer& operator=(const Layer& other);

    void setNextLayer(Layer* nextLayer)
    {
      m_NextLayer = nextLayer;
    }
    void setPrevLayer(Layer* prevLayer)
    {
      m_PrevLayer = prevLayer;
    }

    virtual bool extendLayer(int offsetInLayer, size_t numOfBytesToExtend);
    virtual bool shortenLayer(int offsetInLayer, size_t numOfBytesToShorten);

    bool hasNextLayer() const
    {
      return m_NextLayer != nullptr;
    }

    /// Construct the next layer in the protocol stack. No validation is performed on the data.
    /// @tparam T The type of the layer to construct
    /// @tparam Args The types of the arguments to pass to the layer constructor
    /// @param[in] data The data to construct the layer from
    /// @param[in] dataLen The length of the data
    /// @param[in] packet The packet the layer belongs to
    /// @param[in] extraArgs Extra arguments to be forwarded to the layer constructor
    /// @return The constructed layer
    template <typename T, typename... Args>
    Layer* constructNextLayer(uint8_t* data, size_t dataLen, Packet* packet, Args&&... extraArgs)
    {
      if (hasNextLayer())
      {
        throw std::runtime_error("Next layer already exists");
      }

      Layer* newLayer = new T(data, dataLen, this, packet, std::forward<Args>(extraArgs)...);
      setNextLayer(newLayer);
      return newLayer;
    }

    /// Try to construct the next layer in the protocol stack with a fallback option.
    ///
    /// The method checks if the data is valid for the layer type T before constructing it by calling
    /// T::isDataValid(data, dataLen). If the data is invalid, it constructs the layer of type TFallback.
    ///
    /// @tparam T The type of the layer to construct
    /// @tparam TFallback The fallback layer type to construct if T fails
    /// @tparam Args The types of the extra arguments to pass to the layer constructor of T
    /// @param[in] data The data to construct the layer from
    /// @param[in] dataLen The length of the data
    /// @param[in] packet The packet the layer belongs to
    /// @param[in] extraArgs Extra arguments to be forwarded to the layer constructor of T
    /// @return The constructed layer of type T or TFallback
    template <typename T, typename TFallback, typename... Args>
    Layer* tryConstructNextLayerWithFallback(uint8_t* data, size_t dataLen, Packet* packet, Args&&... extraArgs)
    {
      if (tryConstructNextLayer<T>(data, dataLen, packet, std::forward<Args>(extraArgs)...))
      {
        return m_NextLayer;
      }

      return constructNextLayer<TFallback>(data, dataLen, packet);
    }

    /// @brief Check if the data is large enough to reinterpret as a type
    ///
    /// The data must be non-null and at least as large as the type
    ///
    /// @tparam T The type to reinterpret as
    /// @param data The data to check
    /// @param dataLen The length of the data
    /// @return True if the data is large enough to reinterpret as T, false otherwise
    template <typename T> static bool canReinterpretAs(const uint8_t* data, size_t dataLen)
    {
      return data != nullptr && dataLen >= sizeof(T);
    }

  private:
    /// Try to construct the next layer in the protocol stack.
    ///
    /// The method checks if the data is valid for the layer type T before constructing it by calling
    /// T::isDataValid(data, dataLen). If the data is invalid, a nullptr is returned.
    ///
    /// @tparam T The type of the layer to construct
    /// @tparam Args The types of the extra arguments to pass to the layer constructor
    /// @param[in] data The data to construct the layer from
    /// @param[in] dataLen The length of the data
    /// @param[in] packet The packet the layer belongs to
    /// @param[in] extraArgs Extra arguments to be forwarded to the layer constructor
    /// @return The constructed layer or nullptr if the data is invalid
    template <typename T, typename... Args>
    Layer* tryConstructNextLayer(uint8_t* data, size_t dataLen, Packet* packet, Args&&... extraArgs)
    {
      if (T::isDataValid(data, dataLen))
      {
        return constructNextLayer<T>(data, dataLen, packet, std::forward<Args>(extraArgs)...);
      }
      return nullptr;
    }
  };

  inline std::ostream& operator<<(std::ostream& os, const pcpp::Layer& layer)
  {
    os << layer.toString();
    return os;
  }
}  // namespace pcpp

Coverage Report

Created: 2025-07-11 06:47

Line	Count	Source (jump to first uncovered line)
1		#pragma once
2
3		#include <stdint.h>
4		#include <stdio.h>
5		#include "ProtocolType.h"
6		#include <string>
7		#include <stdexcept>
8		#include <utility>
9
10		/// @file
11
12		/// @namespace pcpp
13		/// @brief The main namespace for the PcapPlusPlus lib
14		namespace pcpp
15		{
16
17		/// @class IDataContainer
18		/// An interface (virtual abstract class) that indicates an object that holds a pointer to a buffer data. The Layer
19		/// class is an example of such object, hence it inherits this interface
20		class IDataContainer
21		{
22		public:
23		/// Get a pointer to the data
24		/// @param[in] offset Get a pointer in a certain offset. Default is 0 - get a pointer to start of data
25		/// @return A pointer to the data
26		virtual uint8_t* getDataPtr(size_t offset = 0) const = 0;
27
28		virtual ~IDataContainer() = default;
29		};
30
31		class Packet;
32
33		/// @class Layer
34		/// Layer is the base class for all protocol layers. Each protocol supported in PcapPlusPlus has a class that
35		/// inherits Layer.
36		/// The protocol layer class expose all properties and methods relevant for viewing and editing protocol fields.
37		/// For example: a pointer to a structured header (e.g tcphdr, iphdr, etc.), protocol header size, payload size,
38		/// compute fields that can be automatically computed, print protocol data to string, etc.
39		/// Each protocol instance is obviously part of a protocol stack (which construct a packet). This protocol stack is
40		/// represented in PcapPlusPlus in a linked list, and each layer is an element in this list. That's why each layer
41		/// has properties to the next and previous layer in the protocol stack. The Layer class, as a base class, is
42		/// abstract and the user can't create an instance of it (it has a private constructor). Each layer holds a pointer
43		/// to the relevant place in the packet. The layer sees all the data from this pointer forward until the end of the
44		/// packet. Here is an example packet showing this concept:
45		///
46		/// @code{.unparsed}
47		/// ====================================================
48		/// \|Eth \|IPv4 \|TCP \|Packet \|
49		/// \|Header \|Header \|Header \|Payload \|
50		/// ====================================================
51		///
52		/// \|--------------------------------------------------\|
53		/// EthLayer data
54		/// \|---------------------------------------\|
55		/// IPv4Layer data
56		/// \|---------------------------\|
57		/// TcpLayer data
58		/// \|----------------\|
59		/// PayloadLayer data
60		/// @endcode
61		class Layer : public IDataContainer
62		{
63		friend class Packet;
64
65		public:
66		/// A destructor for this class. Frees the data if it was allocated by the layer constructor (see
67		/// isAllocatedToPacket() for more info)
68		~Layer() override;
69
70		/// @return A pointer to the next layer in the protocol stack or nullptr if the layer is the last one
71		Layer* getNextLayer() const
72	0	{
73	0	return m_NextLayer;
74	0	}
75
76		/// @return A pointer to the previous layer in the protocol stack or nullptr if the layer is the first one
77		Layer* getPrevLayer() const
78	0	{
79	0	return m_PrevLayer;
80	0	}
81
82		/// @return The protocol enum
83		ProtocolType getProtocol() const
84	0	{
85	0	return m_Protocol;
86	0	}
87
88		/// Check if the layer's protocol matches a protocol family
89		/// @param protocolTypeFamily The protocol family to check
90		/// @return True if the layer's protocol matches the protocol family, false otherwise
91		bool isMemberOfProtocolFamily(ProtocolTypeFamily protocolTypeFamily) const;
92
93		/// @return A pointer to the layer raw data. In most cases it'll be a pointer to the first byte of the header
94		uint8_t* getData() const
95	0	{
96	0	return m_Data;
97	0	}
98
99		/// @return The length in bytes of the data from the first byte of the header until the end of the packet
100		size_t getDataLen() const
101	0	{
102	0	return m_DataLen;
103	0	}
104
105		/// @return A pointer for the layer payload, meaning the first byte after the header
106		uint8_t* getLayerPayload() const
107	0	{
108	0	return m_Data + getHeaderLen();
109	0	}
110
111		/// @return The size in bytes of the payload
112		size_t getLayerPayloadSize() const
113	0	{
114	0	return m_DataLen - getHeaderLen();
115	0	}
116
117		/// Raw data in layers can come from one of sources:
118		/// 1. from an existing packet - this is the case when parsing packets received from files or the network. In
119		/// this case the data was already allocated by someone else, and layer only holds the pointer to the relevant
120		/// place inside this data
121		/// 2. when creating packets, data is allocated when layer is created. In this case the layer is responsible for
122		/// freeing it as well
123		///
124		/// @return Returns true if the data was allocated by an external source (a packet) or false if it was allocated
125		/// by the layer itself
126		bool isAllocatedToPacket() const
127	0	{
128	0	return m_Packet != nullptr;
129	0	}
130
131		/// Copy the raw data of this layer to another array
132		/// @param[out] toArr The destination byte array
133		void copyData(uint8_t* toArr) const;
134
135		// implement abstract methods
136
137		uint8_t* getDataPtr(size_t offset = 0) const override
138	0	{
139	0	return static_cast<uint8_t*>(m_Data + offset);
140	0	}
141
142		// abstract methods
143
144		/// Each layer is responsible for parsing the next layer
145		virtual void parseNextLayer() = 0;
146
147		/// @return The header length in bytes
148		virtual size_t getHeaderLen() const = 0;
149
150		/// Each layer can compute field values automatically using this method. This is an abstract method
151		virtual void computeCalculateFields() = 0;
152
153		/// @return A string representation of the layer most important data (should look like the layer description in
154		/// Wireshark)
155		virtual std::string toString() const = 0;
156
157		/// @return The OSI Model layer this protocol belongs to
158		virtual OsiModelLayer getOsiModelLayer() const = 0;
159
160		protected:
161		uint8_t* m_Data;
162		size_t m_DataLen;
163		Packet* m_Packet;
164		ProtocolType m_Protocol;
165		Layer* m_NextLayer;
166		Layer* m_PrevLayer;
167		bool m_IsAllocatedInPacket;
168
169		Layer()
170		: m_Data(nullptr), m_DataLen(0), m_Packet(nullptr), m_Protocol(UnknownProtocol), m_NextLayer(nullptr),
171		m_PrevLayer(nullptr), m_IsAllocatedInPacket(false)
172	0	{}
173
174		Layer(uint8_t* data, size_t dataLen, Layer* prevLayer, Packet* packet, ProtocolType protocol = UnknownProtocol)
175		: m_Data(data), m_DataLen(dataLen), m_Packet(packet), m_Protocol(protocol), m_NextLayer(nullptr),
176		m_PrevLayer(prevLayer), m_IsAllocatedInPacket(false)
177	0	{}
178
179		// Copy c'tor
180		Layer(const Layer& other);
181		Layer& operator=(const Layer& other);
182
183		void setNextLayer(Layer* nextLayer)
184	0	{
185	0	m_NextLayer = nextLayer;
186	0	}
187		void setPrevLayer(Layer* prevLayer)
188	0	{
189	0	m_PrevLayer = prevLayer;
190	0	}
191
192		virtual bool extendLayer(int offsetInLayer, size_t numOfBytesToExtend);
193		virtual bool shortenLayer(int offsetInLayer, size_t numOfBytesToShorten);
194
195		bool hasNextLayer() const
196	0	{
197	0	return m_NextLayer != nullptr;
198	0	}
199
200		/// Construct the next layer in the protocol stack. No validation is performed on the data.
201		/// @tparam T The type of the layer to construct
202		/// @tparam Args The types of the arguments to pass to the layer constructor
203		/// @param[in] data The data to construct the layer from
204		/// @param[in] dataLen The length of the data
205		/// @param[in] packet The packet the layer belongs to
206		/// @param[in] extraArgs Extra arguments to be forwarded to the layer constructor
207		/// @return The constructed layer
208		template <typename T, typename... Args>
209		Layer* constructNextLayer(uint8_t* data, size_t dataLen, Packet* packet, Args&&... extraArgs)
210		{
211		if (hasNextLayer())
212		{
213		throw std::runtime_error("Next layer already exists");
214		}
215
216		Layer* newLayer = new T(data, dataLen, this, packet, std::forward<Args>(extraArgs)...);
217		setNextLayer(newLayer);
218		return newLayer;
219		}
220
221		/// Try to construct the next layer in the protocol stack with a fallback option.
222		///
223		/// The method checks if the data is valid for the layer type T before constructing it by calling
224		/// T::isDataValid(data, dataLen). If the data is invalid, it constructs the layer of type TFallback.
225		///
226		/// @tparam T The type of the layer to construct
227		/// @tparam TFallback The fallback layer type to construct if T fails
228		/// @tparam Args The types of the extra arguments to pass to the layer constructor of T
229		/// @param[in] data The data to construct the layer from
230		/// @param[in] dataLen The length of the data
231		/// @param[in] packet The packet the layer belongs to
232		/// @param[in] extraArgs Extra arguments to be forwarded to the layer constructor of T
233		/// @return The constructed layer of type T or TFallback
234		template <typename T, typename TFallback, typename... Args>
235		Layer* tryConstructNextLayerWithFallback(uint8_t* data, size_t dataLen, Packet* packet, Args&&... extraArgs)
236		{
237		if (tryConstructNextLayer<T>(data, dataLen, packet, std::forward<Args>(extraArgs)...))
238		{
239		return m_NextLayer;
240		}
241
242		return constructNextLayer<TFallback>(data, dataLen, packet);
243		}
244
245		/// @brief Check if the data is large enough to reinterpret as a type
246		///
247		/// The data must be non-null and at least as large as the type
248		///
249		/// @tparam T The type to reinterpret as
250		/// @param data The data to check
251		/// @param dataLen The length of the data
252		/// @return True if the data is large enough to reinterpret as T, false otherwise
253		template <typename T> static bool canReinterpretAs(const uint8_t* data, size_t dataLen)
254	0	{
255	0	return data != nullptr && dataLen >= sizeof(T);
256	0	} Unexecuted instantiation: bool pcpp::Layer::canReinterpretAs<pcpp::arphdr>(unsigned char const, unsigned long) Unexecuted instantiation: bool pcpp::Layer::canReinterpretAs<pcpp::iphdr>(unsigned char const, unsigned long)
257
258		private:
259		/// Try to construct the next layer in the protocol stack.
260		///
261		/// The method checks if the data is valid for the layer type T before constructing it by calling
262		/// T::isDataValid(data, dataLen). If the data is invalid, a nullptr is returned.
263		///
264		/// @tparam T The type of the layer to construct
265		/// @tparam Args The types of the extra arguments to pass to the layer constructor
266		/// @param[in] data The data to construct the layer from
267		/// @param[in] dataLen The length of the data
268		/// @param[in] packet The packet the layer belongs to
269		/// @param[in] extraArgs Extra arguments to be forwarded to the layer constructor
270		/// @return The constructed layer or nullptr if the data is invalid
271		template <typename T, typename... Args>
272		Layer* tryConstructNextLayer(uint8_t* data, size_t dataLen, Packet* packet, Args&&... extraArgs)
273		{
274		if (T::isDataValid(data, dataLen))
275		{
276		return constructNextLayer<T>(data, dataLen, packet, std::forward<Args>(extraArgs)...);
277		}
278		return nullptr;
279		}
280		};
281
282		inline std::ostream& operator<<(std::ostream& os, const pcpp::Layer& layer)
283	0	{
284	0	os << layer.toString();
285	0	return os;
286	0	}
287		} // namespace pcpp