blob: 70271e39600bce972e9765c707a39c378116ae04 [file] [log] [blame]
Alexander Afanasyeve2800232013-11-27 02:24:14 +00001.. _Interest:
Alexander Afanasyeveee8c252013-11-21 23:22:41 +00002
3Interest Packet
4---------------
5
Alexander Afanasyeve2800232013-11-27 02:24:14 +00006NDN Interest packet is TLV defined as follows:
7
8::
Alexander Afanasyeveee8c252013-11-21 23:22:41 +00009
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -070010 Interest ::= INTEREST-TYPE TLV-LENGTH
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000011 Name
12 Selectors?
13 Nonce
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000014 InterestLifetime?
spirosmastorakis988e7412016-10-27 14:01:59 -070015 Link?
16 SelectedDelegation?
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000017
Alexander Afanasyev7455e9b2014-06-25 09:41:08 -070018``Name`` and ``Nonce`` are the only two required elements in an Interest packet.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000019Selectors are optional elements that further qualify Data that may match the Interest.
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -070020They are used for discovering and selecting the Data that matches best to what the application wants. Selectors are placed right after the Name to facilitate implementations that may use continuous memory block of Name and Selectors TLVs together as the index for PIT lookup. By using a TLV to group all the Selectors, an implementation can easily skip them to find Nonce, which is used together with Name to identify looping Interests.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000021If Selectors TLV is present in the Interest, it MUST contain at least one selector.
22
Junxiao Shibdc75012015-01-13 22:09:12 -070023``InterestLifetime`` is optional and is referred to as a *Guider*.
24It affects Interest forwarding behavior, i.e., how long an Interest may be kept in the PIT.
25
26.. Guiders are not grouped.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000027
28
29Name
30~~~~
31
Alexander Afanasyeve2800232013-11-27 02:24:14 +000032The Name element in an Interest is synonymous with the term *prefix*.
33See :ref:`Name section <Name>` for details.
34
Alexander Afanasyev25286362016-09-05 20:55:25 -070035The Name element that can be put in the Interest is further restricted to have at least one NameComponent.
36Interests that include Name TLV that has zero name components MUST BE discarded.
37
Alexander Afanasyeve2800232013-11-27 02:24:14 +000038.. _Selectors:
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000039
40Selectors
41~~~~~~~~~
Alexander Afanasyeve2800232013-11-27 02:24:14 +000042
43::
44
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -070045 Selectors ::= SELECTORS-TYPE TLV-LENGTH
Alexander Afanasyeve2800232013-11-27 02:24:14 +000046 MinSuffixComponents?
47 MaxSuffixComponents?
48 PublisherPublicKeyLocator?
49 Exclude?
50 ChildSelector?
51 MustBeFresh?
52
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000053MinSuffixComponents, MaxSuffixComponents
54++++++++++++++++++++++++++++++++++++++++
55
Alexander Afanasyeve2800232013-11-27 02:24:14 +000056::
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000057
58 MinSuffixComponents ::= MIN-SUFFIX-COMPONENTS-TYPE TLV-LENGTH
59 nonNegativeInteger
60
61 MaxSuffixComponents ::= MAX-SUFFIX-COMPONENTS-TYPE TLV-LENGTH
62 nonNegativeInteger
63
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -070064When needed, ``MinSuffixComponents`` and ``MaxSuffixComponents`` allow a data consumer to indicate whether the Name in the Interest is the full name including the digest, or the full name except for the digest, or the content it is seeking has a known range of legitimate component counts.
65These two parameters refer to the number of name components beyond those in the prefix, and counting the implicit digest, that may occur in the matching Data.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000066The default for ``MinSuffixComponents`` is 0 and for ``MaxSuffixComponents`` is effectively infinite, meaning that any Data whose name starts with the prefix is a match. Often only one of these will be needed to get the desired effect.
67
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -070068
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000069PublisherPublicKeyLocator
70+++++++++++++++++++++++++
71
Alexander Afanasyeve2800232013-11-27 02:24:14 +000072::
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000073
Alexander Afanasyev23c2e412014-02-12 19:53:48 +000074 PublisherPublicKeyLocator ::= KeyLocator
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000075
76This element specifies the name of the key which is used to sign the Data packet that the consumer is requesting.
77This is a way for the Interest to select answers from a particular publisher.
78
Alexander Afanasyev23c2e412014-02-12 19:53:48 +000079See :ref:`KeyLocator` section for more detail.
80
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000081Exclude
82+++++++
83
Alexander Afanasyeve2800232013-11-27 02:24:14 +000084::
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000085
Cenk Gündoğan9c0dbbd2016-09-14 19:21:07 +020086 Exclude ::= EXCLUDE-TYPE TLV-LENGTH AnyLeading? (NameComponent | AnyBetween)* AnyTrailing?
87 AnyLeading ::= Any NameComponent
88 AnyBetween ::= NameComponent Any NameComponent
89 AnyTrailing ::= NameComponent Any
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000090 Any ::= ANY-TYPE TLV-LENGTH(=0)
91
Cenk Gündoğanbc5f0ec2016-09-14 15:49:52 +020092The ``Exclude`` selectors allow requesters to specify list and/or ranges of name components that MUST NOT appear as a continuation of the Name prefix in the responding Data packet to the Interest.
Alexander Afanasyev4b8be212014-10-06 10:55:04 -070093For example, if Interest is expressed for ``/ndn/edu`` and Exclude specifies one name component ``ucla``, then neither data producer nor conforming NDN routers are allowed to return any Data packet that has prefix ``/ndn/edu/ucla``.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +000094
95Exclude filter applies only to a name component of the Data packet name that is located at a position that numerically equals to the number of name components in the Interest packet, assuming 0 is the first name component.
96
97The Components in the exclusion list MUST occur in strictly increasing order according to the canonical NDN name component ordering (:ref:`Name Section<name>`), with optional leading, trailing, and interleaved ``Any`` components. The following defines processing of ``Any`` components:
98
Cenk Gündoğanbc5f0ec2016-09-14 15:49:52 +020099- If none of the ``Any`` components are specified, the filter excludes only the names specified in the Exclude list.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000100
101- If a leading ``Any`` component is specified, then the filter excludes all names that are smaller or equal (in NDN name component canonical ordering) to the first NameComponent in the Exclude list.
102
103- If a trailing ``Any`` component is specified, then the filter excludes all names that are larger or equal (in NDN name component canonical ordering) to the last NameComponent in the Exclude list.
104
105- If ``Any`` component is specified between two NameComponents in the list, then the filter excludes all names from the range from the right NameComponent to the left NameComponent, including both ends.
106
107
Alexander Afanasyeve2800232013-11-27 02:24:14 +0000108Exclude filter MUST not consist of a single ``Any`` component or one NameComponent with leading and trailing ``Any`` components.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000109
110
111ChildSelector
112+++++++++++++
113
Alexander Afanasyeve2800232013-11-27 02:24:14 +0000114::
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000115
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -0700116 ChildSelector ::= CHILD-SELECTOR-TYPE TLV-LENGTH
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000117 nonNegativeInteger
118
119Often a given Interest can match more than one Data within a given content store.
120The ``ChildSelector`` provides a way of expressing a preference for which of these should be returned.
121If the value is 0, the leftmost child is preferred.
122If 1, the rightmost child is preferred.
123Here leftmost and rightmost refer to the least and greatest components according to the canonical NDN name component ordering (:ref:`Name Section<name>`).
124This ordering is only done at the level of the name hierarchy one past the name prefix.
Eric Newberry1c799952017-05-20 20:56:16 -0700125If the ``ChildSelector`` field is not present, the leftmost child is preferred (a value of 0).
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000126
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -0700127For example, assuming in the name hierarchy the component immediately after the name prefix is the version number, whose next level is the segment number, then setting ChildSelector to be 1 will retrieve the rightmost version number (i.e., the latest version) and the leftmost segment number (i.e., the first segment). However, this selection is only done with respect to a single content store, not globally. Additional rounds that exclude the earlier versions may be used to explore other content stores for newer versions.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000128In this case, the use of ChildSelector does not change the multi-round outcome, but it decreases the number of rounds needed to converge to an answer.
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -0700129
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000130MustBeFresh
131+++++++++++
132
Alexander Afanasyeve2800232013-11-27 02:24:14 +0000133::
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000134
135 MustBeFresh ::= MUST-BE-FRESH-TYPE TLV-LENGTH(=0)
136
137This selector is encoded with Type and Length but no Value part.
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -0700138When it is absent from an Interest packet, the router can respond with a Data packet from its content store whose FreshnessPeriod is either still valid or expired.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000139When it is present in an Interest packet, the router should not return Data packet from its content store whose FreshnessPeriod has expired.
140
141The FreshnessPeriod carried in each Data packet (:ref:`Data Section<data>`) is set by the original producer. It starts counting down when the Data packet arrives at a node. Consequently if a node is N hops away from the original producer, it may not consider the Data stale until N *X* FreshnessPeriod after the Data is produced.
142
Alexander Afanasyevfffabfb2013-12-11 21:29:05 +0000143.. _Nonce:
144
145Nonce
146~~~~~
147
148Nonce defined as follows:
149
150::
151
152 Nonce ::= NONCE-TYPE TLV-LENGTH(=4) BYTE{4}
153
Alexander Afanasyev4b896112014-06-23 21:47:15 -0700154The Nonce carries a randomly-generated 4-octet long byte-string.
Alexander Afanasyevfffabfb2013-12-11 21:29:05 +0000155The combination of Name and Nonce should uniquely identify an Interest packet.
156This is used to detect looping Interests.
157
158.. _Guiders:
159
160Guiders
161~~~~~~~
162
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000163InterestLifetime
164++++++++++++++++
165
Alexander Afanasyeve2800232013-11-27 02:24:14 +0000166::
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000167
168 InterestLifetime ::= INTEREST-LIFETIME-TYPE TLV-LENGTH nonNegativeInteger
169
Alexander Afanasyeva6fc7272014-06-13 11:58:06 -0700170``InterestLifetime`` indicates the (approximate) time remaining before the Interest times out.
Alexander Afanasyeveee8c252013-11-21 23:22:41 +0000171The value is the number of milliseconds. The timeout is relative to the arrival time of the Interest at the current node.
172
173Nodes that forward Interests may decrease the lifetime to account for the time spent in the node before forwarding, but are not required to do so. It is recommended that these adjustments be done only for relatively large delays (measured in seconds).
174
175It is the application that sets the value for ``InterestLifetime``.
176If the ``InterestLifetime`` element is omitted, a default value of 4 seconds is used (4000).
177The missing element may be added before forwarding.
spirosmastorakis988e7412016-10-27 14:01:59 -0700178
179Link
180~~~~
181
182The format is the following::
183
184 Link ::= LinkObject
185
186``LinkObject`` is a :ref:`Data packet <data>` of a dedicated ``LINK`` type and specially-formatted content part, listing a set of delegations (name prefixes and the associated priorities) that should be used to guide forwarding of the Internet packet.
187
188See the :ref:`link` section for formal definition of the ``LinkObject``.
189
190Selected Delegation
191~~~~~~~~~~~~~~~~~~~
192
193The SelectedDelegation field indicates the index of the delegation in the attached ``Link`` that was chosen by a downstream forwarder(s).
194
195The format is the following::
196
197 SelectedDelegation ::= SELECTED-DELEGATION-TYPE TLV-LENGTH
198 nonNegativeInteger
199
200If ``Link`` field is not present, the ``SelectedDelegation`` field MUST NOT be present.
201
202The index value of the ``SelectedDelegation`` field MUST be less than the number of delegations within the ``Link``.