blob: 5ba4729144e09e10a1c6bb4f0487d88d5a958ae7 [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -08002/**
Alexander Afanasyev74633892015-02-08 18:08:46 -08003 * Copyright (c) 2013-2015 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 Afanasyev15f67312014-07-22 15:11:09 -070025#include "common.hpp"
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070026#include "encoding/block.hpp"
Alexander Afanasyev95b0e342014-02-12 21:34:44 -080027#include "encoding/encoding-buffer.hpp"
Alexander Afanasyev15f67312014-07-22 15:11:09 -070028#include "util/time.hpp"
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070029#include "name-component.hpp"
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
34/**
35 * An MetaInfo holds the meta info which is signed inside the data packet.
Shock Jiangca7ea702014-10-02 11:23:25 -070036 *
37 * The class allows experimentation with application-defined meta information blocks,
38 * which slightly violates NDN-TLV specification. When using the application-defined
39 * meta information blocks be aware that this may result in packet drop (NFD and
40 * previous versions of ndn-cxx will gracefully accept such packet).
41 *
42 * The following definition of MetaInfo block is assumed in this implementation (compared
43 * to the NDN-TLV spec, definition extended to allow optional AppMetaInfo TLV blocks):
44 *
45 * MetaInfo ::= META-INFO-TYPE TLV-LENGTH
46 * ContentType?
47 * FreshnessPeriod?
48 * FinalBlockId?
49 * AppMetaInfo*
50 *
51 * AppMetaInfo ::= any TLV block with type in the restricted application range [128, 252]
52 *
53 * Note that AppMetaInfo blocks are application-defined and must have TLV type from
54 * the restricted application range [128, 252].
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -080055 */
Alexander Afanasyev2a7f7202014-04-23 14:25:29 -070056class MetaInfo
57{
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -080058public:
Shock Jiangca7ea702014-10-02 11:23:25 -070059 class Error : public tlv::Error
60 {
61 public:
62 explicit
63 Error(const std::string& what)
64 : tlv::Error(what)
65 {
66 }
67 };
68
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070069 MetaInfo();
Alexander Afanasyev95b0e342014-02-12 21:34:44 -080070
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070071 /**
72 * @brief Create from wire encoding
73 */
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070074 explicit
75 MetaInfo(const Block& block);
Alexander Afanasyevc348f832014-02-17 16:35:17 -080076
Alexander Afanasyev74633892015-02-08 18:08:46 -080077 template<encoding::Tag TAG>
Alexander Afanasyevc348f832014-02-17 16:35:17 -080078 size_t
Alexander Afanasyev74633892015-02-08 18:08:46 -080079 wireEncode(EncodingImpl<TAG>& block) const;
Alexander Afanasyevc348f832014-02-17 16:35:17 -080080
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070081 const Block&
Alexander Afanasyevc348f832014-02-17 16:35:17 -080082 wireEncode() const;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070083
Alexander Afanasyevc348f832014-02-17 16:35:17 -080084 void
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -070085 wireDecode(const Block& wire);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070086
Junxiao Shia464b922014-11-12 21:13:06 -070087public: // getter/setter
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070088 uint32_t
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070089 getType() const;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070090
Junxiao Shia464b922014-11-12 21:13:06 -070091 /** @brief set ContentType
92 * @param type a code defined in tlv::ContentTypeValue
93 */
Alexander Afanasyev95b0e342014-02-12 21:34:44 -080094 MetaInfo&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070095 setType(uint32_t type);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070096
97 const time::milliseconds&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -070098 getFreshnessPeriod() const;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070099
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800100 MetaInfo&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700101 setFreshnessPeriod(const time::milliseconds& freshnessPeriod);
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800102
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800103 const name::Component&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700104 getFinalBlockId() const;
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800105
106 MetaInfo&
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700107 setFinalBlockId(const name::Component& finalBlockId);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700108
Junxiao Shia464b922014-11-12 21:13:06 -0700109public: // app-defined MetaInfo items
Shock Jiangca7ea702014-10-02 11:23:25 -0700110 /**
111 * @brief Get all app-defined MetaInfo items
112 *
113 * @note Warning: Experimental API, which may change or disappear in the future
114 *
115 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
116 * is called before *AppMetaInfo, all app-defined blocks will be lost
117 */
118 const std::list<Block>&
119 getAppMetaInfo() const;
120
121 /**
122 * @brief Set app-defined MetaInfo items
123 *
124 * This method will replace all existing app-defined MetaInfo items, if they existed.
125 *
126 * @throw Error if some block in @p info has type not in the application range
127 * (http://named-data.net/doc/ndn-tlv/types.html)
128 *
129 * @note Warning: Experimental API, which may change or disappear in the future
130 *
131 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
132 * is called before *AppMetaInfo, all app-defined blocks will be lost
133 */
134 MetaInfo&
135 setAppMetaInfo(const std::list<Block>& info);
136
137 /**
138 * @brief Add an app-defined MetaInfo item
139 *
140 * @throw Error if @p block has type not in the application range
141 * (http://named-data.net/doc/ndn-tlv/types.html)
142 *
143 * @note Warning: Experimental API, which may change or disappear in the future
144 *
145 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
146 * is called before *AppMetaInfo, all app-defined blocks will be lost
147 */
148 MetaInfo&
149 addAppMetaInfo(const Block& block);
150
151 /**
152 * @brief Remove a first app-defined MetaInfo item with type @p tlvType
153 *
154 * @return true if an item was deleted
155 *
156 * @note Warning: Experimental API, which may change or disappear in the future
157 *
158 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
159 * is called before *AppMetaInfo, all app-defined blocks will be lost
160 */
161 bool
162 removeAppMetaInfo(uint32_t tlvType);
163
164 /**
165 * @brief Find a first app-defined MetaInfo item of type @p tlvType
166 *
167 * @return NULL if an item is not found, otherwise const pointer to the item
168 *
169 * @throw Error if @p tlvType is not in the application range
170 * (http://named-data.net/doc/ndn-tlv/types.html)
171 *
172 * @note Warning: Experimental API, which may change or disappear in the future
173 *
174 * @note If MetaInfo is decoded from wire and setType, setFreshnessPeriod, or setFinalBlockId
175 * is called before *AppMetaInfo, all app-defined blocks will be lost
176 */
177 const Block*
178 findAppMetaInfo(uint32_t tlvType) const;
179
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700180public: // EqualityComparable concept
181 bool
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700182 operator==(const MetaInfo& other) const;
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700183
184 bool
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700185 operator!=(const MetaInfo& other) const;
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700186
Junxiao Shia464b922014-11-12 21:13:06 -0700187public: // deprecated
188 /** @deprecated use tlv::ContentType_Blob
189 */
190 static const uint32_t DEPRECATED(TYPE_BLOB) = tlv::ContentType_Blob;
191
192 /** @deprecated use tlv::ContentType_Link
193 */
194 static const uint32_t DEPRECATED(TYPE_LINK) = tlv::ContentType_Link;
195
196 /** @deprecated use tlv::ContentType_Key
197 */
198 static const uint32_t DEPRECATED(TYPE_KEY) = tlv::ContentType_Key;
199
200 /** @deprecated use tlv::ContentType_Nack
201 */
202 static const uint32_t DEPRECATED(TYPE_NACK) = tlv::ContentType_Nack;
203
204 /** @deprecated use tlv::ContentType_Default
205 */
206 static const uint32_t DEPRECATED(TYPE_DEFAULT) = tlv::ContentType_Blob;
207
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800208private:
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800209 uint32_t m_type;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700210 time::milliseconds m_freshnessPeriod;
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800211 name::Component m_finalBlockId;
Shock Jiangca7ea702014-10-02 11:23:25 -0700212 std::list<Block> m_appMetaInfo;
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800213
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800214 mutable Block m_wire;
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800215};
216
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700217std::ostream&
218operator<<(std::ostream& os, const MetaInfo& info);
219
220/////////////////////////////////////////////////////////////////////////
221
222inline uint32_t
223MetaInfo::getType() const
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800224{
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700225 return m_type;
Alexander Afanasyev95b0e342014-02-12 21:34:44 -0800226}
227
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700228inline const time::milliseconds&
229MetaInfo::getFreshnessPeriod() const
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800230{
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700231 return m_freshnessPeriod;
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800232}
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700233
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700234inline const name::Component&
235MetaInfo::getFinalBlockId() const
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800236{
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700237 return m_finalBlockId;
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800238}
239
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700240inline bool
241MetaInfo::operator==(const MetaInfo& other) const
Alexander Afanasyev4ff3c912014-01-03 15:25:02 -0800242{
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700243 return wireEncode() == other.wireEncode();
244}
Alexander Afanasyev4ff3c912014-01-03 15:25:02 -0800245
Alexander Afanasyev01065fb2014-10-02 13:01:46 -0700246inline bool
247MetaInfo::operator!=(const MetaInfo& other) const
248{
249 return !(*this == other);
Alexander Afanasyev4ff3c912014-01-03 15:25:02 -0800250}
251
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800252} // namespace ndn
253
254#endif // NDN_META_INFO_HPP