blob: b87cd50e1d6d1eb5ae09b7346eb91b0625abb4fd [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 Afanasyevd5c48e02015-06-24 11:58:14 -070092 wireEncode(EncodingImpl<TAG>& encoder) 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
Alexander Afanasyevcac08382015-09-02 14:52:40 -0700137 * @throws tlv::Error if the incorporated link object is malformed
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -0700138 */
Alexander Afanasyevcac08382015-09-02 14:52:40 -0700139 const Link&
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -0700140 getLink() const;
141
142 /**
143 * @brief Set the link object for this interest
144 * @param link The link object that will be included in this interest (in wire format)
145 * @post !hasSelectedDelegation()
146 */
147 void
148 setLink(const Block& link);
149
150 /**
Alexander Afanasyevcac08382015-09-02 14:52:40 -0700151 * @brief Delete the link object for this interest
152 * @post !hasLink()
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -0700153 */
154 void
155 unsetLink();
156
157 /**
158 * @brief Check whether the Interest includes a selected delegation
159 * @return True if there is a selected delegation, otherwise false
160 */
161 bool
162 hasSelectedDelegation() const;
163
164 /**
165 * @brief Get the name of the selected delegation
166 * @return The name of the selected delegation
167 * @throw Error SelectedDelegation is not set.
168 */
169 Name
170 getSelectedDelegation() const;
171
172 /**
173 * @brief Set the selected delegation
174 * @param delegationName The name of the selected delegation
175 * @throw Error Link is not set.
176 * @throw std::invalid_argument @p delegationName does not exist in Link.
177 */
178 void
179 setSelectedDelegation(const Name& delegationName);
180
181 /**
182 * @brief Set the selected delegation
Davide Pesavento18cf81b2015-09-12 23:36:43 +0200183 * @param delegationIndex The index of the selected delegation
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -0700184 * @throw Error Link is not set.
185 * @throw std::out_of_range @p delegationIndex is out of bound in Link.
186 */
187 void
188 setSelectedDelegation(size_t delegationIndex);
189
190 /**
191 * @brief Unset the selected delegation
192 */
193 void
194 unsetSelectedDelegation();
195
Junxiao Shi2af905b2014-11-27 13:10:54 -0700196public: // matching
197 /** @brief Check if Interest, including selectors, matches the given @p name
198 * @param name The name to be matched. If this is a Data name, it shall contain the
199 * implicit digest component
Alexander Afanasyev84681982014-01-03 13:26:09 -0800200 */
201 bool
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700202 matchesName(const Name& name) const;
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800203
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700204 /**
205 * @brief Check if Interest can be satisfied by @p data.
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700206 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700207 * This method considers Name, MinSuffixComponents, MaxSuffixComponents,
208 * PublisherPublicKeyLocator, and Exclude.
209 * This method does not consider ChildSelector and MustBeFresh.
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700210 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700211 * @todo recognize implicit digest component
Junxiao Shiaf8eeea2014-03-31 20:10:56 -0700212 */
213 bool
214 matchesData(const Data& data) const;
215
Junxiao Shi2af905b2014-11-27 13:10:54 -0700216public: // Name and guiders
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700217 const Name&
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800218 getName() const
Jeff Thompsonc0486c12013-07-16 14:36:16 -0700219 {
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800220 return m_name;
221 }
222
223 Interest&
224 setName(const Name& name)
225 {
226 m_name = name;
227 m_wire.reset();
228 return *this;
Jeff Thompsonc0486c12013-07-16 14:36:16 -0700229 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700230
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700231 const time::milliseconds&
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800232 getInterestLifetime() const
233 {
234 return m_interestLifetime;
235 }
236
237 Interest&
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700238 setInterestLifetime(const time::milliseconds& interestLifetime)
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800239 {
240 m_interestLifetime = interestLifetime;
241 m_wire.reset();
242 return *this;
243 }
244
Junxiao Shi2af905b2014-11-27 13:10:54 -0700245 /** @brief Check if Nonce set
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300246 */
247 bool
248 hasNonce() const
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800249 {
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300250 return m_nonce.hasWire();
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800251 }
252
Junxiao Shi2af905b2014-11-27 13:10:54 -0700253 /** @brief Get Interest's nonce
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300254 *
Junxiao Shi2af905b2014-11-27 13:10:54 -0700255 * If nonce was not set before this call, it will be automatically assigned to a random value
256 */
257 uint32_t
258 getNonce() const;
259
260 /** @brief Set Interest's nonce
261 *
262 * If wire format already exists, this call simply replaces nonce in the
263 * existing wire format, without resetting and recreating it.
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300264 */
265 Interest&
266 setNonce(uint32_t nonce);
267
Junxiao Shi2af905b2014-11-27 13:10:54 -0700268 /** @brief Refresh nonce
Alexander Afanasyevc3932172014-07-10 18:53:56 -0700269 *
Junxiao Shi2af905b2014-11-27 13:10:54 -0700270 * It's guaranteed that new nonce value differs from the existing one.
Alexander Afanasyevc3932172014-07-10 18:53:56 -0700271 *
Junxiao Shi2af905b2014-11-27 13:10:54 -0700272 * If nonce is already set, it will be updated to a different random value.
273 * If nonce is not set, this method does nothing.
Alexander Afanasyevc3932172014-07-10 18:53:56 -0700274 */
275 void
276 refreshNonce();
277
Junxiao Shi2af905b2014-11-27 13:10:54 -0700278public: // local control header
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800279 nfd::LocalControlHeader&
280 getLocalControlHeader()
281 {
282 return m_localControlHeader;
283 }
284
285 const nfd::LocalControlHeader&
286 getLocalControlHeader() const
287 {
288 return m_localControlHeader;
289 }
290
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800291 uint64_t
292 getIncomingFaceId() const
293 {
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800294 return getLocalControlHeader().getIncomingFaceId();
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800295 }
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800296
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800297 Interest&
298 setIncomingFaceId(uint64_t incomingFaceId)
299 {
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800300 getLocalControlHeader().setIncomingFaceId(incomingFaceId);
Alexander Afanasyev5964fb72014-02-18 12:42:45 -0800301 // ! do not reset Interest's wire !
302 return *this;
303 }
304
Alexander Afanasyev5964fb72014-02-18 12:42:45 -0800305 uint64_t
306 getNextHopFaceId() const
307 {
308 return getLocalControlHeader().getNextHopFaceId();
309 }
310
311 Interest&
312 setNextHopFaceId(uint64_t nextHopFaceId)
313 {
314 getLocalControlHeader().setNextHopFaceId(nextHopFaceId);
315 // ! do not reset Interest's wire !
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800316 return *this;
317 }
318
Junxiao Shi2af905b2014-11-27 13:10:54 -0700319public: // Selectors
320 /**
321 * @return true if Interest has any selector present
322 */
323 bool
324 hasSelectors() const
325 {
326 return !m_selectors.empty();
327 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700328
Junxiao Shi2af905b2014-11-27 13:10:54 -0700329 const Selectors&
330 getSelectors() const
331 {
332 return m_selectors;
333 }
334
335 Interest&
336 setSelectors(const Selectors& selectors)
337 {
338 m_selectors = selectors;
339 m_wire.reset();
340 return *this;
341 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700342
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800343 int
344 getMinSuffixComponents() const
345 {
346 return m_selectors.getMinSuffixComponents();
347 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700348
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800349 Interest&
350 setMinSuffixComponents(int minSuffixComponents)
351 {
352 m_selectors.setMinSuffixComponents(minSuffixComponents);
353 m_wire.reset();
354 return *this;
355 }
356
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800357 int
358 getMaxSuffixComponents() const
359 {
360 return m_selectors.getMaxSuffixComponents();
361 }
362
363 Interest&
364 setMaxSuffixComponents(int maxSuffixComponents)
365 {
366 m_selectors.setMaxSuffixComponents(maxSuffixComponents);
367 m_wire.reset();
368 return *this;
369 }
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700370
Junxiao Shib332e782014-03-31 14:23:46 -0700371 const KeyLocator&
372 getPublisherPublicKeyLocator() const
373 {
374 return m_selectors.getPublisherPublicKeyLocator();
375 }
376
377 Interest&
378 setPublisherPublicKeyLocator(const KeyLocator& keyLocator)
379 {
380 m_selectors.setPublisherPublicKeyLocator(keyLocator);
381 m_wire.reset();
382 return *this;
383 }
384
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800385 const Exclude&
386 getExclude() const
387 {
388 return m_selectors.getExclude();
389 }
390
391 Interest&
392 setExclude(const Exclude& exclude)
393 {
394 m_selectors.setExclude(exclude);
395 m_wire.reset();
396 return *this;
397 }
398
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700399 int
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800400 getChildSelector() const
401 {
402 return m_selectors.getChildSelector();
403 }
404
405 Interest&
406 setChildSelector(int childSelector)
407 {
408 m_selectors.setChildSelector(childSelector);
409 m_wire.reset();
410 return *this;
411 }
412
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700413 int
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800414 getMustBeFresh() const
415 {
416 return m_selectors.getMustBeFresh();
417 }
418
419 Interest&
420 setMustBeFresh(bool mustBeFresh)
421 {
422 m_selectors.setMustBeFresh(mustBeFresh);
423 m_wire.reset();
424 return *this;
425 }
426
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700427public: // EqualityComparable concept
428 bool
429 operator==(const Interest& other) const
430 {
431 return wireEncode() == other.wireEncode();
432 }
433
434 bool
435 operator!=(const Interest& other) const
436 {
437 return !(*this == other);
438 }
439
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800440private:
441 Name m_name;
442 Selectors m_selectors;
Alexander Afanasyeve881e932014-06-08 14:47:03 +0300443 mutable Block m_nonce;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700444 time::milliseconds m_interestLifetime;
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800445
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -0700446 mutable Block m_link;
Alexander Afanasyevcac08382015-09-02 14:52:40 -0700447 mutable shared_ptr<Link> m_linkCached;
Spyridon Mastorakisc8188b32015-04-18 18:33:38 -0700448 size_t m_selectedDelegationIndex;
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800449 mutable Block m_wire;
Yingdi Yua4e57672014-02-06 11:16:17 -0800450
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800451 nfd::LocalControlHeader m_localControlHeader;
452 friend class nfd::LocalControlHeader;
Jeff Thompsonb7f95562013-07-03 18:36:42 -0700453};
Alexander Afanasyev84681982014-01-03 13:26:09 -0800454
Alexander Afanasyevff2d08f2014-04-07 18:28:25 -0700455std::ostream&
456operator<<(std::ostream& os, const Interest& interest);
Alexander Afanasyev84681982014-01-03 13:26:09 -0800457
458inline std::string
459Interest::toUri() const
460{
461 std::ostringstream os;
462 os << *this;
463 return os.str();
464}
465
Alexander Afanasyevc348f832014-02-17 16:35:17 -0800466} // namespace ndn
467
468#endif // NDN_INTEREST_HPP