Adding documentation for link object
Change-Id: Ied40e45296fb25b7efd227e2e13a2af48223ba1b
diff --git a/changelog.rst b/changelog.rst
index 5895c8b..4c6ec4a 100644
--- a/changelog.rst
+++ b/changelog.rst
@@ -1,6 +1,17 @@
Changes
=======
+Since version 0.2
+-----------------
+
+- Add definition of Link Object
+
+- **Interest**
+
+ + Add specification of Link and SelectedDelegation fields
+
+************************************************************
+
Since version 0.1.1
-------------------
@@ -26,6 +37,8 @@
+ Reserve 800-1000 range for link protocol
+************************************************************
+
Since version 0.1
-----------------
@@ -36,6 +49,8 @@
+ ``KeyLocator`` field is now defined to be optionally present in generic ``SignatureInfo`` block.
``SignatureSha256WithRsa`` and ``SignatureSha256WithEcdsa`` still require ``KeyLocator`` to be always present.
+************************************************************
+
Since CCNx 0.7.2
----------------
diff --git a/conf.py b/conf.py
index be0b9a7..5aa27b3 100644
--- a/conf.py
+++ b/conf.py
@@ -41,16 +41,16 @@
# General information about the project.
project = u'NDN Packet Format Specification'
-copyright = u'2013-2014, NDN Project Team'
+copyright = u'2013-2016, NDN Project Team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
-version = '0.2'
+version = '0.2-1'
# The full version, including alpha/beta/rc tags.
-release = '0.2'
+release = '0.2-1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/data.rst b/data.rst
index 39be231..7948bd6 100644
--- a/data.rst
+++ b/data.rst
@@ -48,7 +48,7 @@
| BLOB | 0 | payload identified by the data name; this is the default |
| | | ContentType |
+-----------------+----------------+--------------------------------------------------------------+
-| LINK | 1 | another name which identifies the actual data content |
+| LINK | 1 | a list of delegations (see :ref:`link`) |
+-----------------+----------------+--------------------------------------------------------------+
| KEY | 2 | public key |
+-----------------+----------------+--------------------------------------------------------------+
diff --git a/index.rst b/index.rst
index 1fb1b6e..b6b4df2 100644
--- a/index.rst
+++ b/index.rst
@@ -10,6 +10,7 @@
interest
data
signature
+ link
types
changelog
:maxdepth: 3
diff --git a/interest.rst b/interest.rst
index a6d7460..fa5de11 100644
--- a/interest.rst
+++ b/interest.rst
@@ -12,6 +12,8 @@
Selectors?
Nonce
InterestLifetime?
+ Link?
+ SelectedDelegation?
``Name`` and ``Nonce`` are the only two required elements in an Interest packet.
Selectors are optional elements that further qualify Data that may match the Interest.
@@ -172,3 +174,28 @@
It is the application that sets the value for ``InterestLifetime``.
If the ``InterestLifetime`` element is omitted, a default value of 4 seconds is used (4000).
The missing element may be added before forwarding.
+
+Link
+~~~~
+
+The format is the following::
+
+ Link ::= LinkObject
+
+``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.
+
+See the :ref:`link` section for formal definition of the ``LinkObject``.
+
+Selected Delegation
+~~~~~~~~~~~~~~~~~~~
+
+The SelectedDelegation field indicates the index of the delegation in the attached ``Link`` that was chosen by a downstream forwarder(s).
+
+The format is the following::
+
+ SelectedDelegation ::= SELECTED-DELEGATION-TYPE TLV-LENGTH
+ nonNegativeInteger
+
+If ``Link`` field is not present, the ``SelectedDelegation`` field MUST NOT be present.
+
+The index value of the ``SelectedDelegation`` field MUST be less than the number of delegations within the ``Link``.
diff --git a/intro.rst b/intro.rst
index 3acb3f9..ce227d6 100644
--- a/intro.rst
+++ b/intro.rst
@@ -2,7 +2,7 @@
------------
This version of specification aims to describe the NDN packet format only, a much narrower scope than a full NDN protocol specification.
-Full protocol specification will be published as a separate document. For more information about the overall protocol refer to `"Named Data Networking" by Lixia Zhang, Alexander Afanasyev, Jeffrey Burke, Van Jacobson, kc claffy, Patrick Crowley, Christos Papadopoulos, Lan Wang, and Beichuan Zhang, ACM SIGCOMM Computer Communication Review (CCR), July 2014.`__ and other publications on `Named Data Networking website <https://named-data.net>`__.
+Full protocol specification will be published as a separate document. For more information about the overall protocol refer to `"Named Data Networking" by Lixia Zhang, Alexander Afanasyev, Jeffrey Burke, Van Jacobson, kc claffy, Patrick Crowley, Christos Papadopoulos, Lan Wang, and Beichuan Zhang, ACM SIGCOMM Computer Communication Review (CCR), July 2014 <https://named-data.net/publications/named_data_networking_ccr/>`__ and other publications on `Named Data Networking website <https://named-data.net>`__.
In addition to the packet format and full protocol specification, we have published a set of technical memos and papers that explain the reasoning behind the design choices:
@@ -17,4 +17,4 @@
Acknowledgment
--------------
-This NDN packet format specification is evolution of the `CCNx 0.7.2 specification <https://github.com/named-data/ndnx/releases/tag/ccnx-0.7.2-ndn-1>`_ as of May 2013.
+This NDN packet format specification is evolution of the `CCNx 0.7.2 specification <https://github.com/named-data/ndnx/releases/tag/ccnx-0.7.2-ndn-1>`__ as of May 2013.
diff --git a/link.rst b/link.rst
new file mode 100644
index 0000000..f0c2199
--- /dev/null
+++ b/link.rst
@@ -0,0 +1,49 @@
+.. _link:
+
+Link Object
+-----------
+
+The Link Object is a specialized form of a :ref:`Data packet <data>` packet, defined as follows::
+
+ LinkObject ::= DATA-TLV TLV-LENGTH
+ Name
+ MetaInfo (.ContentType = LINK)
+ LinkContent
+ Signature
+
+ LinkContent ::= CONTENT-TYPE TLV-LENGTH
+ Delegation+
+
+ Delegation ::= LINK-DELEGATION-TYPE TLV-LENGTH
+ Preference
+ Name
+
+ Preference ::= LINK-PREFERENCE-TYPE TLV-LENGTH
+ nonNegativeInteger
+
+
+Link Object is a data packet, whose content contains a list of one or more name delegations: a pair of name and the associate priority.
+The semantical meaning of the delegations depends on the specific use. For example, when LinkObject is used as part of Interest packet, each delegation implies that the requested Data packet can be retrieved by forwarding the interest along the delegation path. Specifics of the forwarding logic for Interests with ``LinkObject`` will be defined in a separated document.
+
+The list of delegations in ``LinkContent`` SHOULD be ordered by preference value in ascending order (i.e., the lowest value first).
+
+In a LinkContent, each Delegation SHOULD have a distinct Name.
+
+
+..
+ Let’s assume that we have files that are published under /net/ndnsim, but are hosted under /att/user/alex/net/ndnsim and /verizon/user/alex/net/ndnsim. The structure of the Link would be the following:
+
+
+ +-----------------+---------------------------------------------+--------------------------------------------------------------+
+ | Link Field | Value | Description of the value |
+ +=================+=============================================+==============================================================+
+ | Name | /net/ndnsim/LINK | Name of the link (as a convention, the last NameComponent |
+ | | | MAY be "LINK") |
+ +-----------------+---------------------------------------------+--------------------------------------------------------------+
+ | MetaInfo | ContentType = LINK | Field that identifies the actual data content |
+ +-----------------+---------------------------------------------+--------------------------------------------------------------+
+ | Content | (/verizon/user/alex/net/ndnsim, 10) | Content in the form of (alias, preference) pairs |
+ | | (/att/user/alex/net/ndnsim, 100) | |
+ +-----------------+---------------------------------------------+--------------------------------------------------------------+
+ | Signature | Varying | Signed by the publisher of the Link |
+ +-----------------+---------------------------------------------+--------------------------------------------------------------+