interest.hpp
Go to the documentation of this file.
1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2 /*
3  * Copyright (c) 2013-2022 Regents of the University of California.
4  *
5  * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
6  *
7  * ndn-cxx library is free software: you can redistribute it and/or modify it under the
8  * terms of the GNU Lesser General Public License as published by the Free Software
9  * Foundation, either version 3 of the License, or (at your option) any later version.
10  *
11  * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
12  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
13  * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
14  *
15  * You should have received copies of the GNU General Public License and GNU Lesser
16  * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
17  * <http://www.gnu.org/licenses/>.
18  *
19  * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
20  */
21 
22 #ifndef NDN_CXX_INTEREST_HPP
23 #define NDN_CXX_INTEREST_HPP
24 
26 #include "ndn-cxx/name.hpp"
30 #include "ndn-cxx/util/time.hpp"
31 
32 #include <array>
33 
34 #include <boost/endian/conversion.hpp>
35 
36 namespace ndn {
37 
38 class Data;
39 
44 
49 class Interest : public PacketBase, public std::enable_shared_from_this<Interest>
50 {
51 public:
52  class Error : public tlv::Error
53  {
54  public:
55  using tlv::Error::Error;
56  };
57 
58  class Nonce final : public std::array<uint8_t, 4>
59  {
60  using Base = std::array<uint8_t, 4>;
61 
62  public:
63  Nonce() = default;
64 
65  // implicit conversion from uint32_t
66  Nonce(uint32_t n) noexcept
67  {
68  boost::endian::native_to_big_inplace(n);
69  std::memcpy(data(), &n, sizeof(n));
70  }
71 
72  Nonce(uint8_t n1, uint8_t n2, uint8_t n3, uint8_t n4) noexcept
73  {
74  data()[0] = n1;
75  data()[1] = n2;
76  data()[2] = n3;
77  data()[3] = n4;
78  }
79 
80  private: // non-member operators
81  // NOTE: the following "hidden friend" operators are available via
82  // argument-dependent lookup only and must be defined inline.
83 
84  friend bool
85  operator==(const Nonce& lhs, const Nonce& rhs) noexcept
86  {
87  return static_cast<const Base&>(lhs) == static_cast<const Base&>(rhs);
88  }
89 
90  friend bool
91  operator!=(const Nonce& lhs, const Nonce& rhs) noexcept
92  {
93  return static_cast<const Base&>(lhs) != static_cast<const Base&>(rhs);
94  }
95 
96  friend std::ostream&
97  operator<<(std::ostream& os, const Nonce& nonce)
98  {
99  printHex(os, nonce, false);
100  return os;
101  }
102  };
103 
110  explicit
111  Interest(const Name& name = {}, time::milliseconds lifetime = DEFAULT_INTEREST_LIFETIME);
112 
118  explicit
119  Interest(const Block& wire);
120 
123  template<encoding::Tag TAG>
124  size_t
125  wireEncode(EncodingImpl<TAG>& encoder) const;
126 
129  const Block&
130  wireEncode() const;
131 
134  void
135  wireDecode(const Block& wire);
136 
139  bool
140  hasWire() const noexcept
141  {
142  return m_wire.hasWire();
143  }
144 
152  std::string
153  toUri() const;
154 
155 public: // matching
161  bool
162  matchesData(const Data& data) const;
163 
168  bool
169  matchesInterest(const Interest& other) const;
170 
171 public: // element access
172  const Name&
173  getName() const noexcept
174  {
175  return m_name;
176  }
177 
182  Interest&
183  setName(const Name& name);
184 
188  bool
189  getCanBePrefix() const noexcept
190  {
191  return m_canBePrefix;
192  }
193 
198  Interest&
199  setCanBePrefix(bool canBePrefix)
200  {
201  m_canBePrefix = canBePrefix;
202  m_wire.reset();
203  return *this;
204  }
205 
209  bool
210  getMustBeFresh() const noexcept
211  {
212  return m_mustBeFresh;
213  }
214 
219  Interest&
220  setMustBeFresh(bool mustBeFresh)
221  {
222  m_mustBeFresh = mustBeFresh;
223  m_wire.reset();
224  return *this;
225  }
226 
227  span<const Name>
228  getForwardingHint() const noexcept
229  {
230  return m_forwardingHint;
231  }
232 
233  Interest&
234  setForwardingHint(std::vector<Name> value);
235 
239  bool
240  hasNonce() const noexcept
241  {
242  return m_nonce.has_value();
243  }
244 
250  Nonce
251  getNonce() const;
252 
258  Interest&
259  setNonce(optional<Nonce> nonce);
260 
267  void
268  refreshNonce();
269 
274  getInterestLifetime() const noexcept
275  {
276  return m_interestLifetime;
277  }
278 
283  Interest&
285 
289  optional<uint8_t>
290  getHopLimit() const noexcept
291  {
292  return m_hopLimit;
293  }
294 
300  Interest&
301  setHopLimit(optional<uint8_t> hopLimit);
302 
306  bool
307  hasApplicationParameters() const noexcept
308  {
309  return !m_parameters.empty();
310  }
311 
319  Block
321  {
322  if (m_parameters.empty())
323  return {};
324  else
325  return m_parameters.front();
326  }
327 
341  Interest&
342  setApplicationParameters(const Block& block);
343 
353  Interest&
354  setApplicationParameters(span<const uint8_t> value);
355 
365  Interest&
367 
376  Interest&
378 
384  bool
385  isSigned() const noexcept;
386 
391  optional<SignatureInfo>
392  getSignatureInfo() const;
393 
397  Interest&
399 
405  Block
406  getSignatureValue() const;
407 
416  Interest&
417  setSignatureValue(span<const uint8_t> value);
418 
427  Interest&
429 
434  InputBuffers
435  extractSignedRanges() const;
436 
437 public: // ParametersSha256DigestComponent support
438  static bool
440  {
441  return s_autoCheckParametersDigest;
442  }
443 
444  static void
446  {
447  s_autoCheckParametersDigest = b;
448  }
449 
457  bool
458  isParametersDigestValid() const;
459 
460 private:
461  Interest&
462  setApplicationParametersInternal(Block parameters);
463 
464  Interest&
465  setSignatureValueInternal(Block sigValue);
466 
467  NDN_CXX_NODISCARD shared_ptr<Buffer>
468  computeParametersDigest() const;
469 
477  void
478  addOrReplaceParametersDigestComponent();
479 
486  static ssize_t
487  findParametersDigestComponent(const Name& name);
488 
489  std::vector<Block>::const_iterator
490  findFirstParameter(uint32_t type) const;
491 
492 private:
493  static bool s_autoCheckParametersDigest;
494 
495  Name m_name;
496  std::vector<Name> m_forwardingHint;
497  mutable optional<Nonce> m_nonce;
498  time::milliseconds m_interestLifetime = DEFAULT_INTEREST_LIFETIME;
499  optional<uint8_t> m_hopLimit;
500  bool m_canBePrefix = false;
501  bool m_mustBeFresh = false;
502 
503  // Stores the "Interest parameters", i.e., all maybe-unrecognized non-critical TLV
504  // elements that appear at the end of the Interest, starting from ApplicationParameters.
505  // If the Interest does not contain any ApplicationParameters TLV, this vector will
506  // be empty. Conversely, if this vector is not empty, the first element will always
507  // be an ApplicationParameters block. All blocks in this vector are covered by the
508  // digest in the ParametersSha256DigestComponent.
509  std::vector<Block> m_parameters;
510 
511  mutable Block m_wire;
512 };
513 
515 
516 std::ostream&
517 operator<<(std::ostream& os, const Interest& interest);
518 
519 } // namespace ndn
520 
521 #endif // NDN_CXX_INTEREST_HPP
#define NDN_CXX_NODISCARD
Definition: backports.hpp:68
Represents a TLV element of the NDN packet format.
Definition: block.hpp:45
bool hasWire() const noexcept
Check if the Block contains a fully encoded wire representation.
Definition: block.hpp:221
void reset() noexcept
Reset the Block to a default-constructed state.
Definition: block.cpp:254
Represents a Data packet.
Definition: data.hpp:39
Nonce(uint32_t n) noexcept
Definition: interest.hpp:66
friend bool operator!=(const Nonce &lhs, const Nonce &rhs) noexcept
Definition: interest.hpp:91
Nonce(uint8_t n1, uint8_t n2, uint8_t n3, uint8_t n4) noexcept
Definition: interest.hpp:72
friend std::ostream & operator<<(std::ostream &os, const Nonce &nonce)
Definition: interest.hpp:97
friend bool operator==(const Nonce &lhs, const Nonce &rhs) noexcept
Definition: interest.hpp:85
Represents an Interest packet.
Definition: interest.hpp:50
Interest & setMustBeFresh(bool mustBeFresh)
Add or remove MustBeFresh element.
Definition: interest.hpp:220
static void setAutoCheckParametersDigest(bool b)
Definition: interest.hpp:445
void wireDecode(const Block &wire)
Decode from wire.
Definition: interest.cpp:150
const Name & getName() const noexcept
Definition: interest.hpp:173
Block getApplicationParameters() const
Get the ApplicationParameters element.
Definition: interest.hpp:320
Interest & setHopLimit(optional< uint8_t > hopLimit)
Set the Interest's hop limit.
Definition: interest.cpp:451
Nonce getNonce() const
Get nonce value.
Definition: interest.cpp:404
Interest & setSignatureValue(span< const uint8_t > value)
Set InterestSignatureValue by copying from a contiguous sequence of bytes.
Definition: interest.cpp:620
span< const Name > getForwardingHint() const noexcept
Definition: interest.hpp:228
bool matchesInterest(const Interest &other) const
Check if this Interest matches other.
Definition: interest.cpp:359
bool hasApplicationParameters() const noexcept
Return whether this Interest has any ApplicationParameters element.
Definition: interest.hpp:307
time::milliseconds getInterestLifetime() const noexcept
Get the Interest's lifetime.
Definition: interest.hpp:274
bool matchesData(const Data &data) const
Check if Interest can be satisfied by data.
Definition: interest.cpp:327
bool getMustBeFresh() const noexcept
Check whether the MustBeFresh element is present.
Definition: interest.hpp:210
Block getSignatureValue() const
Get the InterestSignatureValue element.
Definition: interest.cpp:575
InputBuffers extractSignedRanges() const
Extract ranges of Interest covered by the signature in Packet Specification v0.3.
Definition: interest.cpp:636
bool hasNonce() const noexcept
Check if the Nonce element is present.
Definition: interest.hpp:240
bool getCanBePrefix() const noexcept
Check whether the CanBePrefix element is present.
Definition: interest.hpp:189
void refreshNonce()
Change nonce value.
Definition: interest.cpp:424
optional< uint8_t > getHopLimit() const noexcept
Get the Interest's hop limit.
Definition: interest.hpp:290
Interest & setCanBePrefix(bool canBePrefix)
Add or remove CanBePrefix element.
Definition: interest.hpp:199
bool isSigned() const noexcept
Return whether the Interest is signed.
Definition: interest.cpp:521
optional< SignatureInfo > getSignatureInfo() const
Get the InterestSignatureInfo element.
Definition: interest.cpp:531
Interest & unsetApplicationParameters()
Remove the ApplicationParameters element from this Interest.
Definition: interest.cpp:509
bool isParametersDigestValid() const
Check if the ParametersSha256DigestComponent in the name is valid.
Definition: interest.cpp:671
Interest & setName(const Name &name)
Set the Interest's name.
Definition: interest.cpp:369
Interest & setSignatureInfo(const SignatureInfo &info)
Set the InterestSignatureInfo element.
Definition: interest.cpp:541
Interest & setApplicationParameters(const Block &block)
Set ApplicationParameters from a Block.
Definition: interest.cpp:478
Interest & setForwardingHint(std::vector< Name > value)
Definition: interest.cpp:387
std::string toUri() const
Return a URI-like string that represents the Interest.
Definition: interest.cpp:317
static bool getAutoCheckParametersDigest()
Definition: interest.hpp:439
Interest & setNonce(optional< Nonce > nonce)
Set the Interest's nonce.
Definition: interest.cpp:414
const Block & wireEncode() const
Encode into a Block.
Definition: interest.cpp:134
Interest(const Name &name={}, time::milliseconds lifetime=DEFAULT_INTEREST_LIFETIME)
Construct an Interest with given name and lifetime.
Definition: interest.cpp:45
bool hasWire() const noexcept
Check if this instance has cached wire encoding.
Definition: interest.hpp:140
Interest & setInterestLifetime(time::milliseconds lifetime)
Set the Interest's lifetime.
Definition: interest.cpp:437
Represents an absolute name.
Definition: name.hpp:44
Base class to allow simple management of packet tags.
Definition: packet-base.hpp:32
Represents a SignatureInfo or InterestSignatureInfo TLV element.
Represents an error in TLV encoding or decoding.
Definition: tlv.hpp:54
Error(const char *expectedType, uint32_t actualType)
Definition: tlv.cpp:27
#define NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(ClassName)
boost::chrono::milliseconds milliseconds
Definition: time.hpp:48
@ Data
Definition: tlv.hpp:69
@ Interest
Definition: tlv.hpp:68
@ Nonce
Definition: tlv.hpp:85
Definition: data.cpp:25
void printHex(std::ostream &os, uint64_t num, bool wantUpperCase)
Output the hex representation of num to the output stream os.
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:139
std::ostream & operator<<(std::ostream &os, const Data &data)
Definition: data.cpp:374
const time::milliseconds DEFAULT_INTEREST_LIFETIME
Default value of InterestLifetime.
Definition: interest.hpp:43
SignatureInfo info