NFD » ndn-cxx

Please define the TLV wire format for an link object, including TLV-TYPE code assignments.

Link Design.pdf lacks the exact encoding of Content.

As I see in link.pdf, a Link in section 1 is encoded as:

<Data>
  <Name>
    <NameComponent>net</NameComponent>
    <NameComponent>ndnsim</NameComponent>
    <NameComponent>LINK</NameComponent>
  </Name>
  <MetaInfo>
    <ContentType>1</ContentType>
  </MetaInfo>
  <Content>
    <ContenttypeLink>
      <LinkPair>
        <Pref>100</Pref>
        <Name>
          <NameComponent>att</NameComponent>
          <NameComponent>user</NameComponent>
          <NameComponent>alex</NameComponent>
          <NameComponent>net</NameComponent>
          <NameComponent>ndnsim</NameComponent>
        </Name>
      </LinkPair>
      <LinkPair>
        <Pref>10</Pref>
        <Name>
          <NameComponent>verizon</NameComponent>
          <NameComponent>user</NameComponent>
          <NameComponent>alex</NameComponent>
          <NameComponent>net</NameComponent>
          <NameComponent>ndnsim</NameComponent>
        </Name>
      </LinkPair>
    </ContenttypeLink>
  </Content>
  <SignatureInfo>...</SignatureInfo>
  <SignatureBits>...</SignatureBits>
</Data>

This <ContenttypeLink> element looks weird.

Section 3 mentions something about Interest modification. Does this affect wire format? If so, define the wire format.

As I see in note-13 link.pdf, a Link in section 1 is encoded as:

<Data>
  <Name>
    <NameComponent>net</NameComponent>
    <NameComponent>ndnsim</NameComponent>
    <NameComponent>LINK</NameComponent>
  </Name>
  <MetaInfo>
    <ContentType>1</ContentType>
  </MetaInfo>
  <Content>
    <Linkpair>
      <Pref>100</Pref>
      <Name>
        <NameComponent>att</NameComponent>
        <NameComponent>user</NameComponent>
        <NameComponent>alex</NameComponent>
        <NameComponent>net</NameComponent>
        <NameComponent>ndnsim</NameComponent>
      </Name>
    </Linkpair>
    <Linkpair>
      <Pref>10</Pref>
      <Name>
        <NameComponent>verizon</NameComponent>
        <NameComponent>user</NameComponent>
        <NameComponent>alex</NameComponent>
        <NameComponent>net</NameComponent>
        <NameComponent>ndnsim</NameComponent>
      </Name>
    </Linkpair>
  </Content>
  <SignatureInfo>...</SignatureInfo>
  <SignatureBits>...</SignatureBits>
</Data>

Please confirm this is precise.

TLV-TYPE codes for <Linkpair> and <Pref> elements are unassigned.

(yes I saw the assignments for <LinkPreference> <LinkDelegation> <SelectedDelegation> but the element names need to match precisely)

What are CONTENT-TLV LINKPAIR-TLV PREF-TLV?

If you are referring to the type code, it shall be written as CONTENT-TYPE, etc.

The extension to Interest in section 5 is missing the declaration of <SelectedDelegation> element.

Also, explain why <Link> <SelectedDelegation> elements should appear after <InterestLifetime>, instead of in some other position inside the Interest.

Yes, this is precise.
The type of LinkContent is the typical Content. The type of the Delegation is the LinkDelegation noted as number 31. The Type of Preference is the LinkPreference noted as the number 30. The SelectedDelegation is the forwarding hint and its type is the SelectedDelegated noted as the number 32. The SelectedDelegation field is a NonNegativeInteger. You are right that this part of the document is confusing, so I will update it to make these points clear enough.

Moreover, I followed the guidelines and the Interest format proposed by the related memo, which was submitted for publication lately. In this paper, the field was placed after the field and the field after the field.

From note-20 link.pdf:

I can see an Interest is encoded as: (please confirm this is accurate)

<Interest>
  <Name>..</Name>
  <Nonce>..</Nonce>
  <Data>
    <Name>
      <NameComponent>net</NameComponent>
      <NameComponent>ndnsim</NameComponent>
      <NameComponent>LINK</NameComponent>
    </Name>
    <MetaInfo>
      <ContentType>1</ContentType>
    </MetaInfo>
    <Content>
      <LinkDelegation>
        <LinkPreference>100</LinkPreference>
        <Name>
          <NameComponent>att</NameComponent>
          <NameComponent>user</NameComponent>
          <NameComponent>alex</NameComponent>
          <NameComponent>net</NameComponent>
          <NameComponent>ndnsim</NameComponent>
        </Name>
      </LinkDelegation>
      <LinkDelegation>
        <LinkPreference>10</LinkPreference>
        <Name>
          <NameComponent>verizon</NameComponent>
          <NameComponent>user</NameComponent>
          <NameComponent>alex</NameComponent>
          <NameComponent>net</NameComponent>
          <NameComponent>ndnsim</NameComponent>
        </Name>
      </LinkDelegation>
    </Content>
    <SignatureInfo>...</SignatureInfo>
    <SignatureBits>...</SignatureBits>
  </Data>
  <SelectedDelegation>
    1
  </SelectedDelegation>
</Interest>

Define the semantics of SelectedDelegation.

I guess it must be less than COUNT(/Interest/Data[MetaInfo/ContentType==1]/Content/LinkDelegation)? This rule needs to be made explicit.

Typo: "LINKP-REFERENCE-TLV" should be "LINK-PREFERENCE-TYPE".

Earlier I was annoyed by these static methods:

  /**
   * @brief Get the name of the selected delegation for the given block and index
   * @param block The block format of the Link
   * @param delegation The index of the selected delegation
   * @return The name of the selected delegation
   */
  static Name
  getDelegationName(const Block& block, size_t delegation);

  /**
   * @brief Get the selected delegation index for the given block and Name
   * @param block The block format of the Link
   * @param delegation The name of the selected Delegation
   * @return The index of the selected delegation
   */
  static size_t
  getDelegationIndex(const Block& block, const Name& delegation);

Alex explained in 20150410 conference call that these methods allow a router to peek into a Link object without decoding, but I'm not convinced.

However, I realize that these methods are required for correct operation, because:

• At protocol level, delegations in Link object is unordered.
• SelectedDelegation field refers to the index of delegation in wire format.
• ndn::Link type does not preserve the order of delegations from wire.

Therefore, decoding Link element into ndn::Link may change the order of delegations, and therefore SelectedDelegation no longer indexes the correct delegation.

I suggest changing the code as follows:

/** \brief gets the delegation at \p index from \p block
 *  \param block wire format of a Link object
 *  \param index 0-based index of a delegation in the Link object
 *  \return delegation preference and name
 *  \throw std::out_of_range index is out of range
 */
static std::tuple<uint32_t, Name>
getDelegationFromWire(const Block& block, size_t index);

/** \brief finds index of a delegation with \p delegationName from \p block
 *  \param block wire format of a Link object
 *  \return 0-based index of the first delegation with \p delegationName ,
 *          or -1 if no such delegation exists
 */
static ssize_t
findDelegationFromWire(const Block& block, const Name& delegationName);

And also add a warning to Link::wireDecode:

\warning This method does not preserve the relative order between delegations.
         To get a delegation by index, use \p getDelegationFromWire method.

+1 for the updated interface.