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-2018 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_NAME_COMPONENT_HPP
23 #define NDN_NAME_COMPONENT_HPP
24 
25 #include "common.hpp"
26 #include "encoding/block.hpp"
28 #include "util/time.hpp"
29 
30 namespace ndn {
31 namespace name {
32 
34 static const uint8_t SEGMENT_MARKER = 0x00;
36 static const uint8_t SEGMENT_OFFSET_MARKER = 0xFB;
38 static const uint8_t VERSION_MARKER = 0xFD;
40 static const uint8_t TIMESTAMP_MARKER = 0xFC;
42 static const uint8_t SEQUENCE_NUMBER_MARKER = 0xFE;
43 
50 class Component : public Block
51 {
52 public:
53  class Error : public Block::Error
54  {
55  public:
56  explicit
57  Error(const std::string& what)
58  : Block::Error(what)
59  {
60  }
61  };
62 
63 public: // constructors
68  explicit
70 
77  Component(const Block& wire);
78 
86  Component(uint32_t type, ConstBufferPtr buffer);
87 
95  explicit
97  : Component(tlv::GenericNameComponent, std::move(buffer))
98  {
99  }
100 
104  Component(uint32_t type, const Buffer& buffer)
105  : Component(type, buffer.data(), buffer.size())
106  {
107  }
108 
112  explicit
113  Component(const Buffer& buffer)
114  : Component(tlv::GenericNameComponent, buffer)
115  {
116  }
117 
122  Component(uint32_t type, const uint8_t* value, size_t count);
123 
127  Component(const uint8_t* value, size_t count)
128  : Component(tlv::GenericNameComponent, value, count)
129  {
130  }
131 
140  template<class Iterator>
141  Component(uint32_t type, Iterator first, Iterator last)
142  : Block(makeBinaryBlock(type, first, last))
143  {
144  }
145 
149  template<class Iterator>
150  Component(Iterator first, Iterator last)
151  : Component(tlv::GenericNameComponent, first, last)
152  {
153  }
154 
160  explicit
161  Component(const char* str);
162 
168  explicit
169  Component(const std::string& str);
170 
171 public: // encoding and URI
175  template<encoding::Tag TAG>
176  size_t
177  wireEncode(EncodingImpl<TAG>& encoder) const;
178 
182  const Block&
183  wireEncode() const;
184 
188  void
189  wireDecode(const Block& wire);
190 
198  static Component
199  fromEscapedString(const char* input, size_t beginOffset, size_t endOffset)
200  {
201  return fromEscapedString(std::string(input + beginOffset, input + endOffset));
202  }
203 
208  static Component
209  fromEscapedString(const char* input)
210  {
211  return fromEscapedString(std::string(input));
212  }
213 
218  static Component
219  fromEscapedString(std::string input);
220 
228  void
229  toUri(std::ostream& os) const;
230 
238  std::string
239  toUri() const;
240 
241 public: // naming conventions
246  bool
247  isNumber() const;
248 
253  bool
254  isNumberWithMarker(uint8_t marker) const;
255 
260  bool
261  isVersion() const;
262 
267  bool
268  isSegment() const;
269 
274  bool
275  isSegmentOffset() const;
276 
281  bool
282  isTimestamp() const;
283 
288  bool
289  isSequenceNumber() const;
290 
298  uint64_t
299  toNumber() const;
300 
311  uint64_t
312  toNumberWithMarker(uint8_t marker) const;
313 
322  uint64_t
323  toVersion() const;
324 
333  uint64_t
334  toSegment() const;
335 
344  uint64_t
345  toSegmentOffset() const;
346 
356  toTimestamp() const;
357 
366  uint64_t
367  toSequenceNumber() const;
368 
377  static Component
378  fromNumber(uint64_t number);
379 
401  static Component
402  fromNumberWithMarker(uint8_t marker, uint64_t number);
403 
409  static Component
410  fromVersion(uint64_t version);
411 
417  static Component
418  fromSegment(uint64_t segmentNo);
419 
425  static Component
426  fromSegmentOffset(uint64_t offset);
427 
433  static Component
435 
441  static Component
442  fromSequenceNumber(uint64_t seqNo);
443 
444 public: // commonly used TLV-TYPEs
448  bool
449  isGeneric() const;
450 
454  bool
455  isImplicitSha256Digest() const;
456 
460  static Component
462 
466  static Component
467  fromImplicitSha256Digest(const uint8_t* digest, size_t digestSize);
468 
469 public: // operators
470  bool
471  empty() const
472  {
473  return value_size() == 0;
474  }
475 
482  bool
483  equals(const Component& other) const;
484 
495  int
496  compare(const Component& other) const;
497 
504  bool
505  operator==(const Component& other) const
506  {
507  return equals(other);
508  }
509 
515  bool
516  operator!=(const Component& other) const
517  {
518  return !equals(other);
519  }
520 
527  bool
528  operator<=(const Component& other) const
529  {
530  return compare(other) <= 0;
531  }
532 
539  bool
540  operator<(const Component& other) const
541  {
542  return compare(other) < 0;
543  }
544 
551  bool
552  operator>=(const Component& other) const
553  {
554  return compare(other) >= 0;
555  }
556 
563  bool
564  operator>(const Component& other) const
565  {
566  return compare(other) > 0;
567  }
568 
569  Component
570  getSuccessor() const;
571 
572 private:
579  void
580  ensureValid() const;
581 
582  // !!! NOTE TO IMPLEMENTOR !!!
583  //
584  // This class MUST NOT contain any data fields.
585  // Block can be reinterpret_cast'ed as Component type.
586 };
587 
589 
590 inline std::ostream&
591 operator<<(std::ostream& os, const Component& component)
592 {
593  component.toUri(os);
594  return os;
595 }
596 
597 } // namespace name
598 } // namespace ndn
599 
600 #endif // NDN_NAME_COMPONENT_HPP
static Component fromNumber(uint64_t number)
Create a component encoded as nonNegativeInteger.
static Component fromSequenceNumber(uint64_t seqNo)
Create sequence number component using NDN naming conventions.
bool isGeneric() const
Check if the component is GenericComponent.
Copyright (c) 2013-2017 Regents of the University of California.
Definition: common.hpp:66
uint64_t toSegmentOffset() const
Interpret as segment offset component using NDN naming conventions.
bool isTimestamp() const
Check if the component is timestamp per NDN naming conventions.
static Component fromNumberWithMarker(uint8_t marker, uint64_t number)
Create a component encoded as NameComponentWithMarker.
int compare(const Component &other) const
Compare this to the other Component using NDN canonical ordering.
const Block & wireEncode() const
Encode to a wire format.
std::string toUri() const
Convert *this by escaping characters according to the NDN URI Scheme.
Component(uint32_t type, Iterator first, Iterator last)
Construct a NameComponent of TLV-TYPE type, copying TLV-VALUE from a range.
bool operator==(const Component &other) const
Check if this is the same component as other.
Component(uint32_t type=tlv::GenericNameComponent)
Construct a NameComponent of TLV-TYPE type, using empty TLV-VALUE.
time::system_clock::TimePoint toTimestamp() const
Interpret as timestamp component using NDN naming conventions.
bool isNumberWithMarker(uint8_t marker) const
Check if the component is NameComponentWithMarker per NDN naming conventions.
bool isSequenceNumber() const
Check if the component is sequence number per NDN naming conventions.
static Component fromTimestamp(const time::system_clock::TimePoint &timePoint)
Create sequence number component using NDN naming conventions.
STL namespace.
friend std::ostream & operator<<(std::ostream &os, const Block &block)
Print block to os.
Definition: block.cpp:521
Represents a TLV element of NDN packet format.
Definition: block.hpp:42
bool operator<(const Component &other) const
Check if the *this is less than the other in NDN canonical ordering.
static Component fromEscapedString(const char *input)
Decode NameComponent from a URI component.
#define NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(ClassName)
static Component fromSegmentOffset(uint64_t offset)
Create segment offset component using NDN naming conventions.
Component(uint32_t type, const Buffer &buffer)
Construct a NameComponent of TLV-TYPE type, copying TLV-VALUE from buffer.
static const uint8_t SEGMENT_OFFSET_MARKER
Segment offset marker for NDN naming conventions.
import common constructs for ndn-cxx library internal use
uint64_t toNumberWithMarker(uint8_t marker) const
Interpret this name component as NameComponentWithMarker.
size_t size() const
Get size of encoded wire, including Type-Length-Value.
Definition: block.cpp:301
static Component fromSegment(uint64_t segmentNo)
Create segment number component using NDN naming conventions.
bool isSegment() const
Check if the component is segment number per NDN naming conventions.
bool isVersion() const
Check if the component is version per NDN naming conventions.
uint64_t toVersion() const
Interpret as version component using NDN naming conventions.
uint64_t toSegment() const
Interpret as segment number component using NDN naming conventions.
static Component fromEscapedString(const char *input, size_t beginOffset, size_t endOffset)
Decode NameComponent from a URI component.
Block makeBinaryBlock(uint32_t type, const uint8_t *value, size_t length)
Create a TLV block copying TLV-VALUE from raw buffer.
bool operator<=(const Component &other) const
Check if the *this is less than or equal to the other in NDN canonical ordering.
void toUri(std::ostream &os) const
Write *this to the output stream, escaping characters according to the NDN URI Scheme.
bool operator!=(const Component &other) const
Check if this is not the same component as other.
Component(const Buffer &buffer)
Construct a GenericNameComponent, copying TLV-VALUE from buffer.
size_t value_size() const
Get size of TLV-VALUE aka TLV-LENGTH.
Definition: block.cpp:319
Component(ConstBufferPtr buffer)
Construct a GenericNameComponent, using TLV-VALUE from buffer.
uint32_t type() const
Get TLV-TYPE.
Definition: block.hpp:235
Component getSuccessor() const
static const uint8_t VERSION_MARKER
Version marker for NDN naming conventions.
time_point TimePoint
Definition: time.hpp:196
Represents a name component.
static Component fromImplicitSha256Digest(const ConstBufferPtr &digest)
Create ImplicitSha256DigestComponent component.
void wireDecode(const Block &wire)
Decode from the wire format.
Component(Iterator first, Iterator last)
Construct a GenericNameComponent, copying TLV-VALUE from a range.
static const uint8_t SEGMENT_MARKER
Segment marker for NDN naming conventions.
bool isNumber() const
Check if the component is nonNegativeInteger.
const uint8_t * wire() const
Get pointer to encoded wire.
Definition: block.cpp:292
Component(const uint8_t *value, size_t count)
Construct a GenericNameComponent, copying count bytes at value as TLV-VALUE.
const uint8_t * value() const
Get pointer to TLV-VALUE.
Definition: block.cpp:313
static Component fromVersion(uint64_t version)
Create version component using NDN naming conventions.
bool isSegmentOffset() const
Check if the component is segment offset per NDN naming conventions.
static const uint8_t SEQUENCE_NUMBER_MARKER
Sequence number marker for NDN naming conventions.
uint64_t toSequenceNumber() const
Interpret as sequence number component using NDN naming conventions.
bool equals(const Component &other) const
Check if this is the same component as other.
uint64_t toNumber() const
Interpret this name component as nonNegativeInteger.
static const uint8_t TIMESTAMP_MARKER
Timestamp marker for NDN naming conventions.
General-purpose automatically managed/resized buffer.
Definition: buffer.hpp:40
bool operator>=(const Component &other) const
Check if the *this is greater or equal than the other in NDN canonical ordering.
bool operator>(const Component &other) const
Check if the *this is greater than the other in NDN canonical ordering.
bool isImplicitSha256Digest() const
Check if the component is ImplicitSha256DigestComponent.
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:89
Error(const std::string &what)