block.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  * @author Alexander Afanasyev <http://lasr.cs.ucla.edu/afanasyev/index.html>
22  */
23 
24 #ifndef NDN_CXX_ENCODING_BLOCK_HPP
25 #define NDN_CXX_ENCODING_BLOCK_HPP
26 
29 #include "ndn-cxx/encoding/tlv.hpp"
30 #include "ndn-cxx/util/span.hpp"
31 
32 namespace boost {
33 namespace asio {
34 class const_buffer;
35 } // namespace asio
36 } // namespace boost
37 
38 namespace ndn {
39 
44 class Block
45 {
46 public:
47  using value_type = Buffer::value_type;
48  using const_iterator = Buffer::const_iterator;
49  using element_container = std::vector<Block>;
50  using element_iterator = element_container::iterator;
51  using element_const_iterator = element_container::const_iterator;
52 
53  class Error : public tlv::Error
54  {
55  public:
56  using tlv::Error::Error;
57  };
58 
59 public: // construction, assignment
63  Block();
64 
67  Block(const Block&);
68 
71  Block&
72  operator=(const Block&);
73 
76  Block(Block&&) noexcept;
77 
80  Block&
81  operator=(Block&&) noexcept;
82 
89  explicit
90  Block(span<const uint8_t> buffer);
91 
96  explicit
97  Block(const EncodingBuffer& buffer);
98 
104  explicit
105  Block(const ConstBufferPtr& buffer);
106 
116  bool verifyLength = true);
117 
127  bool verifyLength = true);
128 
137  Block(ConstBufferPtr buffer, uint32_t type,
139  Buffer::const_iterator valueBegin, Buffer::const_iterator valueEnd);
140 
144  explicit
145  Block(uint32_t type);
146 
151  Block(uint32_t type, ConstBufferPtr value);
152 
157  Block(uint32_t type, const Block& value);
158 
165  NDN_CXX_NODISCARD static std::tuple<bool, Block>
166  fromBuffer(ConstBufferPtr buffer, size_t offset = 0);
167 
175  NDN_CXX_NODISCARD static std::tuple<bool, Block>
176  fromBuffer(span<const uint8_t> buffer);
177 
182  static Block
183  fromStream(std::istream& is);
184 
185 public: // wire format
191  bool
192  isValid() const noexcept
193  {
194  return m_type != tlv::Invalid;
195  }
196 
204  void
205  reset() noexcept;
206 
212  void
213  resetWire() noexcept;
214 
220  bool
221  hasWire() const noexcept
222  {
223  return m_buffer != nullptr && m_begin != m_end;
224  }
225 
230  begin() const;
231 
236  end() const;
237 
243  const uint8_t*
244  data() const;
245 
249  const uint8_t*
250  wire() const
251  {
252  return data();
253  }
254 
260  size_t
261  size() const;
262 
266  getBuffer() const
267  {
268  return m_buffer;
269  }
270 
271 public: // type and value
276  uint32_t
277  type() const noexcept
278  {
279  return m_type;
280  }
281 
290  bool
291  hasValue() const noexcept
292  {
293  return m_buffer != nullptr;
294  }
295 
301  value_begin() const noexcept
302  {
303  return m_valueBegin;
304  }
305 
311  value_end() const noexcept
312  {
313  return m_valueEnd;
314  }
315 
320  size_t
321  value_size() const noexcept
322  {
323  return hasValue() ? static_cast<size_t>(m_valueEnd - m_valueBegin) : 0;
324  }
325 
329  span<const uint8_t>
330  value_bytes() const noexcept
331  {
332  if (hasValue())
333  return {m_valueBegin, m_valueEnd};
334  else
335  return {};
336  }
337 
342  const uint8_t*
343  value() const noexcept;
344 
349  Block
350  blockFromValue() const;
351 
352 public: // sub-elements
360  void
361  parse() const;
362 
366  void
367  encode();
368 
373  const Block&
374  get(uint32_t type) const;
375 
382  find(uint32_t type) const;
383 
388  void
389  remove(uint32_t type);
390 
394  erase(element_const_iterator position);
395 
400 
404  void
405  push_back(const Block& element);
406 
410  void
411  push_back(Block&& element);
412 
419  insert(element_const_iterator pos, const Block& element);
420 
425  const element_container&
426  elements() const noexcept
427  {
428  return m_elements;
429  }
430 
435  elements_begin() const noexcept
436  {
437  return m_elements.begin();
438  }
439 
444  elements_end() const noexcept
445  {
446  return m_elements.end();
447  }
448 
452  size_t
453  elements_size() const noexcept
454  {
455  return m_elements.size();
456  }
457 
458 public: // misc
462  operator boost::asio::const_buffer() const;
463 
464 private:
467  size_t
468  encode(EncodingEstimator& estimator) const;
469 
472  size_t
473  encodeValue(EncodingEstimator& estimator) const;
474 
479  size_t
480  encode(EncodingBuffer& encoder);
481 
482 protected:
491  shared_ptr<const Buffer> m_buffer;
492  Buffer::const_iterator m_begin;
493  Buffer::const_iterator m_end;
494 
495  Buffer::const_iterator m_valueBegin;
496  Buffer::const_iterator m_valueEnd;
497 
498  uint32_t m_type = tlv::Invalid;
499 
505  size_t m_size = 0;
506 
513 
524  friend std::ostream&
525  operator<<(std::ostream& os, const Block& block);
526 };
527 
528 inline
529 Block::Block(Block&&) noexcept = default;
530 
531 inline Block&
532 Block::operator=(Block&&) noexcept = default;
533 
537 bool
538 operator==(const Block& lhs, const Block& rhs) noexcept;
539 
540 inline bool
541 operator!=(const Block& lhs, const Block& rhs) noexcept
542 {
543  return !(lhs == rhs);
544 }
545 
559 Block
560 operator ""_block(const char* input, std::size_t len);
561 
562 } // namespace ndn
563 
564 #endif // NDN_CXX_ENCODING_BLOCK_HPP
#define NDN_CXX_NODISCARD
Definition: backports.hpp:68
Represents a TLV element of the NDN packet format.
Definition: block.hpp:45
element_const_iterator elements_begin() const noexcept
Equivalent to elements().begin().
Definition: block.hpp:435
element_container::const_iterator element_const_iterator
Definition: block.hpp:51
const uint8_t * data() const
Return a raw pointer to the beginning of the encoded wire.
Definition: block.cpp:285
Buffer::const_iterator const_iterator
Definition: block.hpp:48
const_iterator value_end() const noexcept
Get end iterator of TLV-VALUE.
Definition: block.hpp:311
uint32_t m_type
TLV-TYPE.
Definition: block.hpp:498
element_const_iterator find(uint32_t type) const
Find the first sub-element of the specified TLV-TYPE.
Definition: block.cpp:424
Buffer::value_type value_type
Definition: block.hpp:47
const_iterator begin() const
Get begin iterator of encoded wire.
Definition: block.cpp:267
Block blockFromValue() const
Return a new Block constructed from the TLV-VALUE of this Block.
Definition: block.cpp:312
element_iterator erase(element_const_iterator position)
Erase a sub-element.
Definition: block.cpp:441
friend std::ostream & operator<<(std::ostream &os, const Block &block)
Print block to os.
Definition: block.cpp:492
size_t elements_size() const noexcept
Equivalent to elements().size().
Definition: block.hpp:453
const element_container & elements() const noexcept
Get container of sub-elements.
Definition: block.hpp:426
void remove(uint32_t type)
Remove all sub-elements of the specified TLV-TYPE.
Definition: block.cpp:431
size_t size() const
Return the size of the encoded wire, i.e., of the whole TLV.
Definition: block.cpp:294
element_const_iterator elements_end() const noexcept
Equivalent to elements().end().
Definition: block.hpp:444
bool hasWire() const noexcept
Check if the Block contains a fully encoded wire representation.
Definition: block.hpp:221
size_t m_size
Total size including Type-Length-Value.
Definition: block.hpp:505
Buffer::const_iterator m_valueEnd
Definition: block.hpp:496
void resetWire() noexcept
Reset wire buffer but keep TLV-TYPE and sub-elements (if any)
Definition: block.cpp:260
element_container m_elements
Contains the sub-elements.
Definition: block.hpp:512
static std::tuple< bool, Block > fromBuffer(ConstBufferPtr buffer, size_t offset=0)
Try to parse Block from a wire buffer.
Definition: block.cpp:162
void push_back(const Block &element)
Append a sub-element.
Definition: block.cpp:455
Block(Block &&) noexcept
Move constructor.
Block & operator=(const Block &)
Copy assignment operator.
Buffer::const_iterator m_end
Definition: block.hpp:493
Buffer::const_iterator m_valueBegin
Definition: block.hpp:495
Block(const Block &)
Copy constructor.
const uint8_t * wire() const
Definition: block.hpp:250
ConstBufferPtr getBuffer() const
Get underlying buffer.
Definition: block.hpp:266
bool hasValue() const noexcept
Check if the Block has a non-empty TLV-VALUE.
Definition: block.hpp:291
bool isValid() const noexcept
Check if the Block is valid.
Definition: block.hpp:192
element_container::iterator element_iterator
Definition: block.hpp:50
void encode()
Encode sub-elements into TLV-VALUE.
Definition: block.cpp:351
span< const uint8_t > value_bytes() const noexcept
Return a read-only view of TLV-VALUE as a contiguous range of bytes.
Definition: block.hpp:330
const_iterator end() const
Get end iterator of encoded wire.
Definition: block.cpp:276
uint32_t type() const noexcept
Return the TLV-TYPE of the Block.
Definition: block.hpp:277
static Block fromStream(std::istream &is)
Parse Block from an input stream.
Definition: block.cpp:220
void reset() noexcept
Reset the Block to a default-constructed state.
Definition: block.cpp:254
Buffer::const_iterator m_begin
Definition: block.hpp:492
shared_ptr< const Buffer > m_buffer
Underlying buffer storing TLV-VALUE and possibly TLV-TYPE and TLV-LENGTH fields.
Definition: block.hpp:491
std::vector< Block > element_container
Definition: block.hpp:49
void parse() const
Parse TLV-VALUE into sub-elements.
Definition: block.cpp:324
const_iterator value_begin() const noexcept
Get begin iterator of TLV-VALUE.
Definition: block.hpp:301
const Block & get(uint32_t type) const
Return the first sub-element of the specified TLV-TYPE.
Definition: block.cpp:412
size_t value_size() const noexcept
Return the size of TLV-VALUE, i.e., the TLV-LENGTH.
Definition: block.hpp:321
Block()
Create an invalid Block.
element_iterator insert(element_const_iterator pos, const Block &element)
Insert a sub-element.
Definition: block.cpp:469
const uint8_t * value() const noexcept
Return a raw pointer to the beginning of TLV-VALUE.
Definition: block.cpp:306
General-purpose automatically managed/resized buffer.
Definition: buffer.hpp:42
Represents an error in TLV encoding or decoding.
Definition: tlv.hpp:54
Error(const char *expectedType, uint32_t actualType)
Definition: tlv.cpp:27
EncodingImpl< EstimatorTag > EncodingEstimator
EncodingImpl< EncoderTag > EncodingBuffer
@ Invalid
Definition: tlv.hpp:67
Definition: data.cpp:25
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:139