interest.hpp

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013-2024 Regents of the University of California.
 *
 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
 *
 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later version.
 *
 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
 *
 * You should have received copies of the GNU General Public License and GNU Lesser
 * General Public License along with ndn-cxx, e.g., in COPYING.md file.  If not, see
 * <http://www.gnu.org/licenses/>.
 *
 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
 */
 
#ifndef NDN_CXX_INTEREST_HPP
#define NDN_CXX_INTEREST_HPP
 
#include "ndn-cxx/detail/packet-base.hpp"
#include "ndn-cxx/name.hpp"
#include "ndn-cxx/security/security-common.hpp"
#include "ndn-cxx/signature-info.hpp"
#include "ndn-cxx/util/string-helper.hpp"
#include "ndn-cxx/util/time.hpp"
 
#include <array>
 
#include <boost/endian/conversion.hpp>
 
namespace ndn {
 
class Data;
 
inline constexpr time::milliseconds DEFAULT_INTEREST_LIFETIME = 4_s;
 
class Interest : public PacketBase, public std::enable_shared_from_this<Interest>
{
public:
  class Error : public tlv::Error
  {
  public:
    using tlv::Error::Error;
  };
 
  class Nonce final : public std::array<uint8_t, 4>, private boost::equality_comparable<Nonce>
  {
  public:
    Nonce() = default;
 
    // implicit conversion from uint32_t
    Nonce(uint32_t n) noexcept
    {
      boost::endian::native_to_big_inplace(n);
      std::memcpy(data(), &n, sizeof(n));
    }
 
    Nonce(uint8_t n1, uint8_t n2, uint8_t n3, uint8_t n4) noexcept
    {
      (*this)[0] = n1;
      (*this)[1] = n2;
      (*this)[2] = n3;
      (*this)[3] = n4;
    }
 
  private: // non-member operators
    // NOTE: the following "hidden friend" operators are available via
    //       argument-dependent lookup only and must be defined inline.
    // boost::equality_comparable provides != operator.
 
    friend bool
    operator==(const Nonce& lhs, const Nonce& rhs) noexcept
    {
      return std::equal(lhs.begin(), lhs.end(), rhs.begin());
    }
 
    friend std::ostream&
    operator<<(std::ostream& os, const Nonce& nonce)
    {
      printHex(os, nonce, false);
      return os;
    }
  };
 
  explicit
  Interest(const Name& name = {}, time::milliseconds lifetime = DEFAULT_INTEREST_LIFETIME);
 
  explicit
  Interest(const Block& wire);
 
  template<encoding::Tag TAG>
  size_t
  wireEncode(EncodingImpl<TAG>& encoder) const;
 
  const Block&
  wireEncode() const;
 
  void
  wireDecode(const Block& wire);
 
  bool
  hasWire() const noexcept
  {
    return m_wire.hasWire();
  }
 
  std::string
  toUri() const;
 
public: // matching
  [[nodiscard]] bool
  matchesData(const Data& data) const;
 
  [[nodiscard]] bool
  matchesInterest(const Interest& other) const;
 
public: // Interest fields
  const Name&
  getName() const noexcept
  {
    return m_name;
  }
 
  Interest&
  setName(const Name& name);
 
  bool
  getCanBePrefix() const noexcept
  {
    return m_canBePrefix;
  }
 
  Interest&
  setCanBePrefix(bool canBePrefix);
 
  bool
  getMustBeFresh() const noexcept
  {
    return m_mustBeFresh;
  }
 
  Interest&
  setMustBeFresh(bool mustBeFresh);
 
  span<const Name>
  getForwardingHint() const noexcept
  {
    return m_forwardingHint;
  }
 
  Interest&
  setForwardingHint(std::vector<Name> value);
 
  bool
  hasNonce() const noexcept
  {
    return m_nonce.has_value();
  }
 
  Nonce
  getNonce() const;
 
  Interest&
  setNonce(std::optional<Nonce> nonce);
 
  void
  refreshNonce();
 
  time::milliseconds
  getInterestLifetime() const noexcept;
 
  Interest&
  setInterestLifetime(time::milliseconds lifetime);
 
  std::optional<uint8_t>
  getHopLimit() const noexcept
  {
    return m_hopLimit;
  }
 
  Interest&
  setHopLimit(std::optional<uint8_t> hopLimit);
 
  bool
  hasApplicationParameters() const noexcept
  {
    return !m_parameters.empty();
  }
 
  Block
  getApplicationParameters() const
  {
    if (m_parameters.empty())
      return {};
    else
      return m_parameters.front();
  }
 
  Interest&
  setApplicationParameters(const Block& block);
 
  Interest&
  setApplicationParameters(span<const uint8_t> value);
 
  Interest&
  setApplicationParameters(std::string_view value);
 
  Interest&
  setApplicationParameters(ConstBufferPtr value);
 
  Interest&
  setApplicationParameters(std::nullptr_t) = delete;
 
  Interest&
  unsetApplicationParameters();
 
  bool
  isSigned() const noexcept;
 
  std::optional<SignatureInfo>
  getSignatureInfo() const;
 
  Interest&
  setSignatureInfo(const SignatureInfo& info);
 
  Block
  getSignatureValue() const;
 
  Interest&
  setSignatureValue(span<const uint8_t> value);
 
  Interest&
  setSignatureValue(ConstBufferPtr value);
 
  Interest&
  setSignatureValue(std::nullptr_t) = delete;
 
  [[nodiscard]] InputBuffers
  extractSignedRanges() const;
 
public: // ParametersSha256DigestComponent support
  static bool
  getAutoCheckParametersDigest()
  {
    return s_autoCheckParametersDigest;
  }
 
  static void
  setAutoCheckParametersDigest(bool b)
  {
    s_autoCheckParametersDigest = b;
  }
 
  bool
  isParametersDigestValid() const;
 
private:
  Interest&
  setApplicationParametersInternal(Block parameters);
 
  Interest&
  setSignatureValueInternal(Block sigValue);
 
  [[nodiscard]] shared_ptr<Buffer>
  computeParametersDigest() const;
 
  void
  addOrReplaceParametersDigestComponent();
 
  static ssize_t
  findParametersDigestComponent(const Name& name);
 
  std::vector<Block>::const_iterator
  findFirstParameter(uint32_t type) const;
 
private:
  Name m_name;
  std::vector<Name> m_forwardingHint;
  mutable std::optional<Nonce> m_nonce;
  uint64_t m_interestLifetime = DEFAULT_INTEREST_LIFETIME.count();
  std::optional<uint8_t> m_hopLimit;
  bool m_canBePrefix = false;
  bool m_mustBeFresh = false;
 
  // Stores the "Interest parameters", i.e., all maybe-unrecognized non-critical TLV
  // elements that appear at the end of the Interest, starting from ApplicationParameters.
  // If the Interest does not contain any ApplicationParameters TLV, this vector will
  // be empty. Conversely, if this vector is not empty, the first element will always
  // be an ApplicationParameters block. All blocks in this vector are covered by the
  // digest in the ParametersSha256DigestComponent.
  std::vector<Block> m_parameters;
 
  mutable Block m_wire;
 
  static inline bool s_autoCheckParametersDigest = true;
};
 
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(Interest);
 
std::ostream&
operator<<(std::ostream& os, const Interest& interest);
 
} // namespace ndn
 
#endif // NDN_CXX_INTEREST_HPP