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

Source
#pragma once

#include <stdint.h>
#include <stdio.h>
#include "ProtocolType.h"
#include "Serializers.h"
#include <ostream>
#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;

  namespace internal
  {
    /// @brief Holds information about a Layer's data and object ownership.
    struct LayerAllocationInfo
    {
      /// @brief Pointer to the Packet this layer is attached to (if any).
      ///
      /// If the layer is attached to a Packet, the layer's memory span (data) is considered managed by the
      /// Packet. The Packet is responsible for keeping the layer's memory span valid and updating it should it
      /// become necessary as long as the layer is attached to it.
      ///
      /// In an event the Packet is destroyed, all of its attached layers's memory views are considered invalid.
      /// Accessing layer data after the Packet is destroyed results in undefined behavior.
      ///
      /// If nullptr, the layer is not attached to any Packet and is considered unmanaged.
      /// It also means the layer's memory span is considered owned by the layer itself and will be freed when
      /// the layer is destroyed.
      Packet* attachedPacket = nullptr;

      /// @brief Controls if the layer object is considered owned by the attached Packet
      ///
      /// If 'true', the Layer object is considered owned by the attached Packet and will be freed by it on Packet
      /// destruction.
      ///
      /// If 'false', the Layer object is considered unmanaged and the user is responsible for freeing it.
      /// This is commonly the case for layers created on the stack and attached to a Packet.
      bool ownedByPacket = false;

      /// @brief Sets the state of attachment to a specified Packet
      /// @param packet Pointer to the Packet this layer is attached to (or nullptr if not attached to any Packet)
      /// @param managed True if the layer object's lifetime is to be managed by the Packet, false otherwise
      /// @param force If true, bypasses the check for existing attachment. Default is false.
      /// @throws std::runtime_error if the layer is already attached to a Packet and 'force' is false
      void attachPacket(Packet* packet, bool managed, bool force = false)
      {
        if (!force && attachedPacket != nullptr)
        {
          throw std::runtime_error("Layer is already attached to a Packet");
        }

        attachedPacket = packet;
        ownedByPacket = managed;
      }

      /// @brief Clears the attachment to any Packet, resetting to unmanaged state.
      void detach()
      {
        attachedPacket = nullptr;
        ownedByPacket = false;
      }
    };
  }  // namespace internal

  /// @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_AllocationInfo.attachedPacket != nullptr;
    }

    /// @brief Copy the raw data of this layer to another array
    ///
    /// @warning The method does not perform any bounds checking on the destination array. The caller MUST ensure
    /// that the destination array has enough space to hold the getDataLen() bytes.
    ///
    /// @warning Prefer the overload of copyData() that accepts a destination size to ensure safe copying of data.
    ///
    /// @param[out] toArr The destination byte array
    void copyData(uint8_t* toArr) const;

    /// @brief Copy the raw data of this layer to another array, with a specified maximum size.
    ///
    /// The method copies up to 'destSize' bytes of the layer's raw data into the provided destination array.
    /// If the layer's data length is greater than 'destSize', only the first 'destSize' bytes will be copied.
    ///
    /// To ensure sufficient space is available in the destination array, use getDataLen() to determine the actual
    /// length of the layer's data before calling this method.
    ///
    /// @param[out] dest The destination byte array
    /// @param[in] destSize The maximum number of bytes to copy
    /// @return The number of bytes copied to the destination array.
    size_t copyData(uint8_t* dest, size_t destSize) const;

    /// @struct SerializedFields
    /// Field descriptors for the fields serialized by Layer::serialize().
    struct SerializedFields
    {
      /// @return A vector containing all layer field descriptors.
      static std::vector<FieldDescriptor> all()
      {
        return { ProtocolName, ProtocolId, Length };
      }

      /// Field descriptor for the layer protocol name.
      static const FieldDescriptor ProtocolName;

      /// Field descriptor for the layer protocol ID.
      static const FieldDescriptor ProtocolId;

      /// Field descriptor for the layer length.
      static const FieldDescriptor Length;

      /// Maximum field ID used by the layer.
      static constexpr uint16_t MaxID = 1;
    };

    /// Serialize the layer using the provided serializer.
    /// @param[in] serializer The serializer to use.
    void serialize(ISerializer& serializer) 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;
    ProtocolType m_Protocol;
    Layer* m_NextLayer;
    Layer* m_PrevLayer;

  private:
    internal::LayerAllocationInfo m_AllocationInfo;

  protected:
    Layer() : m_Data(nullptr), m_DataLen(0), m_Protocol(UnknownProtocol), m_NextLayer(nullptr), m_PrevLayer(nullptr)
    {}

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

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

    /// @brief Get a pointer to the Packet this layer is attached to (if any).
    /// @return A pointer to the Packet this layer is attached to, or nullptr if the layer is not attached.
    Packet* getAttachedPacket()
    {
      return m_AllocationInfo.attachedPacket;
    }

    /// @brief Get a pointer to the Packet this layer is attached to (if any).
    /// @return A const pointer to the Packet this layer is attached to, or nullptr if the layer is not attached.
    Packet const* getAttachedPacket() const
    {
      return m_AllocationInfo.attachedPacket;
    }

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

    // ------ Memory Control Methods -----
    // Used by derived classes to request buffer size changes.

    /// @brief Requests the layer to allocate a new data buffer of the specified length.
    ///
    /// If the layer is not attached to a Packet, it will allocate a new buffer of the specified length.
    /// If the layer is attached to a Packet, it will throw a std::logic_error, as that case is not yet supported.
    ///
    /// The primary use case for this method is initial allocation of the data buffer in derived classes.
    ///
    /// @param[in] dataLen The length of the new data buffer.
    /// @param[in] zeroInit If true, the new buffer will be zero-initialized.
    /// @throws std::runtime_error if the layer already has allocated data.
    /// @throws std::logic_error if the layer is attached to a Packet (not yet supported).
    void allocData(size_t dataLen, bool zeroInit = true);

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

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

    /// @brief Construct the next layer in the protocol stack. No validation is performed on the data.
    ///
    /// This overload infers the Packet from the current layer.
    ///
    /// @tparam T The type of the layer to construct
    /// @tparam Args The types of the arguments to pass to the layer constructor
    /// @param data The data to construct the layer from
    /// @param dataLen The length of the data
    /// @param 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, Args&&... extraArgs)
    {
      return constructNextLayer<T>(data, dataLen, getAttachedPacket(), std::forward<Args>(extraArgs)...);
    }

    /// 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;
    }

    /// @brief Construct the next layer in the protocol stack using a factory functor.
    ///
    /// No validation is performed on the data, outside of what the factory functor may perform.
    /// If the factory returns a nullptr, no next layer is set.
    ///
    /// The factory functor is expected to have the following signature:
    /// Layer* factoryFn(uint8_t* data, size_t dataLen, Layer* prevLayer, Packet* packet, ...);
    ///
    /// This overload infers the Packet from the current layer.
    ///
    /// @tparam TFactory The factory functor type.
    /// @tparam ...Args Parameter pack for extra arguments to pass to the factory functor.
    /// @param[in] factoryFn The factory functor to create the layer.
    /// @param[in] data The data to construct the layer from
    /// @param[in] dataLen The length of the data
    /// @param[in] extraArgs Extra arguments to be forwarded to the factory.
    /// @return The return value of the factory functor.
    template <typename TFactory, typename... Args>
    Layer* constructNextLayerFromFactory(TFactory factoryFn, uint8_t* data, size_t dataLen, Args&&... extraArgs)
    {
      return constructNextLayerFromFactory<TFactory>(factoryFn, data, dataLen, getAttachedPacket(),
                                                     std::forward<Args>(extraArgs)...);
    }

    /// @brief Construct the next layer in the protocol stack using a factory functor.
    ///
    /// No validation is performed on the data, outside of what the factory functor may perform.
    /// If the factory returns a nullptr, no next layer is set.
    ///
    /// The factory functor is expected to have the following signature:
    /// Layer* factoryFn(uint8_t* data, size_t dataLen, Layer* prevLayer, Packet* packet, ...);
    ///
    /// @tparam TFactory The factory functor type.
    /// @tparam ...Args Parameter pack for extra arguments to pass to the factory functor.
    /// @param[in] factoryFn The factory functor to create the layer.
    /// @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 factory.
    /// @return The return value of the factory functor.
    template <typename TFactory, typename... Args>
    Layer* constructNextLayerFromFactory(TFactory factoryFn, uint8_t* data, size_t dataLen, Packet* packet,
                                         Args&&... extraArgs)
    {
      if (hasNextLayer())
      {
        throw std::runtime_error("Next layer already exists");
      }

      // cppcheck-suppress redundantInitialization
      Layer* newLayer = factoryFn(data, dataLen, this, packet, std::forward<Args>(extraArgs)...);
      setNextLayer(newLayer);
      return newLayer;
    }

    /// Try to construct the next layer in the protocol stack.
    ///
    /// This overload infers the Packet from the current layer.
    ///
    /// 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, no layer is constructed and 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] 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, Args&&... extraArgs)
    {
      return tryConstructNextLayer<T>(data, dataLen, getAttachedPacket(), std::forward<Args>(extraArgs)...);
    }

    /// 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, no layer is constructed and 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;
    }

    /// @brief Try to construct the next layer in the protocol stack with a fallback option.
    ///
    /// This overload infers the Packet from the current layer.
    ///
    /// 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] extraArgs Extra arguments to be forwarded to the layer constructor of T
    /// @return The constructed layer of type T or TFallback
    /// @remarks The parameters extraArgs are forwarded to the factory function, but not to the TFallback
    /// constructor.
    template <typename T, typename TFallback, typename... Args>
    Layer* tryConstructNextLayerWithFallback(uint8_t* data, size_t dataLen, Args&&... extraArgs)
    {
      return tryConstructNextLayerWithFallback<T, TFallback>(data, dataLen, getAttachedPacket(),
                                                             std::forward<Args>(extraArgs)...);
    }

    /// 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
    /// @remarks The parameters extraArgs are forwarded to the factory function, but not to the TFallback
    /// constructor.
    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 Try to construct the next layer in the protocol stack using a factory functor with a fallback option.
    ///
    /// The method will attempt to construct the next layer using the provided factory function.
    /// If the factory function returns nullptr, indicating failure to create the layer, the method will then
    /// construct a layer of type TFallback.
    ///
    /// The factory functor is expected to have the following signature:
    /// Layer* factoryFn(uint8_t* data, size_t dataLen, Layer* prevLayer, Packet* packet, ...);
    ///
    /// This overload infers the Packet from the current layer.
    ///
    /// @tparam TFallback The fallback layer type to construct if the factory fails.
    /// @tparam TFactory The factory functor type.
    /// @tparam ...Args Parameter pack for extra arguments to pass to the factory functor.
    /// @param[in] factoryFn The factory functor to create the layer.
    /// @param[in] data The data to construct the layer from
    /// @param[in] dataLen The length of the data
    /// @param[in] extraArgs Extra arguments to be forwarded to the factory.
    /// @return The return value of the factory functor.
    /// @remarks The parameters extraArgs are forwarded to the factory function, but not to the TFallback
    /// constructor.
    template <typename TFallback, typename TFactory, typename... Args>
    Layer* tryConstructNextLayerFromFactoryWithFallback(TFactory factoryFn, uint8_t* data, size_t dataLen,
                                                        Args&&... extraArgs)
    {
      // Note that the fallback is first to allow template argument deduction of the factory type.
      return tryConstructNextLayerFromFactoryWithFallback<TFallback, TFactory>(
          factoryFn, data, dataLen, getAttachedPacket(), std::forward<Args>(extraArgs)...);
    }

    /// @brief Try to construct the next layer in the protocol stack using a factory functor with a fallback option.
    ///
    /// The method will attempt to construct the next layer using the provided factory function.
    /// If the factory function returns nullptr, indicating failure to create the layer, the method will then
    /// construct a layer of type TFallback.
    ///
    /// The factory functor is expected to have the following signature:
    /// Layer* factoryFn(uint8_t* data, size_t dataLen, Layer* prevLayer, Packet* packet, ...);
    ///
    /// @tparam TFallback The fallback layer type to construct if the factory fails.
    /// @tparam TFactory The factory functor type.
    /// @tparam ...Args Parameter pack for extra arguments to pass to the factory functor.
    /// @param[in] factoryFn The factory functor to create the layer.
    /// @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 factory.
    /// @return The return value of the factory functor.
    /// @remarks The parameters extraArgs are forwarded to the factory function, but not to the TFallback
    /// constructor.
    template <typename TFallback, typename TFactory, typename... Args>
    Layer* tryConstructNextLayerFromFactoryWithFallback(TFactory factoryFn, uint8_t* data, size_t dataLen,
                                                        Packet* packet, Args&&... extraArgs)
    {
      auto nextLayer = constructNextLayerFromFactory<TFactory>(factoryFn, data, dataLen, packet,
                                                               std::forward<Args>(extraArgs)...);
      if (nextLayer != nullptr)
      {
        return nextLayer;
      }

      // factory failed, construct fallback layer
      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);
    }

    /// Serializes the layer's data into a provided serializer object.
    /// This is used for generating serialized representations (like JSON) of the packet layers.
    /// This method should be overridden by derived layers to provide specific serialization logic.
    ///
    /// @param[in] serializer The object scope serializer to which the layer details should be written.
    virtual void serializeLayer(ObjectScope& serializer) const
    {}
  };

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

Coverage Report

Created: 2026-09-28 07:37