blob: eedea7a75baaa48461e79433e5ce342708dc3205 [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Junxiao Shi81206d52017-07-23 12:43:22 +00002/*
3 * 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.
Jeff Thompson5cae5e52013-07-10 19:41:20 -070020 */
21
Jeff Thompson56ec9e22013-08-02 11:34:07 -070022#ifndef NDN_DATA_HPP
Jeff Thompsona0d18c92013-08-06 13:55:32 -070023#define NDN_DATA_HPP
Jeff Thompson5cae5e52013-07-10 19:41:20 -070024
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -080025#include "meta-info.hpp"
Junxiao Shi81206d52017-07-23 12:43:22 +000026#include "name.hpp"
27#include "signature.hpp"
Alexander Afanasyeva3887ae2014-12-29 16:11:57 -080028#include "tag-host.hpp"
Junxiao Shi81206d52017-07-23 12:43:22 +000029#include "encoding/block.hpp"
Jeff Thompson5cae5e52013-07-10 19:41:20 -070030
31namespace ndn {
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070032
Junxiao Shi81206d52017-07-23 12:43:22 +000033/** @brief Represents a Data packet
Junxiao Shic2b8d242014-11-04 08:35:29 -070034 */
Alexander Afanasyeva3887ae2014-12-29 16:11:57 -080035class Data : public TagHost, public enable_shared_from_this<Data>
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080036{
Jeff Thompson5cae5e52013-07-10 19:41:20 -070037public:
Junxiao Shic2b8d242014-11-04 08:35:29 -070038 class Error : public tlv::Error
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -070039 {
40 public:
41 explicit
42 Error(const std::string& what)
Junxiao Shic2b8d242014-11-04 08:35:29 -070043 : tlv::Error(what)
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -070044 {
45 }
46 };
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070047
Junxiao Shi81206d52017-07-23 12:43:22 +000048 /** @brief Create a new Data with the given name and empty Content
49 * @warning In certain contexts that use Data::shared_from_this(), Data must be created
50 * using `make_shared`. Otherwise, .shared_from_this() will trigger undefined behavior.
Jeff Thompson20af0732013-09-12 17:01:45 -070051 */
Junxiao Shi9b845352017-07-24 05:04:56 +000052 explicit
Junxiao Shi81206d52017-07-23 12:43:22 +000053 Data(const Name& name = Name());
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070054
Junxiao Shi81206d52017-07-23 12:43:22 +000055 /** @brief Create from wire encoding
56 * @warning In certain contexts that use Data::shared_from_this(), Data must be created
57 * using `make_shared`. Otherwise, .shared_from_this() will trigger undefined behavior.
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -080058 */
59 explicit
Alexander Afanasyev197e5652014-06-13 16:56:31 -070060 Data(const Block& wire);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070061
Junxiao Shi81206d52017-07-23 12:43:22 +000062 /** @brief Fast encoding or block size estimation
63 * @param encoder EncodingEstimator or EncodingBuffer instance
64 * @param wantUnsignedPortionOnly If true, only prepends Name, MetaInfo, Content, and
65 * SignatureInfo to @p encoder, but omit SignatureValue and outmost Type-Length of Data
66 * element. This is intended to be used with wireEncode(encoder, signatureValue).
67 * @throw Error SignatureBits are not provided and wantUnsignedPortionOnly is false.
Jeff Thompsonb7aefa002013-09-16 18:22:00 -070068 */
Alexander Afanasyev74633892015-02-08 18:08:46 -080069 template<encoding::Tag TAG>
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -070070 size_t
Alexander Afanasyevd5c48e02015-06-24 11:58:14 -070071 wireEncode(EncodingImpl<TAG>& encoder, bool wantUnsignedPortionOnly = false) const;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070072
Junxiao Shi81206d52017-07-23 12:43:22 +000073 /** @brief Finalize Data packet encoding with the specified SignatureValue
74 * @param encoder EncodingBuffer containing Name, MetaInfo, Content, and SignatureInfo, but
75 * without SignatureValue or outmost Type-Length of Data element
76 * @param signatureValue SignatureValue element
Alexander Afanasyev197e5652014-06-13 16:56:31 -070077 *
Junxiao Shi81206d52017-07-23 12:43:22 +000078 * This method is intended to be used in concert with Data::wireEncode(encoder, true)
79 * @code
Alexander Afanasyev197e5652014-06-13 16:56:31 -070080 * Data data;
81 * ...
82 * EncodingBuffer encoder;
83 * data.wireEncode(encoder, true);
84 * ...
85 * Block signatureValue = <sign_over_unsigned_portion>(encoder.buf(), encoder.size());
86 * data.wireEncode(encoder, signatureValue)
Junxiao Shi81206d52017-07-23 12:43:22 +000087 * @endcode
Alexander Afanasyev197e5652014-06-13 16:56:31 -070088 */
89 const Block&
90 wireEncode(EncodingBuffer& encoder, const Block& signatureValue) const;
91
Junxiao Shi81206d52017-07-23 12:43:22 +000092 /** @brief Encode to a wire format
93 */
94 const Block&
95 wireEncode() const;
96
97 /** @brief Decode from the wire format
Alexander Afanasyev809805d2014-02-17 17:20:33 -080098 */
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -070099 void
100 wireDecode(const Block& wire);
Alexander Afanasyevfadc97d2014-01-03 13:22:10 -0800101
Junxiao Shi81206d52017-07-23 12:43:22 +0000102 /** @brief Check if already has wire
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800103 */
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700104 bool
Junxiao Shi81206d52017-07-23 12:43:22 +0000105 hasWire() const
106 {
107 return m_wire.hasWire();
108 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700109
Junxiao Shi81206d52017-07-23 12:43:22 +0000110 /** @brief Get full name including implicit digest
111 * @pre hasWire() == true; i.e. wireEncode() must have been called
112 * @throw Error Data has no wire encoding
Alexander Afanasyev3b703102014-06-13 17:01:14 -0700113 */
114 const Name&
115 getFullName() const;
116
Junxiao Shi81206d52017-07-23 12:43:22 +0000117public: // Data fields
118 /** @brief Get name
119 */
120 const Name&
121 getName() const
122 {
123 return m_name;
124 }
125
126 /** @brief Set name
127 * @return a reference to this Data, to allow chaining
128 */
129 Data&
130 setName(const Name& name);
131
132 /** @brief Get MetaInfo
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700133 */
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700134 const MetaInfo&
Junxiao Shi81206d52017-07-23 12:43:22 +0000135 getMetaInfo() const
136 {
137 return m_metaInfo;
138 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700139
Junxiao Shi81206d52017-07-23 12:43:22 +0000140 /** @brief Set MetaInfo
141 * @return a reference to this Data, to allow chaining
Jeff Thompson0cd8c4a2013-09-13 17:46:40 -0700142 */
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700143 Data&
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800144 setMetaInfo(const MetaInfo& metaInfo);
Jeff Thompson46bd45f2013-08-08 16:46:41 -0700145
Junxiao Shi81206d52017-07-23 12:43:22 +0000146 /** @brief Get Content
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800147 *
Junxiao Shi81206d52017-07-23 12:43:22 +0000148 * The Content value is accessible through value()/value_size() or value_begin()/value_end()
149 * methods of the Block class.
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800150 */
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700151 const Block&
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800152 getContent() const;
Alexander Afanasyevfadc97d2014-01-03 13:22:10 -0800153
Junxiao Shi81206d52017-07-23 12:43:22 +0000154 /** @brief Set Content from a block
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700155 *
Junxiao Shi81206d52017-07-23 12:43:22 +0000156 * If block's TLV-TYPE is Content, it will be used directly as Data's Content element.
157 * If block's TLV-TYPE is not Content, it will be nested into a Content element.
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700158 *
Junxiao Shi81206d52017-07-23 12:43:22 +0000159 * @return a reference to this Data, to allow chaining
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700160 */
161 Data&
162 setContent(const Block& block);
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800163
Junxiao Shi81206d52017-07-23 12:43:22 +0000164 /** @brief Copy Content value from raw buffer
165 * @param value pointer to the first octet of the value
166 * @param valueSize size of the raw buffer
167 * @return a reference to this Data, to allow chaining
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700168 */
169 Data&
Junxiao Shi81206d52017-07-23 12:43:22 +0000170 setContent(const uint8_t* value, size_t valueSize);
Alexander Afanasyev809805d2014-02-17 17:20:33 -0800171
Junxiao Shi81206d52017-07-23 12:43:22 +0000172 /** @brief Set Content from wire buffer
173 * @param value Content value, which does not need to be a TLV element
174 * @return a reference to this Data, to allow chaining
175 */
176 Data&
177 setContent(const ConstBufferPtr& value);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700178
Junxiao Shi81206d52017-07-23 12:43:22 +0000179 /** @brief Get Signature
180 */
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700181 const Signature&
Junxiao Shi81206d52017-07-23 12:43:22 +0000182 getSignature() const
183 {
184 return m_signature;
185 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700186
Junxiao Shi81206d52017-07-23 12:43:22 +0000187 /** @brief Set Signature
188 * @return a reference to this Data, to allow chaining
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800189 */
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700190 Data&
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800191 setSignature(const Signature& signature);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700192
Junxiao Shi81206d52017-07-23 12:43:22 +0000193 /** @brief Set SignatureValue
194 * @return a reference to this Data, to allow chaining
195 */
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700196 Data&
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700197 setSignatureValue(const Block& value);
Yingdi Yua4e57672014-02-06 11:16:17 -0800198
Junxiao Shi81206d52017-07-23 12:43:22 +0000199public: // MetaInfo fields
200 uint32_t
201 getContentType() const
202 {
203 return m_metaInfo.getType();
204 }
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700205
Junxiao Shi81206d52017-07-23 12:43:22 +0000206 Data&
207 setContentType(uint32_t type);
208
209 const time::milliseconds&
210 getFreshnessPeriod() const
211 {
212 return m_metaInfo.getFreshnessPeriod();
213 }
214
215 Data&
216 setFreshnessPeriod(const time::milliseconds& freshnessPeriod);
217
218 const name::Component&
219 getFinalBlockId() const
220 {
221 return m_metaInfo.getFinalBlockId();
222 }
223
224 Data&
225 setFinalBlockId(const name::Component& finalBlockId);
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700226
Spyridon Mastorakis3b54e852015-04-07 08:03:25 -0700227protected:
Junxiao Shi81206d52017-07-23 12:43:22 +0000228 /** @brief Clear wire encoding and cached FullName
229 * @note This does not clear the SignatureValue.
Jeff Thompsonb7aefa002013-09-16 18:22:00 -0700230 */
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700231 void
Junxiao Shi81206d52017-07-23 12:43:22 +0000232 resetWire();
Alexander Afanasyevfadc97d2014-01-03 13:22:10 -0800233
234private:
Alexander Afanasyev809805d2014-02-17 17:20:33 -0800235 Name m_name;
236 MetaInfo m_metaInfo;
Junxiao Shi81206d52017-07-23 12:43:22 +0000237 Block m_content;
Alexander Afanasyev809805d2014-02-17 17:20:33 -0800238 Signature m_signature;
Alexander Afanasyevfadc97d2014-01-03 13:22:10 -0800239
Alexander Afanasyev809805d2014-02-17 17:20:33 -0800240 mutable Block m_wire;
Junxiao Shi81206d52017-07-23 12:43:22 +0000241 mutable Name m_fullName; ///< cached FullName computed from m_wire
Jeff Thompson5cae5e52013-07-10 19:41:20 -0700242};
Alexander Afanasyevfadc97d2014-01-03 13:22:10 -0800243
Alexander Afanasyeva0c5f832014-06-19 13:27:56 -0700244std::ostream&
245operator<<(std::ostream& os, const Data& data);
Alexander Afanasyev809805d2014-02-17 17:20:33 -0800246
Junxiao Shi81206d52017-07-23 12:43:22 +0000247bool
248operator==(const Data& lhs, const Data& rhs);
249
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800250inline bool
Junxiao Shi81206d52017-07-23 12:43:22 +0000251operator!=(const Data& lhs, const Data& rhs)
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800252{
Junxiao Shi81206d52017-07-23 12:43:22 +0000253 return !(lhs == rhs);
Alexander Afanasyev2ba8f662014-01-05 22:53:18 -0800254}
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700255
Alexander Afanasyevfadc97d2014-01-03 13:22:10 -0800256} // namespace ndn
257
Junxiao Shi81206d52017-07-23 12:43:22 +0000258#endif // NDN_DATA_HPP