blob: 41e38481304b69021d29d4a4a68464bdff3832a8 [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Jeff Thompson47eecfc2013-07-07 22:56:46 -07002/**
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.
Jeff Thompsonb7f95562013-07-03 18:36:42 -070020 */
21
22#ifndef NDN_INTEREST_HPP
Jeff Thompson2d27e2f2013-08-09 12:55:00 -070023#define NDN_INTEREST_HPP
Jeff Thompsonb7f95562013-07-03 18:36:42 -070024
Alexander Afanasyeve2dcdfd2014-02-07 15:53:28 -080025#include "common.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070026
Jeff Thompson53412192013-08-06 13:35:50 -070027#include "name.hpp"
Alexander Afanasyevc348f832014-02-17 16:35:17 -080028#include "selectors.hpp"
Alexander Afanasyev15f67312014-07-22 15:11:09 -070029#include "util/time.hpp"
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -080030#include "management/nfd-local-control-header.hpp"
Alexander Afanasyeva3887ae2014-12-29 16:11:57 -080031#include "tag-host.hpp"
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -070032#include "link.hpp"
Jeff Thompsonb7f95562013-07-03 18:36:42 -070033
34namespace ndn {
Alexander Afanasyevc348f832014-02-17 16:35:17 -080035
Junxiao Shiaf8eeea2014-03-31 20:10:56 -070036class Data;
37
Junxiao Shi7007a3c2014-11-20 22:37:55 -070038/** @var const unspecified_duration_type DEFAULT_INTEREST_LIFETIME;
39 * @brief default value for InterestLifetime
40 */
41const time::milliseconds DEFAULT_INTEREST_LIFETIME = time::milliseconds(4000);
Alexander Afanasyevc348f832014-02-17 16:35:17 -080042
Junxiao Shic2b8d242014-11-04 08:35:29 -070043/** @brief represents an Interest packet
Jeff Thompson8238d002013-07-10 11:56:49 -070044 */
Alexander Afanasyeva3887ae2014-12-29 16:11:57 -080045class Interest : public TagHost, public enable_shared_from_this<Interest>
Alexander Afanasyevc348f832014-02-17 16:35:17 -080046{
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070047public:
Junxiao Shic2b8d242014-11-04 08:35:29 -070048 class Error : public tlv::Error
49 {
50 public:
51 explicit
52 Error(const std::string& what)
53 : tlv::Error(what)
54 {
55 }
56 };
57
Junxiao Shi2af905b2014-11-27 13:10:54 -070058 /** @brief Create a new Interest with an empty name (`ndn:/`)
59 * @warning In certain contexts that use Interest::shared_from_this(), Interest must be created
60 * using `make_shared`. Otherwise, .shared_from_this() will throw an exception.
Alexander Afanasyevc348f832014-02-17 16:35:17 -080061 */
Junxiao Shi2af905b2014-11-27 13:10:54 -070062 Interest();
Alexander Afanasyevc348f832014-02-17 16:35:17 -080063
Junxiao Shi2af905b2014-11-27 13:10:54 -070064 /** @brief Create a new Interest with the given name
65 * @param name The name for the interest.
66 * @note This constructor allows implicit conversion from Name.
67 * @warning In certain contexts that use Interest::shared_from_this(), Interest must be created
68 * using `make_shared`. Otherwise, .shared_from_this() will throw an exception.
Alexander Afanasyevc348f832014-02-17 16:35:17 -080069 */
Junxiao Shi2af905b2014-11-27 13:10:54 -070070 Interest(const Name& name);
Alexander Afanasyevc348f832014-02-17 16:35:17 -080071
Junxiao Shi2af905b2014-11-27 13:10:54 -070072 /** @brief Create a new Interest with the given name and interest lifetime
73 * @param name The name for the interest.
74 * @param interestLifetime The interest lifetime in time::milliseconds, or -1 for none.
75 * @warning In certain contexts that use Interest::shared_from_this(), Interest must be created
76 * using `make_shared`. Otherwise, .shared_from_this() will throw an exception.
Alexander Afanasyevc348f832014-02-17 16:35:17 -080077 */
Junxiao Shi2af905b2014-11-27 13:10:54 -070078 Interest(const Name& name, const time::milliseconds& interestLifetime);
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070079
Junxiao Shi2af905b2014-11-27 13:10:54 -070080 /** @brief Create from wire encoding
81 * @warning In certain contexts that use Interest::shared_from_this(), Interest must be created
82 * using `make_shared`. Otherwise, .shared_from_this() will throw an exception.
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070083 */
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -080084 explicit
Junxiao Shi2af905b2014-11-27 13:10:54 -070085 Interest(const Block& wire);
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -080086
Jeff Thompson1b4a7b12013-11-15 12:00:02 -080087 /**
Alexander Afanasyevc348f832014-02-17 16:35:17 -080088 * @brief Fast encoding or block size estimation
Jeff Thompson1b4a7b12013-11-15 12:00:02 -080089 */
Alexander Afanasyev74633892015-02-08 18:08:46 -080090 template<encoding::Tag TAG>
Alexander Afanasyev197e5652014-06-13 16:56:31 -070091 size_t
Alexander Afanasyev74633892015-02-08 18:08:46 -080092 wireEncode(EncodingImpl<TAG>& block) const;
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -080093
Jeff Thompson1b4a7b12013-11-15 12:00:02 -080094 /**
Alexander Afanasyevc348f832014-02-17 16:35:17 -080095 * @brief Encode to a wire format
Jeff Thompson1b4a7b12013-11-15 12:00:02 -080096 */
Alexander Afanasyev197e5652014-06-13 16:56:31 -070097 const Block&
Alexander Afanasyev1eb961a2014-01-03 13:51:49 -080098 wireEncode() const;
Alexander Afanasyevc348f832014-02-17 16:35:17 -080099
Jeff Thompson1b4a7b12013-11-15 12:00:02 -0800100 /**
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800101 * @brief Decode from the wire format
Jeff Thompson1b4a7b12013-11-15 12:00:02 -0800102 */
Alexander Afanasyev197e5652014-06-13 16:56:31 -0700103 void
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700104 wireDecode(const Block& wire);
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800105
106 /**
107 * @brief Check if already has wire
108 */
Alexander Afanasyev197e5652014-06-13 16:56:31 -0700109 bool
Junxiao Shi2af905b2014-11-27 13:10:54 -0700110 hasWire() const
111 {
112 return m_wire.hasWire();
113 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700114
Jeff Thompsond9e278c2013-07-08 15:20:13 -0700115 /**
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700116 * @brief Encode the name according to the NDN URI Scheme
117 *
118 * If there are interest selectors, this method will append "?" and add the selectors as
119 * a query string. For example, "/test/name?ndn.ChildSelector=1"
Jeff Thompson13e280b2013-12-03 13:12:23 -0800120 */
Alexander Afanasyev197e5652014-06-13 16:56:31 -0700121 std::string
Jeff Thompson13e280b2013-12-03 13:12:23 -0800122 toUri() const;
Jeff Thompsonb7f95562013-07-03 18:36:42 -0700123
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -0700124public: // Link and forwarding hint
125
126 /**
127 * @brief Check whether the Interest contains a Link object
128 * @return True if there is a link object, otherwise false
129 */
130 bool
131 hasLink() const;
132
133 /**
134 * @brief Get the link object for this interest
135 * @return The link object if there is one contained in this interest
136 * @throws Interest::Error if there is no link object contained in the interest
137 */
138 Link
139 getLink() const;
140
141 /**
142 * @brief Set the link object for this interest
143 * @param link The link object that will be included in this interest (in wire format)
144 * @post !hasSelectedDelegation()
145 */
146 void
147 setLink(const Block& link);
148
149 /**
150 *@brief Reset the wire format of the given interest and the contained link
151 */
152 void
153 unsetLink();
154
155 /**
156 * @brief Check whether the Interest includes a selected delegation
157 * @return True if there is a selected delegation, otherwise false
158 */
159 bool
160 hasSelectedDelegation() const;
161
162 /**
163 * @brief Get the name of the selected delegation
164 * @return The name of the selected delegation
165 * @throw Error SelectedDelegation is not set.
166 */
167 Name
168 getSelectedDelegation() const;
169
170 /**
171 * @brief Set the selected delegation
172 * @param delegationName The name of the selected delegation
173 * @throw Error Link is not set.
174 * @throw std::invalid_argument @p delegationName does not exist in Link.
175 */
176 void
177 setSelectedDelegation(const Name& delegationName);
178
179 /**
180 * @brief Set the selected delegation
181 * @param delegation The index of the selected delegation
182 * @throw Error Link is not set.
183 * @throw std::out_of_range @p delegationIndex is out of bound in Link.
184 */
185 void
186 setSelectedDelegation(size_t delegationIndex);
187
188 /**
189 * @brief Unset the selected delegation
190 */
191 void
192 unsetSelectedDelegation();
193
Junxiao Shi2af905b2014-11-27 13:10:54 -0700194public: // matching
195 /** @brief Check if Interest, including selectors, matches the given @p name
196 * @param name The name to be matched. If this is a Data name, it shall contain the
197 * implicit digest component
Alexander Afanasyev84681982014-01-03 13:26:09 -0800198 */
199 bool
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700200 matchesName(const Name& name) const;
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800201
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700202 /**
203 * @brief Check if Interest can be satisfied by @p data.
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700204 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700205 * This method considers Name, MinSuffixComponents, MaxSuffixComponents,
206 * PublisherPublicKeyLocator, and Exclude.
207 * This method does not consider ChildSelector and MustBeFresh.
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700208 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700209 * @todo recognize implicit digest component
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700210 */
211 bool
212 matchesData(const Data& data) const;
213
Junxiao Shi2af905b2014-11-27 13:10:54 -0700214public: // Name and guiders
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700215 const Name&
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800216 getName() const
Jeff Thompsonc0486c12013-07-16 14:36:16 -0700217 {
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800218 return m_name;
219 }
220
221 Interest&
222 setName(const Name& name)
223 {
224 m_name = name;
225 m_wire.reset();
226 return *this;
Jeff Thompsonc0486c12013-07-16 14:36:16 -0700227 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700228
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700229 const time::milliseconds&
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800230 getInterestLifetime() const
231 {
232 return m_interestLifetime;
233 }
234
235 Interest&
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700236 setInterestLifetime(const time::milliseconds& interestLifetime)
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800237 {
238 m_interestLifetime = interestLifetime;
239 m_wire.reset();
240 return *this;
241 }
242
Junxiao Shi2af905b2014-11-27 13:10:54 -0700243 /** @brief Check if Nonce set
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300244 */
245 bool
246 hasNonce() const
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800247 {
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300248 return m_nonce.hasWire();
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800249 }
250
Junxiao Shi2af905b2014-11-27 13:10:54 -0700251 /** @brief Get Interest's nonce
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300252 *
Junxiao Shi2af905b2014-11-27 13:10:54 -0700253 * If nonce was not set before this call, it will be automatically assigned to a random value
254 */
255 uint32_t
256 getNonce() const;
257
258 /** @brief Set Interest's nonce
259 *
260 * If wire format already exists, this call simply replaces nonce in the
261 * existing wire format, without resetting and recreating it.
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300262 */
263 Interest&
264 setNonce(uint32_t nonce);
265
Junxiao Shi2af905b2014-11-27 13:10:54 -0700266 /** @brief Refresh nonce
Alexander Afanasyevc3932172014-07-10 18:53:56 -0700267 *
Junxiao Shi2af905b2014-11-27 13:10:54 -0700268 * It's guaranteed that new nonce value differs from the existing one.
Alexander Afanasyevc3932172014-07-10 18:53:56 -0700269 *
Junxiao Shi2af905b2014-11-27 13:10:54 -0700270 * If nonce is already set, it will be updated to a different random value.
271 * If nonce is not set, this method does nothing.
Alexander Afanasyevc3932172014-07-10 18:53:56 -0700272 */
273 void
274 refreshNonce();
275
Junxiao Shi2af905b2014-11-27 13:10:54 -0700276public: // local control header
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800277 nfd::LocalControlHeader&
278 getLocalControlHeader()
279 {
280 return m_localControlHeader;
281 }
282
283 const nfd::LocalControlHeader&
284 getLocalControlHeader() const
285 {
286 return m_localControlHeader;
287 }
288
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800289 uint64_t
290 getIncomingFaceId() const
291 {
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800292 return getLocalControlHeader().getIncomingFaceId();
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800293 }
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800294
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800295 Interest&
296 setIncomingFaceId(uint64_t incomingFaceId)
297 {
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800298 getLocalControlHeader().setIncomingFaceId(incomingFaceId);
Alexander Afanasyev5964fb72014-02-18 12:42:45 -0800299 // ! do not reset Interest's wire !
300 return *this;
301 }
302
Alexander Afanasyev5964fb72014-02-18 12:42:45 -0800303 uint64_t
304 getNextHopFaceId() const
305 {
306 return getLocalControlHeader().getNextHopFaceId();
307 }
308
309 Interest&
310 setNextHopFaceId(uint64_t nextHopFaceId)
311 {
312 getLocalControlHeader().setNextHopFaceId(nextHopFaceId);
313 // ! do not reset Interest's wire !
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800314 return *this;
315 }
316
Junxiao Shi2af905b2014-11-27 13:10:54 -0700317public: // Selectors
318 /**
319 * @return true if Interest has any selector present
320 */
321 bool
322 hasSelectors() const
323 {
324 return !m_selectors.empty();
325 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700326
Junxiao Shi2af905b2014-11-27 13:10:54 -0700327 const Selectors&
328 getSelectors() const
329 {
330 return m_selectors;
331 }
332
333 Interest&
334 setSelectors(const Selectors& selectors)
335 {
336 m_selectors = selectors;
337 m_wire.reset();
338 return *this;
339 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700340
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800341 int
342 getMinSuffixComponents() const
343 {
344 return m_selectors.getMinSuffixComponents();
345 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700346
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800347 Interest&
348 setMinSuffixComponents(int minSuffixComponents)
349 {
350 m_selectors.setMinSuffixComponents(minSuffixComponents);
351 m_wire.reset();
352 return *this;
353 }
354
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800355 int
356 getMaxSuffixComponents() const
357 {
358 return m_selectors.getMaxSuffixComponents();
359 }
360
361 Interest&
362 setMaxSuffixComponents(int maxSuffixComponents)
363 {
364 m_selectors.setMaxSuffixComponents(maxSuffixComponents);
365 m_wire.reset();
366 return *this;
367 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700368
Junxiao Shib332e782014-03-31 14:23:46 -0700369 const KeyLocator&
370 getPublisherPublicKeyLocator() const
371 {
372 return m_selectors.getPublisherPublicKeyLocator();
373 }
374
375 Interest&
376 setPublisherPublicKeyLocator(const KeyLocator& keyLocator)
377 {
378 m_selectors.setPublisherPublicKeyLocator(keyLocator);
379 m_wire.reset();
380 return *this;
381 }
382
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800383 const Exclude&
384 getExclude() const
385 {
386 return m_selectors.getExclude();
387 }
388
389 Interest&
390 setExclude(const Exclude& exclude)
391 {
392 m_selectors.setExclude(exclude);
393 m_wire.reset();
394 return *this;
395 }
396
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700397 int
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800398 getChildSelector() const
399 {
400 return m_selectors.getChildSelector();
401 }
402
403 Interest&
404 setChildSelector(int childSelector)
405 {
406 m_selectors.setChildSelector(childSelector);
407 m_wire.reset();
408 return *this;
409 }
410
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700411 int
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800412 getMustBeFresh() const
413 {
414 return m_selectors.getMustBeFresh();
415 }
416
417 Interest&
418 setMustBeFresh(bool mustBeFresh)
419 {
420 m_selectors.setMustBeFresh(mustBeFresh);
421 m_wire.reset();
422 return *this;
423 }
424
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700425public: // EqualityComparable concept
426 bool
427 operator==(const Interest& other) const
428 {
429 return wireEncode() == other.wireEncode();
430 }
431
432 bool
433 operator!=(const Interest& other) const
434 {
435 return !(*this == other);
436 }
437
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800438private:
439 Name m_name;
440 Selectors m_selectors;
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300441 mutable Block m_nonce;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700442 time::milliseconds m_interestLifetime;
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800443
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -0700444 mutable Block m_link;
445 size_t m_selectedDelegationIndex;
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800446 mutable Block m_wire;
Yingdi Yua4e57672014-02-06 11:16:17 -0800447
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800448 nfd::LocalControlHeader m_localControlHeader;
449 friend class nfd::LocalControlHeader;
Jeff Thompsonb7f95562013-07-03 18:36:42 -0700450};
Alexander Afanasyev84681982014-01-03 13:26:09 -0800451
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700452std::ostream&
453operator<<(std::ostream& os, const Interest& interest);
Alexander Afanasyev84681982014-01-03 13:26:09 -0800454
455inline std::string
456Interest::toUri() const
457{
458 std::ostringstream os;
459 os << *this;
460 return os.str();
461}
462
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800463} // namespace ndn
464
465#endif // NDN_INTEREST_HPP