Options
All
  • Public
  • Public/Protected
  • All
Menu

@ndn/tlv

This package is part of NDNts, Named Data Networking libraries for the modern web.

This package implements Type-Length-Value structure encoder and decoder as specified in NDN Packet Format v0.3. It has full support for TLV evolvability guidelines.

import { Encoder, Decoder, EvDecoder, NNI } from "@ndn/tlv";

// other imports for examples
import { Name, TT as nameTT } from "@ndn/packet";
import { strict as assert } from "assert";

Encoder

The Encoder has an internal buffer of Uint8Array type. It prepends any encodable items to the internal buffer, and reallocates a larger buffer when necessary.

// Encode TLV object that implements EncodableObj interface:
let encoder = new Encoder();
encoder.encode(new Name("/A"));
// Look at the output:
assert.deepEqual(encoder.output, Uint8Array.of(0x07, 0x03, 0x08, 0x01, 0x41));

// Prepend a TLV structure with specified TLV-TYPE and TLV-VALUE:
encoder = new Encoder();
encoder.encode([0xB0, Uint8Array.of(0xC0, 0xC1)]);
assert.deepEqual(encoder.output, Uint8Array.of(0xB0, 0x02, 0xC0, 0xC1));

// Prepend a non-negative integer
encoder.encode(NNI(0x200110));
// We are using the same Encoder instance, so it gets prepended:
assert.deepEqual(encoder.output, Uint8Array.of(0x00, 0x20, 0x01, 0x10, 0xB0, 0x02, 0xC0, 0xC1));

// Put multiple encodable items in TLV-VALUE:
encoder = new Encoder();
encoder.encode([0xB0, Uint8Array.of(0xC0, 0xC1), new Name("/A")]);
assert.deepEqual(encoder.output,
  Uint8Array.of(0xB0, 0x07, 0xC0, 0xC1, 0x07, 0x03, 0x08, 0x01, 0x41));

Decoder

The Decoder is a basic sequential decoder.

// Read Type-Length-Value manually:
let decoder = new Decoder(Uint8Array.of(0x08, 0x01, 0x41, 0xFF));
const { type, length, value } = decoder.read();
assert.equal(type, 0x08);
assert.equal(length, 1);
assert.deepEqual(value, Uint8Array.of(0x41));
// The remaining [0xFF] is still in the buffer.
// If you continue reading, you get an error due to incomplete TLV.
assert.throws(() => decoder.read());

// Decode into TLV object:
decoder = new Decoder(Uint8Array.of(0x07, 0x03, 0x08, 0x01, 0x41));
const name = decoder.decode(Name);
assert(name instanceof Name);
assert.equal(name.toString(), "/8=A");

EvDecoder

The EvDecoder is a decoder that is aware of TLV evolvability guidelines. It's used to implement decoding functions of TLV objects, such as Interest.decodeFrom.

Suppose we want to decode NLSR's LSDB Dataset:

Adjacency = ADJACENCY-TYPE TLV-LENGTH
              Name
              Uri
              Cost
Uri = URI-TYPE TLV-LENGTH *VCHAR
Cost = COST-TYPE TLV-LENGTH nonNegativeInteger

ADJACENCY-TYPE = 0x84
URI-TYPE = 0x8D
COST-TYPE = 0x8C
// Declare a class to represent this type.
class Adjacency {
  public name = new Name();
  public uri = "";
  public cost = 0;
}

// Declare constants for TLV-TYPE numbers.
const TT = {
  ...nameTT,
  Adjacency: 0x84,
  Cost: 0x8C,
  Uri: 0x8D,
};

// Create the decoder.
const EVD = new EvDecoder<Adjacency>("Adjacency", TT.Adjacency)
  .add(TT.Name, (t, { decoder }) => t.name = decoder.decode(Name), { required: true })
  .add(TT.Uri, (t, { text }) => t.uri = text, { required: true })
  .add(TT.Cost, (t, { nni }) => t.cost = nni, { required: true });
// Each rule declares a possible sub TLV.
// They are added in the order of expected appearance.
// The callback receives two arguments:
// (1) the target object we are decoding into, so that EVD instances are reusable;
// (2) a Decoder.Tlv structure, where we can selectively access just the TLV-VALUE, the whole TLV,
//     the TLV-VALUE as a Decoder, the whole TLV as a Decoder, etc.

// Suppose we receive this encoded TLV:
const adjacencyWire = Uint8Array.of(
  0x84, 0x0D,
  0x07, 0x03, 0x08, 0x01, 0x41, // Name
  0x8D, 0x01, 0x42, // Uri
  0xF0, 0x00, // unrecognized non-critical TLV-TYPE, ignored
  0x8C, 0x01, 0x80, // Cost
);
const adjacencyDecoder = new Decoder(adjacencyWire);

// We can decode it with the EVD.
const adjacency = EVD.decode(new Adjacency(), adjacencyDecoder);
assert.equal(adjacency.name.toString(), "/8=A");
assert.equal(adjacency.uri, "B");
assert.equal(adjacency.cost, 128);

Index

References

Decodable

Re-exports Decodable

Decoder

Re-exports Decoder

Encodable

Re-exports Encodable

EncodableObj

Re-exports EncodableObj

EncodableTlv

Re-exports EncodableTlv

Encoder

Re-exports Encoder

EvDecoder

Re-exports EvDecoder

Extensible

Re-exports Extensible

Extension

Re-exports Extension

ExtensionRegistry

Re-exports ExtensionRegistry

NNI

Re-exports NNI

fromHex

Re-exports fromHex

fromUtf8

Re-exports fromUtf8

printTT

Re-exports printTT

toHex

Re-exports toHex

toUtf8

Re-exports toUtf8

Type aliases

ElementCallback

ElementCallback<T>: (target: T, tlv: Tlv) => void

Invoked when a matching TLV element is found.

Type parameters

  • T

Type declaration

    • (target: T, tlv: Tlv): void
    • Parameters

      • target: T
      • tlv: Tlv

      Returns void

Encodable

Encodable: Uint8Array | undefined | EncodableObj | EncodableTlv

An object acceptable to Encoder.encode().

EncodableTlv

EncodableTlv: [number, any]

An encodable TLV structure.

First item is a number for TLV-TYPE. Optional second item could be OmitEmpty to omit the TLV if TLV-VALUE is empty. Subsequent items are Encodables for TLV-VALUE.

IsCriticalCallback

IsCriticalCallback: (tt: number) => boolean

Type declaration

    • (tt: number): boolean
    • Parameters

      • tt: number

      Returns boolean

Len

Len: 1 | 2 | 4 | 8

RuleOptions

RuleOptions<T>: Partial<Omit<Rule<T>, "cb">>

Type parameters

  • T

TopElementCallback

TopElementCallback<T>: (target: T, tlv: Tlv) => void

Type parameters

  • T

Type declaration

    • (target: T, tlv: Tlv): void
    • Parameters

      • target: T
      • tlv: Tlv

      Returns void

UnknownElementCallback

UnknownElementCallback<T>: (target: T, tlv: Tlv, order: number) => boolean

Invoked when a TLV element does not match any rule. 'order' denotes the order number of last recognized TLV element. Return true if this TLV element is accepted, or false to follow evolvability guidelines.

Type parameters

  • T

Type declaration

    • (target: T, tlv: Tlv, order: number): boolean
    • Parameters

      • target: T
      • tlv: Tlv
      • order: number

      Returns boolean

Variables

Const AUTO_ORDER_SKIP

AUTO_ORDER_SKIP: 100 = 100

Let BIG0

BIG0: bigint

Let BIG32

BIG32: bigint

Let BIG64

BIG64: bigint

Const BUF_GROW_SIZE

BUF_GROW_SIZE: 2048 = 2048

Const BUF_INIT_SIZE

BUF_INIT_SIZE: 2048 = 2048

Let decodeBig

decodeBig: (dv: DataView) => bigint

Type declaration

    • (dv: DataView): bigint
    • Parameters

      • dv: DataView

      Returns bigint

Let encodeBig64

encodeBig64: (dv: DataView, n: bigint) => void

Type declaration

    • (dv: DataView, n: bigint): void
    • Parameters

      • dv: DataView
      • n: bigint

      Returns void

Let hexTable

hexTable: string[] | undefined

Const textDecoder

textDecoder: TextDecoder = new TextDecoder()

Const textEncoder

textEncoder: TextEncoder = new TextEncoder()

Functions

decode32

  • decode32(dv: DataView): number

fromHex

  • fromHex(s: string): Uint8Array
  • Convert hexadecimal string to byte array.

    This function lacks error handling. Use on trusted input only.

    Parameters

    • s: string

    Returns Uint8Array

fromUtf8

  • fromUtf8(buf: Uint8Array): string

getHexTable

  • getHexTable(): string[]

isCritical

  • isCritical(tt: number): boolean

nest

printTT

  • printTT(tlvType: number): string

sizeofVarNum

  • sizeofVarNum(n: number): number

toHex

  • toHex(buf: Uint8Array): string

toUtf8

  • toUtf8(s: string): Uint8Array

writeVarNum

  • writeVarNum(room: Uint8Array, off: number, n: number): void

Object literals

Const EncodeNniClass

EncodeNniClass: object

1

1: Nni1 = Nni1

2

2: Nni2 = Nni2

4

4: Nni4 = Nni4

8

8: Nni8Number = Nni8Number

Legend

  • Namespace
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Type alias
  • Type alias with type parameter
  • Interface
  • Interface with type parameter
  • Class
  • Class with type parameter
  • Enumeration

Generated using TypeDoc