blob: 3691ed9fc0cb50bd8ce6ae83818b34f3eb7393f8 [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07002/**
Alexander Afanasyevaf99f462015-01-19 21:43:09 -08003 * Copyright (c) 2013-2015 Regents of the University of California.
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -08004 *
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07005 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -08006 *
Alexander Afanasyevc169a812014-05-20 20:37:29 -04007 * 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.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070020 *
21 * @author Alexander Afanasyev <http://lasr.cs.ucla.edu/afanasyev/index.html>
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080022 */
23
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070024#ifndef NDN_ENCODING_BLOCK_HPP
25#define NDN_ENCODING_BLOCK_HPP
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080026
Alexander Afanasyev19508852014-01-29 01:01:51 -080027#include "../common.hpp"
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080028
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080029#include "buffer.hpp"
30#include "tlv.hpp"
31
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -070032namespace boost {
33namespace asio {
34class const_buffer;
35} // namespace asio
36} // namespace boost
37
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080038namespace ndn {
39
Alexander Afanasyev233750e2014-02-16 00:50:07 -080040template<bool> class EncodingImpl;
41typedef EncodingImpl<true> EncodingBuffer;
42
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070043/** @brief Class representing a wire element of NDN-TLV packet format
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080044 */
45class Block
46{
47public:
Alexander Afanasyev8ea763d2014-02-06 20:32:52 -080048 typedef std::vector<Block> element_container;
49 typedef element_container::iterator element_iterator;
50 typedef element_container::const_iterator element_const_iterator;
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080051
Steve DiBenedetto54ce6682014-07-22 13:22:57 -060052 class Error : public tlv::Error
Alexander Afanasyev937aa782014-03-21 13:17:57 -070053 {
Alexander Afanasyeva465e972014-03-22 17:21:49 -070054 public:
55 explicit
56 Error(const std::string& what)
Steve DiBenedetto54ce6682014-07-22 13:22:57 -060057 : tlv::Error(what)
Alexander Afanasyeva465e972014-03-22 17:21:49 -070058 {
59 }
Alexander Afanasyev937aa782014-03-21 13:17:57 -070060 };
61
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070062public: // constructor, creation, assignment
63 /** @brief Create an empty Block
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080064 */
65 Block();
66
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070067 /** @brief Create a Block based on EncodingBuffer object
Alexander Afanasyev15151312014-02-16 00:53:51 -080068 */
69 explicit
70 Block(const EncodingBuffer& buffer);
Alexander Afanasyev937aa782014-03-21 13:17:57 -070071
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070072 /** @brief Create a Block from the raw buffer with Type-Length parsing
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080073 */
Alexander Afanasyev197e5652014-06-13 16:56:31 -070074 explicit
Alexander Afanasyev937aa782014-03-21 13:17:57 -070075 Block(const ConstBufferPtr& buffer);
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080076
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070077 /** @brief Create a Block from a buffer, directly specifying boundaries
78 * of the block within the buffer
Alexander Afanasyev187bc482014-02-06 15:04:04 -080079 *
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070080 * This overload will automatically detect type and position of the value within the block
Alexander Afanasyev187bc482014-02-06 15:04:04 -080081 */
Alexander Afanasyev937aa782014-03-21 13:17:57 -070082 Block(const ConstBufferPtr& buffer,
83 const Buffer::const_iterator& begin, const Buffer::const_iterator& end,
Alexander Afanasyev5964fb72014-02-18 12:42:45 -080084 bool verifyLength = true);
Alexander Afanasyev937aa782014-03-21 13:17:57 -070085
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070086 /** @brief Create a Block from the raw buffer with Type-Length parsing
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080087 */
Alexander Afanasyev937aa782014-03-21 13:17:57 -070088 Block(const uint8_t* buffer, size_t maxlength);
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080089
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070090 /** @brief Create a Block from the raw buffer with Type-Length parsing
91 */
Alexander Afanasyev937aa782014-03-21 13:17:57 -070092 Block(const void* buffer, size_t maxlength);
Yingdi Yu27158392014-01-20 13:04:20 -080093
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070094 /** @brief Create a Block from the wire buffer (no parsing)
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080095 *
Junxiao Shi81a6c5d2014-11-30 00:14:42 -070096 * This overload does not do any parsing
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080097 */
Alexander Afanasyev937aa782014-03-21 13:17:57 -070098 Block(const ConstBufferPtr& wire,
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -080099 uint32_t type,
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700100 const Buffer::const_iterator& begin, const Buffer::const_iterator& end,
101 const Buffer::const_iterator& valueBegin, const Buffer::const_iterator& valueEnd);
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800102
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700103 /** @brief Create Block of a specific type with empty wire buffer
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800104 */
Alexander Afanasyevf42ce132014-01-07 13:32:30 -0800105 explicit
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800106 Block(uint32_t type);
107
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700108 /** @brief Create a Block of a specific type with the specified value
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800109 *
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700110 * The underlying buffer holds only value Additional operations are needed
111 * to construct wire encoding, one need to prepend the wire buffer with type
112 * and value-length VAR-NUMBERs
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800113 */
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700114 Block(uint32_t type, const ConstBufferPtr& value);
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800115
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700116 /** @brief Create a nested Block of a specific type with the specified value
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800117 *
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700118 * The underlying buffer holds only value. Additional operations are needed
119 * to construct wire encoding, one need to prepend the wire buffer with type
120 * and value-length VAR-NUMBERs
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800121 */
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700122 Block(uint32_t type, const Block& value);
123
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700124 /** @brief Create a Block from an input stream
125 * @deprecated Use Block::fromStream instead
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700126 */
127 explicit
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700128 DEPRECATED(Block(std::istream& is))
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700129 {
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700130 *this = std::move(Block::fromStream(is));
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700131 }
132
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700133 /** @brief Create a Block from an input stream
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700134 */
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700135 static Block
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700136 fromStream(std::istream& is);
137
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700138 /** @brief Try to construct block from Buffer, referencing data block pointed by wire
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700139 *
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700140 * This method does not throw upon decoding error.
141 * @return true if Block successfully created, false if block cannot be created
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700142 */
143 static bool
144 fromBuffer(const ConstBufferPtr& wire, size_t offset, Block& block);
145
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700146 /** @brief Try to construct block from Buffer, referencing data block pointed by wire
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700147 *
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700148 * This method does not throw upon decoding error.
149 * @return true if Block successfully created, false if block cannot be created
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700150 */
151 static bool
152 fromBuffer(const uint8_t* buffer, size_t maxSize, Block& block);
Alexander Afanasyev196b9aa2014-01-31 17:19:16 -0800153
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700154public: // wire format
155 /** @brief Check if the Block is empty
Alexander Afanasyev196b9aa2014-01-31 17:19:16 -0800156 */
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700157 bool
Alexander Afanasyev196b9aa2014-01-31 17:19:16 -0800158 empty() const;
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700159
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700160 /** @brief Check if the Block has fully encoded wire
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800161 */
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700162 bool
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800163 hasWire() const;
164
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700165 /** @brief Reset wire buffer of the element
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800166 */
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700167 void
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800168 reset();
169
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700170 /** @brief Reset wire buffer but keep sub elements (if any)
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800171 */
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700172 void
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800173 resetWire();
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800174
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700175 Buffer::const_iterator
176 begin() const;
177
178 Buffer::const_iterator
179 end() const;
180
181 const uint8_t*
182 wire() const;
183
184 size_t
185 size() const;
186
187public: // type and value
188 uint32_t
189 type() const;
190
191 /** @brief Check if the Block has value block (no type and length are encoded)
192 */
193 bool
194 hasValue() const;
195
196 Buffer::const_iterator
197 value_begin() const;
198
199 Buffer::const_iterator
200 value_end() const;
201
202 const uint8_t*
203 value() const;
204
205 size_t
206 value_size() const;
207
208public: // sub elements
209 /** @brief Parse wire buffer into subblocks
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800210 *
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700211 * This method is not really const, but it does not modify any data. It simply
212 * parses contents of the buffer into subblocks
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800213 */
214 void
215 parse() const;
216
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700217 /** @brief Encode subblocks into wire buffer
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800218 */
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800219 void
220 encode();
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700221
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700222 /** @brief Get the first subelement of the requested type
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800223 */
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700224 const Block&
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800225 get(uint32_t type) const;
226
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700227 element_const_iterator
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800228 find(uint32_t type) const;
229
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700230 void
Alexander Afanasyevf5c35ae2014-01-17 16:06:31 -0800231 remove(uint32_t type);
232
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700233 element_iterator
Alexander Afanasyevf5c35ae2014-01-17 16:06:31 -0800234 erase(element_iterator position);
235
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700236 element_iterator
Alexander Afanasyevf5c35ae2014-01-17 16:06:31 -0800237 erase(element_iterator first, element_iterator last);
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700238
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700239 void
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700240 push_back(const Block& element);
241
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700242 /** @brief Get all subelements
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800243 */
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700244 const element_container&
245 elements() const;
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800246
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700247 element_const_iterator
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800248 elements_begin() const;
249
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700250 element_const_iterator
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800251 elements_end() const;
252
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700253 size_t
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800254 elements_size() const;
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700255
Yingdi Yu4270f202014-01-28 14:19:16 -0800256 Block
257 blockFromValue() const;
258
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700259public: // EqualityComparable concept
260 bool
261 operator==(const Block& other) const;
262
263 bool
264 operator!=(const Block& other) const;
265
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700266public: // ConvertibleToConstBuffer
267 operator boost::asio::const_buffer() const;
268
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800269protected:
270 ConstBufferPtr m_buffer;
271
272 uint32_t m_type;
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700273
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800274 Buffer::const_iterator m_begin;
275 Buffer::const_iterator m_end;
276 uint32_t m_size;
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700277
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800278 Buffer::const_iterator m_value_begin;
279 Buffer::const_iterator m_value_end;
280
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800281 mutable element_container m_subBlocks;
Alexander Afanasyev233750e2014-02-16 00:50:07 -0800282 friend class EncodingImpl<true>;
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800283};
284
285////////////////////////////////////////////////////////////////////////////////
286////////////////////////////////////////////////////////////////////////////////
287////////////////////////////////////////////////////////////////////////////////
288
289inline bool
Alexander Afanasyev196b9aa2014-01-31 17:19:16 -0800290Block::empty() const
291{
292 return m_type == std::numeric_limits<uint32_t>::max();
293}
294
Alexander Afanasyev196b9aa2014-01-31 17:19:16 -0800295inline bool
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800296Block::hasWire() const
297{
298 return m_buffer && (m_begin != m_end);
299}
300
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800301inline Buffer::const_iterator
302Block::begin() const
303{
304 if (!hasWire())
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700305 throw Error("Underlying wire buffer is empty");
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800306
307 return m_begin;
308}
309
310inline Buffer::const_iterator
311Block::end() const
312{
313 if (!hasWire())
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700314 throw Error("Underlying wire buffer is empty");
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800315
316 return m_end;
317}
318
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700319inline const uint8_t*
320Block::wire() const
321{
322 if (!hasWire())
323 throw Error("(Block::wire) Underlying wire buffer is empty");
324
325 return &*m_begin;
326}
327
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800328inline size_t
329Block::size() const
330{
331 if (hasWire() || hasValue()) {
332 return m_size;
333 }
334 else
335 throw Error("Block size cannot be determined (undefined block size)");
336}
337
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700338inline uint32_t
339Block::type() const
340{
341 return m_type;
342}
343
344inline bool
345Block::hasValue() const
346{
347 return static_cast<bool>(m_buffer);
348}
349
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800350inline Buffer::const_iterator
351Block::value_begin() const
352{
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800353 return m_value_begin;
354}
355
356inline Buffer::const_iterator
357Block::value_end() const
358{
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800359 return m_value_end;
360}
361
362inline const uint8_t*
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800363Block::value() const
364{
365 if (!hasValue())
Alexander Afanasyev380420b2014-02-09 20:52:29 -0800366 return 0;
Alexander Afanasyev937aa782014-03-21 13:17:57 -0700367
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800368 return &*m_value_begin;
369}
370
371inline size_t
372Block::value_size() const
373{
374 if (!hasValue())
Alexander Afanasyev8ea763d2014-02-06 20:32:52 -0800375 return 0;
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800376
377 return m_value_end - m_value_begin;
378}
379
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700380inline Block::element_iterator
381Block::erase(Block::element_iterator position)
382{
383 resetWire();
384 return m_subBlocks.erase(position);
385}
386
387inline Block::element_iterator
388Block::erase(Block::element_iterator first, Block::element_iterator last)
389{
390 resetWire();
391 return m_subBlocks.erase(first, last);
392}
393
394inline void
395Block::push_back(const Block& element)
396{
397 resetWire();
398 m_subBlocks.push_back(element);
399}
400
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800401inline const Block::element_container&
Alexander Afanasyeva465e972014-03-22 17:21:49 -0700402Block::elements() const
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800403{
404 return m_subBlocks;
405}
406
407inline Block::element_const_iterator
408Block::elements_begin() const
409{
410 return m_subBlocks.begin();
411}
412
413inline Block::element_const_iterator
414Block::elements_end() const
415{
416 return m_subBlocks.end();
417}
418
419inline size_t
420Block::elements_size() const
421{
422 return m_subBlocks.size();
423}
424
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700425inline bool
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700426Block::operator!=(const Block& other) const
427{
428 return !this->operator==(other);
429}
Alexander Afanasyev29e5c3d2014-02-11 00:01:10 -0800430
Junxiao Shi81a6c5d2014-11-30 00:14:42 -0700431} // namespace ndn
Alexander Afanasyev13bb51a2014-01-02 19:13:26 -0800432
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700433#endif // NDN_ENCODING_BLOCK_HPP