13.6. Functions For Handling Packet Data
Prev | Chapter 13. Wireshark’s Lua API Reference Manual | Next

## 13.6. Functions For Handling Packet Data

### 13.6.1. ByteArray

#### 13.6.1.1. ByteArray.new([hexbytes], [separator])

Creates a new `ByteArray` object.

Starting in version 1.11.3, if the second argument is a boolean `true`, then the first argument is treated as a raw Lua string of bytes to use, instead of a hexadecimal string.

#### 13.6.1.2. Example

        local empty = ByteArray.new()
        local b1 = ByteArray.new("a1 b2 c3 d4")
        local b2 = ByteArray.new("112233")

##### Arguments

hexbytes (optional)
  A string consisting of hexadecimal bytes like "00 B1 A2" or "1a2b3c4d".

separator (optional)
  A string separator between hex bytes/words (default=" "), or if the boolean value `true` is used, then the first argument is treated as raw binary data

##### Returns

The new ByteArray object.

#### 13.6.1.3. bytearray:__concat(first, second)

Concatenate two `ByteArray`s.

##### Arguments

first
  First array.

second
  Second array.

##### Returns

The new composite `ByteArray`.

#### 13.6.1.4. bytearray:__eq(first, second)

Compares two ByteArray values.

##### Arguments

first
  First array.

second
  Second array.

#### 13.6.1.5. bytearray:prepend(prepended)

Prepend a `ByteArray` to this `ByteArray`.

##### Arguments

prepended
  `ByteArray` to be prepended.

#### 13.6.1.6. bytearray:append(appended)

Append a `ByteArray` to this `ByteArray`.

##### Arguments

appended
  `ByteArray` to be appended.

#### 13.6.1.7. bytearray:set_size(size)

Sets the size of a `ByteArray`, either truncating it or filling it with zeros.

##### Arguments

size
  New size of the array.

##### Errors

- ByteArray size must be non-negative

#### 13.6.1.8. bytearray:set_index(index, value)

Sets the value of an index of a `ByteArray`.

##### Arguments

index
  The position of the byte to be set.

value
  The char value to set [0-255].

#### 13.6.1.9. bytearray:get_index(index)

Get the value of a byte in a `ByteArray`.

##### Arguments

index
  The position of the byte to get.

##### Returns

The value [0-255] of the byte.

#### 13.6.1.10. bytearray:le_int([offset], [length])

Read a little endian encoded signed integer in a `ByteArray` beginning at given offset with given length.

Since: 4.2.0

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the integer. Default is -1, or the remaining bytes in the `ByteArray`.

##### Returns

The value of the little endian encoded signed integer beginning at given offset with given length.

#### 13.6.1.11. bytearray:le_int64([offset], [length])

Read a little endian encoded 64 bit signed integer in a `ByteArray` beginning at given offset with given length.

Since: 4.2.0

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the integer. Default is -1, or the remaining bytes in the `ByteArray`.

##### Returns

The value of the little endian encoded 64 bit signed integer as a `Int64` object beginning at given offset with given length.

#### 13.6.1.12. bytearray:le_uint([offset], [length])

Read a little endian encoded unsigned integer in a `ByteArray` beginning at given offset with given length.

Since: 4.2.0

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the integer. Default is -1, or the remaining bytes in the `ByteArray`.

##### Returns

The value of the little endian encoded unsigned integer beginning at given offset with given length.

#### 13.6.1.13. bytearray:le_uint64([offset], [length])

Read a little endian encoded 64 bit unsigned integer in a `ByteArray` beginning at given offset with given length.

Since: 4.2.0

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the integer. Default is -1, or the remaining bytes in the `ByteArray`.

##### Returns

The value of the little endian encoded 64 bit unsigned integer as a `UInt64` object beginning at given offset with given length.

#### 13.6.1.14. bytearray:int([offset], [length])

Read a big endian encoded signed integer in a `ByteArray` beginning at given offset with given length.

Since: 4.2.0

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the integer. Default is -1, or the remaining bytes in the `ByteArray`.

##### Returns

The value of the big endian encoded 32 bit signed integer beginning at given offset with given length.

#### 13.6.1.15. bytearray:int64([offset], [length])

Read a big endian encoded 64 bit signed integer in a `ByteArray` beginning at given offset with given length.

Since: 4.2.0

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the integer. Default is -1, or the remaining bytes in the `ByteArray`.

##### Returns

The value of the big endian encoded 64 bit signed integer as a `Int64` object beginning at given offset and given length.

#### 13.6.1.16. bytearray:uint([offset], [length])

Read a big endian encoded unsigned integer in a `ByteArray` beginning at given offset with given length.

Since: 4.2.0

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the integer. Default is -1, or the remaining bytes in the `ByteArray`.

##### Returns

The value of the big endian encoded 32 bit unsigned integer beginning at given offset with given length.

#### 13.6.1.17. bytearray:uint64([offset], [length])

Read a big endian encoded 64 bit unsigned integer in a `ByteArray` beginning at given offset with given length.

Since: 4.2.0

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the integer. Default is -1, or the remaining bytes in the `ByteArray`.

##### Returns

The value of the big endian encoded 64 bit unsigned integer as a `UInt64` object beginning at given offset with given length.

#### 13.6.1.18. bytearray:len()

Obtain the length of a `ByteArray`.

##### Returns

The length of the `ByteArray`.

#### 13.6.1.19. bytearray:subset(offset, length)

Obtain a segment of a `ByteArray`, as a new `ByteArray`.

##### Arguments

offset
  The position of the first byte (0=first).

length
  The length of the segment.

##### Returns

A `ByteArray` containing the requested segment.

#### 13.6.1.20. bytearray:base64_decode()

Obtain a Base64 decoded `ByteArray`.

##### Returns

The created `ByteArray`.

#### 13.6.1.21. bytearray:raw([offset], [length])

Obtain a Lua string of the binary bytes in a `ByteArray`.

##### Arguments

offset (optional)
  The position of the first byte (default=0/first).

length (optional)
  The length of the segment to get (default=all).

##### Returns

A Lua string of the binary bytes in the ByteArray.

#### 13.6.1.22. bytearray:tohex([lowercase], [separator])

Obtain a Lua string of the bytes in a `ByteArray` as hex-ascii, with given separator.

##### Arguments

lowercase (optional)
  True to use lower-case hex characters (default=false).

separator (optional)
  A string separator to insert between hex bytes (default=nil).

##### Returns

A hex-ascii string representation of the `ByteArray`.

#### 13.6.1.23. bytearray:__tostring()

Obtain a Lua string containing the bytes in a `ByteArray` so that it can be used in display filters (e.g. "01FE456789AB").

##### Returns

A hex-ascii string representation of the `ByteArray`.

#### 13.6.1.24. bytearray:tvb(name)

Creates a new `Tvb` from a `ByteArray`. The `Tvb` will be added to the current frame.

#### 13.6.1.25. Example

        function proto_foo.dissector(buf, pinfo, tree)
                -- Create a new tab named "My Tvb" and add some data to it
                local b = ByteArray.new("11223344")
                local tvb = ByteArray.tvb(b, "My Tvb")

                -- Create a tree item that, when clicked, automatically shows the tab we just created
                tree:add( tvb(1,2), "Foo" )
        end

##### Arguments

name
  The name to be given to the new data source.

##### Returns

The created `Tvb`.

#### 13.6.1.26. bytearray.length

Mode: Retrieve only.

The number of bytes in the array. Mirrors `ba:len()`.

### 13.6.2. Tvb

A `Tvb` 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.

To create a `TvbRange` the `Tvb` must be called with offset and length as optional arguments; the offset defaults to 0 and the length to `tvb:captured_len()`.

| Warning
Tvbs are usable only by the current listener or dissector call and are destroyed as soon as the listener or dissector returns, so references to them are unusable once the function has returned.

#### 13.6.2.1. tvb:__tostring()

Convert the bytes of a `Tvb` into a string of the form `Tvb: captured=<C> reported=<R> bytes=<hex>`. The hex preview is automatically truncated by `tvb_bytes_to_str` to a small number of bytes (currently 36) so the rendering stays useful in the debugger Variables view and in `print()` for large packets.

##### Returns

The string.

#### 13.6.2.2. tvb:reported_len()

Obtain the reported length (length on the network) of a `Tvb`.

##### Returns

The reported length of the `Tvb`.

#### 13.6.2.3. tvb:captured_len()

Obtain the captured length (amount saved in the capture process) of a `Tvb`.

##### Returns

The captured length of the `Tvb`.

#### 13.6.2.4. tvb:len()

Obtain the captured length (amount saved in the capture process) of a `Tvb`. Same as captured_len; kept only for backwards compatibility

##### Returns

The captured length of the `Tvb`.

#### 13.6.2.5. tvb:reported_length_remaining([offset])

Obtain the reported (not captured) length of packet data to end of a `Tvb` or 0 if the offset is beyond the end of the `Tvb`.

##### Arguments

offset (optional)
  The offset (in octets) from the beginning of the `Tvb`. Defaults to 0.

##### Returns

The remaining reported length of the `Tvb`.

#### 13.6.2.6. tvb:bytes([offset], [length])

Obtain a `ByteArray` from a `Tvb`.

##### Arguments

offset (optional)
  The offset (in octets) from the beginning of the `Tvb`. Defaults to 0.

length (optional)
  The length (in octets) of the range. Defaults to until the end of the `Tvb`.

##### Returns

The `ByteArray` object or nil.

#### 13.6.2.7. tvb:offset()

Returns the raw offset (from the beginning of the source `Tvb`) of a sub `Tvb`.

##### Returns

The raw offset of the `Tvb`.

#### 13.6.2.8. tvb:__call()

Equivalent to tvb:range(…​)

#### 13.6.2.9. tvb:range([offset], [length])

Creates a `TvbRange` from this `Tvb`.

##### Arguments

offset (optional)
  The offset (in octets) from the beginning of the `Tvb`. Defaults to 0.

length (optional)
  The length (in octets) of the range. Defaults to -1, which specifies the remaining bytes in the `Tvb`.

##### Returns

The TvbRange

#### 13.6.2.10. tvb:raw([offset], [length])

Obtain a Lua string of the binary bytes in a `Tvb`.

##### Arguments

offset (optional)
  The position of the first byte. Default is 0, or the first byte.

length (optional)
  The length of the segment to get. Default is -1, or the remaining bytes in the `Tvb`.

##### Returns

A Lua string of the binary bytes in the `Tvb`.

#### 13.6.2.11. tvb:__eq()

Checks whether contents of two `Tvb`s are equal.

#### 13.6.2.12. tvb.captured_length

Mode: Retrieve only.

The captured length of the Tvb (amount saved in the capture process). Mirrors `tvb:captured_len()`.

#### 13.6.2.13. tvb.reported_length

Mode: Retrieve only.

The reported length of the Tvb (length on the network). Mirrors `tvb:reported_len()`.

#### 13.6.2.14. tvb.raw_offset

Mode: Retrieve only.

The raw offset of this (sub) Tvb in its source Tvb. Mirrors `tvb:offset()`.

### 13.6.3. TvbRange

A `TvbRange` represents a usable range of a `Tvb` and is used to extract data from the `Tvb` that generated it.

`TvbRange`s are created by calling a `Tvb` (e.g. 'tvb(offset,length)'). A length of -1, which is the default, means to use the bytes up to the end of the `Tvb`. If the `TvbRange` span is outside the `Tvb`'s range the creation will cause a runtime error.

#### 13.6.3.1. tvbrange:tvb()

Creates a new `Tvb` from a `TvbRange`.

#### 13.6.3.2. tvbrange:uint()

Get a Big Endian (network order) unsigned integer from a `TvbRange`. The range must be 1-4 octets long.

##### Returns

The unsigned integer value.

#### 13.6.3.3. tvbrange:le_uint()

Get a Little Endian unsigned integer from a `TvbRange`. The range must be 1-4 octets long.

##### Returns

The unsigned integer value

#### 13.6.3.4. tvbrange:uint64()

Get a Big Endian (network order) unsigned 64 bit integer from a `TvbRange`, as a `UInt64` object. The range must be 1-8 octets long.

##### Returns

The `UInt64` object.

#### 13.6.3.5. tvbrange:le_uint64()

Get a Little Endian unsigned 64 bit integer from a `TvbRange`, as a `UInt64` object. The range must be 1-8 octets long.

##### Returns

The `UInt64` object.

#### 13.6.3.6. tvbrange:int()

Get a Big Endian (network order) signed integer from a `TvbRange`. The range must be 1-4 octets long.

##### Returns

The signed integer value.

#### 13.6.3.7. tvbrange:le_int()

Get a Little Endian signed integer from a `TvbRange`. The range must be 1-4 octets long.

##### Returns

The signed integer value.

#### 13.6.3.8. tvbrange:int64()

Get a Big Endian (network order) signed 64 bit integer from a `TvbRange`, as an `Int64` object. The range must be 1-8 octets long.

##### Returns

The `Int64` object.

#### 13.6.3.9. tvbrange:le_int64()

Get a Little Endian signed 64 bit integer from a `TvbRange`, as an `Int64` object. The range must be 1-8 octets long.

##### Returns

The `Int64` object.

#### 13.6.3.10. tvbrange:float()

Get a Big Endian (network order) floating point number from a `TvbRange`. The range must be 4 or 8 octets long.

##### Returns

The floating point value.

#### 13.6.3.11. tvbrange:le_float()

Get a Little Endian floating point number from a `TvbRange`. The range must be 4 or 8 octets long.

##### Returns

The floating point value.

#### 13.6.3.12. tvbrange:ipv4()

Get an IPv4 Address from a `TvbRange`, as an `Address` object.

##### Returns

The IPv4 `Address` object.

#### 13.6.3.13. tvbrange:le_ipv4()

Get an Little Endian IPv4 Address from a `TvbRange`, as an `Address` object.

##### Returns

The IPv4 `Address` object.

#### 13.6.3.14. tvbrange:ipv6()

Get an IPv6 Address from a `TvbRange`, as an `Address` object.

##### Returns

The IPv6 `Address` object.

#### 13.6.3.15. tvbrange:ether()

Get an Ethernet Address from a `TvbRange`, as an `Address` object.

##### Returns

The Ethernet `Address` object.

##### Errors

- The range must be 6 bytes long

#### 13.6.3.16. tvbrange:nstime([encoding])

Obtain a time_t structure from a `TvbRange`, as an `NSTime` object.

##### Arguments

encoding (optional)
  An optional ENC_* encoding value to use

##### Returns

The `NSTime` object and number of bytes used, or nil on failure.

##### Errors

- The range must be 4 or 8 bytes long

#### 13.6.3.17. tvbrange:le_nstime()

Obtain a nstime from a `TvbRange`, as an `NSTime` object.

##### Returns

The `NSTime` object.

##### Errors

- The range must be 4 or 8 bytes long

#### 13.6.3.18. tvbrange:string([encoding])

Obtain a string from a `TvbRange`.

##### Arguments

encoding (optional)
  The encoding to use. Defaults to ENC_ASCII.

##### Returns

A string containing all bytes in the `TvbRange` including all zeroes (e.g., "a\000bc\000").

#### 13.6.3.19. tvbrange:ustring()

Obtain a Big Endian (network order) UTF-16 encoded string from a `TvbRange`.

##### Returns

A string containing all bytes in the `TvbRange` including all zeroes (e.g., "a\000bc\000").

#### 13.6.3.20. tvbrange:le_ustring()

Obtain a Little Endian UTF-16 encoded string from a `TvbRange`.

##### Returns

A string containing all bytes in the `TvbRange` including all zeroes (e.g., "a\000bc\000").

#### 13.6.3.21. tvbrange:stringz([encoding])

Obtain a zero terminated string from a `TvbRange`.

##### Arguments

encoding (optional)
  The encoding to use. Defaults to ENC_ASCII.

##### Returns

The string containing all bytes in the `TvbRange` up to the first terminating zero, and the length of that string.

#### 13.6.3.22. tvbrange:strsize([encoding])

Find the size of a zero terminated string from a `TvbRange`. The size of the string includes the terminating zero.

##### Arguments

encoding (optional)
  The encoding to use. Defaults to ENC_ASCII.

##### Returns

Length of the zero terminated string.

#### 13.6.3.23. tvbrange:ustringz()

Obtain a Big Endian (network order) UTF-16 encoded zero terminated string from a `TvbRange`.

##### Returns

Two return values: the zero terminated string, and the length.

#### 13.6.3.24. tvbrange:le_ustringz()

Obtain a Little Endian UTF-16 encoded zero terminated string from a TvbRange

##### Returns

Two return values: the zero terminated string, and the length.

#### 13.6.3.25. tvbrange:bytes([encoding])

Obtain a `ByteArray` from a `TvbRange`.

Starting in 1.11.4, this function also takes an optional `encoding` argument, which can be set to `ENC_STR_HEX` to decode a hex-string from the `TvbRange` into the returned `ByteArray`. The `encoding` can be bitwise-or’ed with one or more separator encodings, such as `ENC_SEP_COLON`, to allow separators to occur between each pair of hex characters.

The return value also now returns the number of bytes used as a second return value.

On failure or error, nil is returned for both return values.

| Note
The encoding type of the hex string should also be set, for example `ENC_ASCII` or `ENC_UTF_8`, along with `ENC_STR_HEX`.

##### Arguments

encoding (optional)
  An optional ENC_* encoding value to use

##### Returns

The `ByteArray` object or nil, and number of bytes consumed or nil.

#### 13.6.3.26. tvbrange:bitfield([position], [length])

Get a bitfield from a `TvbRange`.

##### Arguments

position (optional)
  The bit offset (MSB 0 bit numbering) from the beginning of the `TvbRange`. Defaults to 0.

length (optional)
  The length in bits of the field. Defaults to 1.

##### Returns

The bitfield value

#### 13.6.3.27. tvbrange:range([offset], [length])

Creates a sub-`TvbRange` from this `TvbRange`.

##### Arguments

offset (optional)
  The offset (in octets) from the beginning of the `TvbRange`. Defaults to 0.

length (optional)
  The length (in octets) of the range. Defaults to until the end of the `TvbRange`.

##### Returns

The `TvbRange`.

#### 13.6.3.28. tvbrange:uncompress_zlib(name)

Given a `TvbRange` containing zlib compressed data, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.29. tvbrange:uncompress(name)

Given a `TvbRange` containing zlib compressed data, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Deprecated; use tvbrange:uncompress_zlib() instead.

##### Arguments

name
  The name to be given to the new data-source.

#### 13.6.3.30. tvbrange:uncompress_brotli(name)

Given a `TvbRange` containing Brotli compressed data, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.31. tvbrange:uncompress_hpack_huff(name)

Given a `TvbRange` containing data compressed using the Huffman encoding in HTTP/2 HPACK and HTTP/3 QPACK, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.32. tvbrange:uncompress_lz77(name)

Given a `TvbRange` containing Microsoft Plain LZ77 compressed data, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.33. tvbrange:uncompress_lz77huff(name)

Given a `TvbRange` containing Microsoft LZ77+Huffman compressed data, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.34. tvbrange:uncompress_lznt1(name)

Given a `TvbRange` containing Microsoft LZNT1 compressed data, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.35. tvbrange:uncompress_snappy(name)

Given a `TvbRange` containing Snappy compressed data, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.36. tvbrange:uncompress_zstd(name)

Given a `TvbRange` containing Zstandard compressed data, decompresses the data and returns a new `TvbRange` containing the uncompressed data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.37. tvbrange:decode_base64(name)

Given a `TvbRange` containing Base64 encoded data, return a new `TvbRange` containing the decoded data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.38. tvbrange:decode_base64url(name)

Given a `TvbRange` containing base64url encoded data, return a new `TvbRange` containing the decoded data. Since: 4.3.0

##### Arguments

name
  The name to be given to the new data-source.

##### Returns

The `TvbRange`.

#### 13.6.3.39. tvbrange:len()

Obtain the length of a `TvbRange`.

#### 13.6.3.40. tvbrange:offset()

Obtain the offset in a `TvbRange`.

#### 13.6.3.41. tvbrange:raw([offset], [length])

Obtain a Lua string of the binary bytes in a `TvbRange`.

##### Arguments

offset (optional)
  The position of the first byte within the range. Default is 0, or first byte.

length (optional)
  The length of the segment to get. Default is -1, or the remaining bytes in the range.

##### Returns

A Lua string of the binary bytes in the `TvbRange`.

#### 13.6.3.42. tvbrange:__eq()

Checks whether the contents of two `TvbRange`s are equal.

#### 13.6.3.43. tvbrange:__tostring()

Converts the `TvbRange` into a string of the form `TvbRange: offset=<O> length=<L> bytes=<hex>`. The hex preview is truncated by `tvb_bytes_to_str` to a small number of bytes so the rendering stays useful in the debugger Variables view and in `print()` for large ranges. Empty ranges render as `TvbRange: offset=<O> length=0 (empty)`.

##### Returns

A short label including the offset, length, and a truncated hex preview.

#### 13.6.3.44. tvbrange.length

Mode: Retrieve only.

The length (in bytes) of the range. Mirrors `range:len()`.

#### 13.6.3.45. tvbrange.position

Mode: Retrieve only.

The offset within the parent Tvb at which the range starts. Mirrors `range:offset()`.

Prev | Up | Next
13.5. Obtaining Packet Information | Home | 13.7. Adding Information To The Dissection Tree