interest.hpp

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013-2022 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>
#include <boost/logic/tribool.hpp>
 
namespace ndn {
 
class Data;
 
const 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>
  {
    using Base = std::array<uint8_t, 4>;
 
  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
    {
      data()[0] = n1;
      data()[1] = n2;
      data()[2] = n3;
      data()[3] = n4;
    }
 
  private: // non-member operators
    // NOTE: the following "hidden friend" operators are available via
    //       argument-dependent lookup only and must be defined inline.
 
    friend bool
    operator==(const Nonce& lhs, const Nonce& rhs) noexcept
    {
      return static_cast<const Base&>(lhs) == static_cast<const Base&>(rhs);
    }
 
    friend bool
    operator!=(const Nonce& lhs, const Nonce& rhs) noexcept
    {
      return static_cast<const Base&>(lhs) != static_cast<const Base&>(rhs);
    }
 
    friend std::ostream&
    operator<<(std::ostream& os, const Nonce& nonce)
    {
      printHex(os, nonce, false);
      return os;
    }
  };
 
  explicit
  Interest(const Name& 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
  bool
  matchesData(const Data& data) const;
 
  bool
  matchesInterest(const Interest& other) const;
 
public: // element access
  const Name&
  getName() const noexcept
  {
    return m_name;
  }
 
  Interest&
  setName(const Name& name);
 
  [[deprecated]]
  static void
  setDefaultCanBePrefix(bool canBePrefix)
  {
    s_defaultCanBePrefix = canBePrefix;
  }
 
  bool
  getCanBePrefix() const noexcept
  {
    return m_canBePrefix;
  }
 
  Interest&
  setCanBePrefix(bool canBePrefix)
  {
    m_canBePrefix = canBePrefix;
    m_wire.reset();
    return *this;
  }
 
  bool
  getMustBeFresh() const noexcept
  {
    return m_mustBeFresh;
  }
 
  Interest&
  setMustBeFresh(bool mustBeFresh)
  {
    m_mustBeFresh = mustBeFresh;
    m_wire.reset();
    return *this;
  }
 
  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(optional<Nonce> nonce);
 
  void
  refreshNonce();
 
  time::milliseconds
  getInterestLifetime() const noexcept
  {
    return m_interestLifetime;
  }
 
  Interest&
  setInterestLifetime(time::milliseconds lifetime);
 
  optional<uint8_t>
  getHopLimit() const noexcept
  {
    return m_hopLimit;
  }
 
  Interest&
  setHopLimit(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);
 
  [[deprecated("use the overload that takes a span<>")]]
  Interest&
  setApplicationParameters(const uint8_t* value, size_t length);
 
  Interest&
  setApplicationParameters(ConstBufferPtr value);
 
  Interest&
  unsetApplicationParameters();
 
  bool
  isSigned() const noexcept;
 
  optional<SignatureInfo>
  getSignatureInfo() const;
 
  Interest&
  setSignatureInfo(const SignatureInfo& info);
 
  Block
  getSignatureValue() const;
 
  Interest&
  setSignatureValue(ConstBufferPtr value);
 
  InputBuffers
  extractSignedRanges() const;
 
public: // ParametersSha256DigestComponent support
  static bool
  getAutoCheckParametersDigest()
  {
    return s_autoCheckParametersDigest;
  }
 
  static void
  setAutoCheckParametersDigest(bool b)
  {
    s_autoCheckParametersDigest = b;
  }
 
  bool
  isParametersDigestValid() const;
 
private:
  void
  setApplicationParametersInternal(Block parameters);
 
  NDN_CXX_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:
  static boost::logic::tribool s_defaultCanBePrefix;
  static bool s_autoCheckParametersDigest;
 
  Name m_name;
  std::vector<Name> m_forwardingHint;
  mutable optional<Nonce> m_nonce;
  time::milliseconds m_interestLifetime;
  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;
};
 
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(Interest);
 
std::ostream&
operator<<(std::ostream& os, const Interest& interest);
 
} // namespace ndn
 
#endif // NDN_CXX_INTEREST_HPP