NS-3 based Named Data Networking (NDN) simulator
ndnSIM 2.5: NDN, CCN, CCNx, content centric networks
API Documentation
name-component.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_NAME_COMPONENT_HPP
23 #define NDN_CXX_NAME_COMPONENT_HPP
24 
28 #include "ndn-cxx/util/time.hpp"
29 
30 namespace ndn {
31 namespace name {
32 
36 enum class UriFormat {
38  CANONICAL,
40  ALTERNATE,
47 };
48 
52 enum class Convention {
53  MARKER = 1 << 0,
54  TYPED = 1 << 1,
55  EITHER = MARKER | TYPED,
56 };
57 
61 enum : uint8_t {
67 };
68 
75 
79 void
81 
88 
93 void
95 
107 class Component : public Block
108 {
109 public:
110  class Error : public Block::Error
111  {
112  public:
113  using Block::Error::Error;
114  };
115 
116 public: // constructors
121  explicit
122  Component(uint32_t type = tlv::GenericNameComponent);
123 
128  explicit
129  Component(const Block& block);
130 
138  Component(uint32_t type, ConstBufferPtr buffer);
139 
147  explicit
149  : Component(tlv::GenericNameComponent, std::move(buffer))
150  {
151  }
152 
156  Component(uint32_t type, span<const uint8_t> value);
157 
161  explicit
162  Component(span<const uint8_t> buffer)
163  : Component(tlv::GenericNameComponent, buffer)
164  {
165  }
166 
172  [[deprecated("use the constructor that takes a span<>")]]
173  Component(uint32_t type, const uint8_t* value, size_t count)
174  : Component(type, {value, count})
175  {
176  }
177 
182  [[deprecated("use the constructor that takes a span<>")]]
183  Component(const uint8_t* value, size_t count)
184  : Component(tlv::GenericNameComponent, {value, count})
185  {
186  }
187 
196  template<class Iterator>
197  Component(uint32_t type, Iterator first, Iterator last)
198  : Block(makeBinaryBlock(type, first, last))
199  {
200  }
201 
205  template<class Iterator>
206  Component(Iterator first, Iterator last)
207  : Component(tlv::GenericNameComponent, first, last)
208  {
209  }
210 
216  explicit
217  Component(const char* str);
218 
224  explicit
225  Component(const std::string& str);
226 
227 public: // encoding and URI
231  template<encoding::Tag TAG>
232  size_t
233  wireEncode(EncodingImpl<TAG>& encoder) const;
234 
238  const Block&
239  wireEncode() const;
240 
244  void
245  wireDecode(const Block& wire);
246 
254  static Component
255  fromEscapedString(const char* input, size_t beginOffset, size_t endOffset)
256  {
257  return fromEscapedString(std::string(input + beginOffset, input + endOffset));
258  }
259 
264  static Component
265  fromEscapedString(const char* input)
266  {
267  return fromEscapedString(std::string(input));
268  }
269 
274  static Component
275  fromEscapedString(const std::string& input);
276 
281  void
282  toUri(std::ostream& os, UriFormat format = UriFormat::DEFAULT) const;
283 
288  std::string
289  toUri(UriFormat format = UriFormat::DEFAULT) const;
290 
291 public: // naming conventions
296  bool
297  isNumber() const;
298 
304  bool
305  isNumberWithMarker(uint8_t marker) const;
306 
311  bool
312  isSegment() const;
313 
318  bool
319  isByteOffset() const;
320 
325  bool
326  isVersion() const;
327 
332  bool
333  isTimestamp() const;
334 
339  bool
340  isSequenceNumber() const;
341 
347  uint64_t
348  toNumber() const;
349 
361  uint64_t
362  toNumberWithMarker(uint8_t marker) const;
363 
369  uint64_t
370  toSegment() const;
371 
377  uint64_t
378  toByteOffset() const;
379 
385  uint64_t
386  toVersion() const;
387 
394  toTimestamp() const;
395 
401  uint64_t
402  toSequenceNumber() const;
403 
412  static Component
413  fromNumber(uint64_t number, uint32_t type = tlv::GenericNameComponent);
414 
432  static Component
433  fromNumberWithMarker(uint8_t marker, uint64_t number);
434 
439  static Component
440  fromSegment(uint64_t segmentNo);
441 
446  static Component
447  fromByteOffset(uint64_t offset);
448 
453  static Component
454  fromVersion(uint64_t version);
455 
460  static Component
461  fromTimestamp(const time::system_clock::time_point& timePoint);
462 
467  static Component
468  fromSequenceNumber(uint64_t seqNo);
469 
470 public: // commonly used TLV-TYPEs
475  bool
476  isGeneric() const noexcept
477  {
478  return type() == tlv::GenericNameComponent;
479  }
480 
486  bool
487  isImplicitSha256Digest() const;
488 
493  [[deprecated("use one of the name::Component constructors")]]
494  static Component
495  fromImplicitSha256Digest(ConstBufferPtr digest);
496 
501  [[deprecated("use one of the name::Component constructors")]]
502  static Component
503  fromImplicitSha256Digest(span<const uint8_t> digest);
504 
510  bool
511  isParametersSha256Digest() const;
512 
517  [[deprecated("use one of the name::Component constructors")]]
518  static Component
519  fromParametersSha256Digest(ConstBufferPtr digest);
520 
525  [[deprecated("use one of the name::Component constructors")]]
526  static Component
527  fromParametersSha256Digest(span<const uint8_t> digest);
528 
533  bool
534  isKeyword() const noexcept
535  {
536  return type() == tlv::KeywordNameComponent;
537  }
538 
539 public: // comparison
540  NDN_CXX_NODISCARD bool
541  empty() const
542  {
543  return value_size() == 0;
544  }
545 
552  bool
553  equals(const Component& other) const;
554 
565  int
566  compare(const Component& other) const;
567 
593  Component
594  getSuccessor() const;
595 
596 private:
600  void
601  ensureValid() const;
602 
603 private: // non-member operators
604  // NOTE: the following "hidden friend" operators are available via
605  // argument-dependent lookup only and must be defined inline.
606 
607  friend bool
608  operator==(const Component& lhs, const Component& rhs)
609  {
610  return lhs.equals(rhs);
611  }
612 
613  friend bool
614  operator!=(const Component& lhs, const Component& rhs)
615  {
616  return !lhs.equals(rhs);
617  }
618 
619  friend bool
620  operator<(const Component& lhs, const Component& rhs)
621  {
622  return lhs.compare(rhs) < 0;
623  }
624 
625  friend bool
626  operator<=(const Component& lhs, const Component& rhs)
627  {
628  return lhs.compare(rhs) <= 0;
629  }
630 
631  friend bool
632  operator>(const Component& lhs, const Component& rhs)
633  {
634  return lhs.compare(rhs) > 0;
635  }
636 
637  friend bool
638  operator>=(const Component& lhs, const Component& rhs)
639  {
640  return lhs.compare(rhs) >= 0;
641  }
642 
643  friend std::ostream&
644  operator<<(std::ostream& os, const Component& component)
645  {
646  component.toUri(os);
647  return os;
648  }
649 
650  // !!! NOTE TO IMPLEMENTOR !!!
651  //
652  // This class MUST NOT contain any data fields.
653  // Block can be reinterpret_cast'ed as Component type.
654 };
655 
657 
658 } // namespace name
659 } // namespace ndn
660 
661 #endif // NDN_CXX_NAME_COMPONENT_HPP
void setConventionDecoding(Convention convention)
Set which Naming Conventions style(s) to accept while decoding.
Same as UriFormat::CANONICAL, unless NDN_NAME_ALT_URI environment variable is set to &#39;1&#39;...
Copyright (c) 2011-2015 Regents of the University of California.
UriFormat
Format used for the URI representation of a name.
Component(uint32_t type, Iterator first, Iterator last)
Construct a NameComponent of TLV-TYPE type, copying TLV-VALUE from a range.
boost::chrono::time_point< system_clock > time_point
Definition: time.hpp:200
std::ostream & operator<<(std::ostream &os, const Data &data)
Definition: data.cpp:376
Same as UriFormat::ALTERNATE, unless NDN_NAME_ALT_URI environment variable is set to &#39;0&#39;...
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(Component)
STL namespace.
NDN_CXX_NODISCARD bool empty() const
void setConventionEncoding(Convention convention)
Set which Naming Conventions style to use while encoding.
Represents a TLV element of the NDN packet format.
Definition: block.hpp:44
int compare(const Component &other) const
Compare this to the other Component using NDN canonical ordering.
static Component fromEscapedString(const char *input)
Decode NameComponent from a URI component.
Typed name components (revision 3)
bool isGeneric() const noexcept
Check if the component is a GenericNameComponent.
Use the library&#39;s default format; currently equivalent to UriFormat::ENV_OR_ALTERNATE.
Convention getConventionDecoding()
Return which Naming Conventions style(s) to accept while decoding.
optional_constexpr bool operator<=(optional< T > const &x, optional< U > const &y)
friend bool operator>=(const Component &lhs, const Component &rhs)
Common includes and macros used throughout the library.
friend bool operator>(const Component &lhs, const Component &rhs)
Component(uint32_t type, const uint8_t *value, size_t count)
Construct a NameComponent of TLV-TYPE type, copying count bytes at value as TLV-VALUE.
static Component fromEscapedString(const char *input, size_t beginOffset, size_t endOffset)
Decode NameComponent from a URI component.
#define NDN_CXX_NODISCARD
Definition: backports.hpp:68
bool equals(const Component &other) const
Check if this is the same component as other.
friend bool operator!=(const Component &lhs, const Component &rhs)
Always prefer the alternate format when available.
Block makeBinaryBlock(uint32_t type, span< const uint8_t > value)
Create a TLV block copying the TLV-VALUE from a byte range.
Component(ConstBufferPtr buffer)
Construct a GenericNameComponent, using TLV-VALUE from buffer.
bool isKeyword() const noexcept
Check if the component is a KeywordNameComponent.
Represents a name component.
Component(Iterator first, Iterator last)
Construct a GenericNameComponent, copying TLV-VALUE from a range.
Component(span< const uint8_t > buffer)
Construct a GenericNameComponent, copying the TLV-VALUE from buffer.
Always use <type-number>=<percent-encoded-value> format.
Component(const uint8_t *value, size_t count)
Construct a GenericNameComponent, copying count bytes at value as TLV-VALUE.
Component markers (revision 1)
Convention getConventionEncoding()
Return which Naming Conventions style to use while encoding.
Convention
Identify a style of NDN Naming Conventions.
bool operator<(const ReadvertisedRoute &lhs, const ReadvertisedRoute &rhs)
friend bool operator==(const Component &lhs, const Component &rhs)
void toUri(std::ostream &os, UriFormat format=UriFormat::DEFAULT) const
Write *this to the output stream, escaping characters according to the NDN URI format.
Error(const char *expectedType, uint32_t actualType)
Definition: tlv.cpp:27
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:139