blob: e8e8a006dc235d13767690885c6c56392ecd1365 [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Davide Pesavento88a0d812017-08-19 21:31:42 -04002/*
Eric Newberryb555b002017-05-17 00:30:44 -07003 * Copyright (c) 2013-2017 Regents of the University of California.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07004 *
5 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07006 *
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 Afanasyev2ba8f662014-01-05 22:53:18 -080020 */
21
22#ifndef NDN_META_INFO_HPP
23#define NDN_META_INFO_HPP
24
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070025#include "encoding/block.hpp"
Alexander Afanasyev95b0e342014-02-12 21:34:44 -080026#include "encoding/encoding-buffer.hpp"
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070027#include "name-component.hpp"
Davide Pesavento88a0d812017-08-19 21:31:42 -040028#include "util/time.hpp"
29
Shock Jiangca7ea702014-10-02 11:23:25 -070030#include <list>
Alexander Afanasyev95b0e342014-02-12 21:34:44 -080031
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -080032namespace ndn {
33
Eric Newberryb555b002017-05-17 00:30:44 -070034const time::milliseconds DEFAULT_FRESHNESS_PERIOD = time::milliseconds::zero();
35
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -080036/**
37 * An MetaInfo holds the meta info which is signed inside the data packet.
Shock Jiangca7ea702014-10-02 11:23:25 -070038 *
39 * The class allows experimentation with application-defined meta information blocks,
40 * which slightly violates NDN-TLV specification. When using the application-defined
41 * meta information blocks be aware that this may result in packet drop (NFD and
42 * previous versions of ndn-cxx will gracefully accept such packet).
43 *
44 * The following definition of MetaInfo block is assumed in this implementation (compared
45 * to the NDN-TLV spec, definition extended to allow optional AppMetaInfo TLV blocks):
46 *
47 * MetaInfo ::= META-INFO-TYPE TLV-LENGTH
48 * ContentType?
49 * FreshnessPeriod?
50 * FinalBlockId?
51 * AppMetaInfo*
52 *
53 * AppMetaInfo ::= any TLV block with type in the restricted application range [128, 252]
54 *
55 * Note that AppMetaInfo blocks are application-defined and must have TLV type from
56 * the restricted application range [128, 252].
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -080057 */
Alexander Afanasyev2a7f7202014-04-23 14:25:29 -070058class MetaInfo
59{
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -080060public:
Shock Jiangca7ea702014-10-02 11:23:25 -070061 class Error : public tlv::Error
62 {
63 public:
64 explicit
65 Error(const std::string& what)
66 : tlv::Error(what)
67 {
68 }
69 };
70
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070071 MetaInfo();
Alexander Afanasyev95b0e342014-02-12 21:34:44 -080072
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070073 /**
74 * @brief Create from wire encoding
75 */
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070076 explicit
77 MetaInfo(const Block& block);
Alexander Afanasyevc348f832014-02-17 16:35:17 -080078
Alexander Afanasyev74633892015-02-08 18:08:46 -080079 template<encoding::Tag TAG>
Alexander Afanasyevc348f832014-02-17 16:35:17 -080080 size_t
Alexander Afanasyevd5c48e02015-06-24 11:58:14 -070081 wireEncode(EncodingImpl<TAG>& encoder) const;
Alexander Afanasyevc348f832014-02-17 16:35:17 -080082
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070083 const Block&
Alexander Afanasyevc348f832014-02-17 16:35:17 -080084 wireEncode() const;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070085
Alexander Afanasyevc348f832014-02-17 16:35:17 -080086 void
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -070087 wireDecode(const Block& wire);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070088
Junxiao Shia464b922014-11-12 21:13:06 -070089public: // getter/setter
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070090 uint32_t
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070091 getType() const;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070092
Junxiao Shia464b922014-11-12 21:13:06 -070093 /** @brief set ContentType
94 * @param type a code defined in tlv::ContentTypeValue
95 */
Alexander Afanasyev95b0e342014-02-12 21:34:44 -080096 MetaInfo&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070097 setType(uint32_t type);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070098
99 const time::milliseconds&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700100 getFreshnessPeriod() const;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700101
Eric Newberryb555b002017-05-17 00:30:44 -0700102 /** @brief set FreshnessPeriod
103 * @throw std::invalid_argument specified FreshnessPeriod is < 0
104 */
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800105 MetaInfo&
Eric Newberryb555b002017-05-17 00:30:44 -0700106 setFreshnessPeriod(time::milliseconds freshnessPeriod);
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800107
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800108 const name::Component&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700109 getFinalBlockId() const;
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800110
111 MetaInfo&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700112 setFinalBlockId(const name::Component& finalBlockId);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700113
Junxiao Shia464b922014-11-12 21:13:06 -0700114public: // app-defined MetaInfo items
Shock Jiangca7ea702014-10-02 11:23:25 -0700115 /**
116 * @brief Get all app-defined MetaInfo items
117 *
118 * @note Warning: Experimental API, which may change or disappear in the future
119 *
120 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
121 * is called before *AppMetaInfo, all app-defined blocks will be lost
122 */
123 const std::list<Block>&
124 getAppMetaInfo() const;
125
126 /**
127 * @brief Set app-defined MetaInfo items
128 *
129 * This method will replace all existing app-defined MetaInfo items, if they existed.
130 *
131 * @throw Error if some block in @p info has type not in the application range
132 * (http://named-data.net/doc/ndn-tlv/types.html)
133 *
134 * @note Warning: Experimental API, which may change or disappear in the future
135 *
136 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
137 * is called before *AppMetaInfo, all app-defined blocks will be lost
138 */
139 MetaInfo&
140 setAppMetaInfo(const std::list<Block>& info);
141
142 /**
143 * @brief Add an app-defined MetaInfo item
144 *
145 * @throw Error if @p block has type not in the application range
146 * (http://named-data.net/doc/ndn-tlv/types.html)
147 *
148 * @note Warning: Experimental API, which may change or disappear in the future
149 *
150 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
151 * is called before *AppMetaInfo, all app-defined blocks will be lost
152 */
153 MetaInfo&
154 addAppMetaInfo(const Block& block);
155
156 /**
157 * @brief Remove a first app-defined MetaInfo item with type @p tlvType
158 *
159 * @return true if an item was deleted
160 *
161 * @note Warning: Experimental API, which may change or disappear in the future
162 *
163 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
164 * is called before *AppMetaInfo, all app-defined blocks will be lost
165 */
166 bool
167 removeAppMetaInfo(uint32_t tlvType);
168
169 /**
170 * @brief Find a first app-defined MetaInfo item of type @p tlvType
171 *
172 * @return NULL if an item is not found, otherwise const pointer to the item
173 *
174 * @throw Error if @p tlvType is not in the application range
175 * (http://named-data.net/doc/ndn-tlv/types.html)
176 *
177 * @note Warning: Experimental API, which may change or disappear in the future
178 *
179 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
180 * is called before *AppMetaInfo, all app-defined blocks will be lost
181 */
182 const Block*
183 findAppMetaInfo(uint32_t tlvType) const;
184
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700185public: // EqualityComparable concept
186 bool
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700187 operator==(const MetaInfo& other) const;
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700188
189 bool
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700190 operator!=(const MetaInfo& other) const;
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700191
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800192private:
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800193 uint32_t m_type;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700194 time::milliseconds m_freshnessPeriod;
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800195 name::Component m_finalBlockId;
Shock Jiangca7ea702014-10-02 11:23:25 -0700196 std::list<Block> m_appMetaInfo;
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800197
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800198 mutable Block m_wire;
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800199};
200
Davide Pesavento88a0d812017-08-19 21:31:42 -0400201NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(MetaInfo);
202
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700203std::ostream&
204operator<<(std::ostream& os, const MetaInfo& info);
205
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700206inline uint32_t
207MetaInfo::getType() const
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800208{
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700209 return m_type;
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800210}
211
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700212inline const time::milliseconds&
213MetaInfo::getFreshnessPeriod() const
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800214{
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700215 return m_freshnessPeriod;
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800216}
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700217
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700218inline const name::Component&
219MetaInfo::getFinalBlockId() const
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800220{
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700221 return m_finalBlockId;
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800222}
223
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700224inline bool
225MetaInfo::operator==(const MetaInfo& other) const
Alexander Afanasyev4ff3c912014-01-03 15:25:02 -0800226{
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700227 return wireEncode() == other.wireEncode();
228}
Alexander Afanasyev4ff3c912014-01-03 15:25:02 -0800229
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700230inline bool
231MetaInfo::operator!=(const MetaInfo& other) const
232{
233 return !(*this == other);
Alexander Afanasyev4ff3c912014-01-03 15:25:02 -0800234}
235
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800236} // namespace ndn
237
238#endif // NDN_META_INFO_HPP