Functions for handling packet data

Since a Tvb can only be created from (or passed into) a dissector or listener, these functions can only be called from a dissector or listener. Attempting to use the functions outside of that context results in an error message.

Tvb

A Tvb ("testy virtual buffer"?) represents the packet's buffer. It is passed as an argument to listeners and dissectors, and can be used to extract information (via TvbRange) from the packet's data. Beware that Tvbs are usable only by the current listener or dissector call and are destroyed as soon as the listener/dissector returns, so references to them are unusable once the function has returned.

function	description
tvb:__tostring()	Gets a string representation of the `Tvb`
tvb:__call()	Creates a `TvbRange` from this `Tvb`. Same as `tvb:range()`
tvb:len()	Gets the number of bytes in the `Tvb`
tvb:offset()	Gets the raw offset (from the beginning of the source `Tvb`) of the `Tvb`
tvb:range([offset] [,length])	Creates a `TvbRange` from a subset of this `Tvb`

Tvb.new_real(bytearray, name)

This function has been replaced by ByteArray.tvb(bytearray, name).

tvb:len()

Description
- Gets the number of bytes in the Tvb
Returns
- number : The length of the Tvb

tvb:offset()

Description
- Gets the raw offset (from the beginning of the source Tvb) of the Tvb
Returns
- number : The raw offset of the Tvb

tvb:range([offset] [,length])

Description
- Creates a TvbRange from a subset of this Tvb.
Parameters
- offset (optional) : number
  - The position of the first byte to the subset. Defaults to 0.
  length (optional) : number
  - The byte length of the subset. Defaults to -1 (assume all remaining bytes).
Returns
- userdata : The new TvbRange

tvb:__tostring()

Description
- Gets a string representation of the Tvb. Cannot be directly called.
Returns
- string : The string representation
Example
- ```
   1  print( tostring(tvb) )
```

tvb:__call()

Description
- Creates a TvbRange from a subset of this Tvb. Same as tvb:range(). Cannot be directly called.
Returns
- userdata : The new TvbRange
Example
- ```
   1  local tvbr1 = tvb()
   2  local tvbr2 = tvb(0,10)
   3  local tvbr3 = tvb(2,5)
```

TvbRange

A range of bytes within a Tvb that is used to extract data. A TvbRange is created from tvb:__call() or tvb:range([offset] [,length]).

function	description
tvbrange:tvb()	Creates a new `Tvb` from this `TvbRange`
tvbrange:uint()	Gets a Big Endian (network order) unsigned integer from the `TvbRange`
tvbrange:le_uint()	Gets a Little Endian unsigned integer from the `TvbRange`
tvbrange:uint64()	Gets a Big Endian (network order) unsigned 64-bit integer from the `TvbRange`
tvbrange:le_uint64()	Gets a Little Endian unsigned 64-bit integer from the `TvbRange`
tvbrange:int()	Gets a Big Endian (network order) signed integer from the `TvbRange`
tvbrange:le_int()	Gets a Little Endian signed integer from the `TvbRange`
tvbrange:int64()	Gets a Big Endian (network order) signed 64-bit integer from the `TvbRange`
tvbrange:le_int64()	Gets a Little Endian signed 64-bit integer from the `TvbRange`
tvbrange:float()	Gets a Big Endian (network order) floating-point number from the `TvbRange`
tvbrange:le_float()	Gets a Little Endian floating-point number from the `TvbRange`
tvbrange:ipv4()	Gets an IPv4 Address from the `TvbRange`
tvbrange:le_ipv4()	Gets a Little Endian IPv4 Address from the `TvbRange`
tvbrange:ether()	Gets an Ethernet Address from the `TvbRange`
tvbrange:string()	Gets a string from the `TvbRange`
tvbrange:stringz()	Gets a zero-terminated string from the `TvbRange`
tvbrange:ustring()	Gets a UTF-16 (Big Endian) string from the `TvbRange`
tvbrange:ustringz()	Gets a zero-terminated UTF-16 (Big Endian) string from the `TvbRange`
tvbrange:le_ustring()	Gets a UTF-16 (Little Endian) string from the `TvbRange`
tvbrange:le_ustringz()	Gets a zero-terminated UTF-16 (Little Endian) string from the `TvbRange`
tvbrange:bytes()	Gets a ByteArray composed of the bytes in the `TvbRange`
tvbrange:bitfield([offset], [length])	Gets a bitfield from the `TvbRange`
tvbrange:len()	Gets the number of bytes in the `TvbRange`
tvbrange:offset()	Gets the raw offset of the `TvbRange`
tvbrange:__tostring()	Gets the string representation of the `TvbRange`

tvbrange:tvb()

Description
- Creates a new Tvb from this TvbRange
Returns
- userdata: the new Tvb

tvbrange:uint()

Description
- Gets a Big Endian (network order) unsigned integer from the TvbRange. The range must be 1, 2, 3 or 4 octets long.
Returns
- number: the unsigned integer value

tvbrange:le_uint()

Description
- Gets a Little Endian unsigned integer from the TvbRange. The range must be 1, 2, 3 or 4 octets long.
Returns
- number: the unsigned integer value

tvbrange:uint64()

Description
- Gets a Big Endian (network order) unsigned 64-bit integer from the TvbRange. The range must be 1-8 octets long.
Returns
- userdata : The unsigned integer value (a UInt64 object)

tvbrange:le_uint64()

Description
- Gets a Little Endian unsigned 64-bit integer from the TvbRange. The range must be 1-8 octets long.
Returns
- userdata : The unsigned integer value (a UInt64 object)

tvbrange:int()

Description
- Gets a Big Endian (network order) signed integer from the TvbRange. The range must be 1, 2 or 4 octets long.
Returns
- number : The signed integer value

tvbrange:le_int()

Description
- Gets a Little Endian signed integer from the TvbRange. The range must be 1, 2 or 4 octets long.
Returns
- number : The signed integer value

tvbrange:int64()

Description
- Gets a Big Endian (network order) signed 64-bit integer from the TvbRange. The range must be 1-8 octets long.
Returns
- userdata : The integer value (an Int64 object)

tvbrange:le_int64()

Description
- Gets a Little Endian signed 64-bit integer from the TvbRange. The range must be 1-8 octets long.
Returns
- userdata : The integer value (an Int64 object)

tvbrange:float()

Description
- Gets a Big Endian (network order) floating-point number from the TvbRange. The range must be 4 or 8 octets long.
Returns
- number : The floating-point value

tvbrange:le_float()

Description
- Gets a Little Endian floating-point number from the TvbRange. The range must be 4 or 8 octets long.
Returns
- number : The floating-point value

tvbrange:ipv4()

Description
- Gets an IPv4 Address from the TvbRange
Returns
- userdata : The IPv4 Address (an Address object)

tvbrange:le_ipv4()

Description
- Gets a Little Endian IPv4 Address from the TvbRange
Returns
- userdata : The IPv4 Address (an Address object)

tvbrange:ether()

Description
- Gets an Ethernet Address from the TvbRange. The range must be 6 bytes long.
Returns
- userdata : The Ethernet Address

tvbrange:string()

Description
- Gets a string from the TvbRange
Returns
- string : The string, containing all bytes in the TvbRange including all zeroes (e.g., "a\000bc\000")

tvbrange:stringz()

Description
- Gets a zero-terminated string from the TvbRange
Returns
- string : The string, containing all bytes in the TvbRange up to the first zero

tvbrange:ustring()

Description
- Gets a UTF-16 (Big Endian) string from the TvbRange
Returns
- string : The string, containing all bytes in the TvbRange including all zeroes (e.g., "a\000bc\000")

tvbrange:ustringz()

Description
- Gets a zero-terminated UTF-16 (Big Endian) string from the TvbRange
Returns
- string : The string, containing all bytes in the TvbRange up to the first zero

tvbrange:le_ustring()

Description
- Gets a UTF-16 (Little Endian) string from the TvbRange
Returns
- string : The string, containing all bytes in the TvbRange including all zeroes (e.g., "a\000bc\000")

tvbrange:le_ustringz()

Description
- Gets a zero-terminated UTF-16 (Little Endian) string from the TvbRange
Returns
- string : The string, containing all bytes in the TvbRange up to the first zero

tvbrange:bytes()

Description
- Gets a ByteArray composed of the bytes in the TvbRange
Returns
- userdata : The ByteArray

tvbrange:bitfield([offset], [length])

Description
- Gets a bitfield from the TvbRange
Parameters
- offset (optional) : number
  - The position of the first bit to the bitfield. Defaults to 0 (rightmost bit).
  length (optional) : number
  - The bit length of the subset. Defaults to 1.
Returns
- number : The bitfield integer value

tvbrange:len()

Description
- Gets the number of bytes in the TvbRange
Returns
- number : The byte length of the TvbRange

tvbrange:offset()

Description
- Gets the raw offset of the TvbRange
Returns
- number : The raw offset

tvbrange:__tostring()

Description
- Gets the hex string representation of the TvbRange. After 24 bytes, terminates the string with an ellipsis. (e.g., 001122334455667788990011223344556677889900112233...)

Int64

Int64 represents a 64-bit signed integer

Can only be created by tvbrange:int64() or tvbrange:le_int64()

UInt64

UInt64 represents a 64-bit unsigned integer

Can only be created by tvbrange:uint64() or tvbrange:le_uint64()

LuaAPI/Tvb