11.6. Functions For Handling Packet Data

11.6. Functions For Handling Packet Data
Prev	Chapter 11. Wireshark’s Lua API Reference Manual	Next

11.6.1. ByteArray

11.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.

11.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.

11.6.1.3. bytearray:__concat(first, second)

Concatenate two ByteArrays.

Arguments

first: First array.

second: Second array.

Returns

The new composite ByteArray.

11.6.1.4. bytearray:__eq(first, second)

Compares two ByteArray values.

Arguments

first: First array.

second: Second array.

11.6.1.5. bytearray:prepend(prepended)

Prepend a ByteArray to this ByteArray.

Arguments

prepended: ByteArray to be prepended.

11.6.1.6. bytearray:append(appended)

Append a ByteArray to this ByteArray.

Arguments

appended: ByteArray to be appended.

11.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

11.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].

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.6.1.18. bytearray:len()

Obtain the length of a ByteArray.

Returns

The length of the ByteArray.

11.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.

11.6.1.20. bytearray:base64_decode()

Obtain a Base64 decoded ByteArray.

Returns

The created ByteArray.

11.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.

11.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.

11.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.

11.6.1.24. bytearray:tvb(name)

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

11.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.

11.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.

11.6.2.1. tvb:__tostring()

Convert the bytes of a Tvb into a string. This is primarily useful for debugging purposes since the string will be truncated if it is too long.

Returns

The string.

11.6.2.2. tvb:reported_len()

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

Returns

The reported length of the Tvb.

11.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.

11.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.

11.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.

11.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.

11.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.

11.6.2.8. tvb:__call()

Equivalent to tvb:range(…)

11.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

11.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.

11.6.2.11. tvb:__eq()

Checks whether contents of two Tvbs are equal.

11.6.3. TvbRange

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

TvbRanges 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.

11.6.3.1. tvbrange:tvb()

Creates a new Tvb from a TvbRange.

11.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.

11.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

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.6.3.12. tvbrange:ipv4()

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

Returns

The IPv4 Address object.

11.6.3.13. tvbrange:le_ipv4()

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

Returns

The IPv4 Address object.

11.6.3.14. tvbrange:ipv6()

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

Returns

The IPv6 Address object.

11.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

11.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

11.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

11.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").

11.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").

11.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").

11.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.

11.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.

11.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.

11.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.

11.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.

11.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

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.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.

11.6.3.39. tvbrange:len()

Obtain the length of a TvbRange.

11.6.3.40. tvbrange:offset()

Obtain the offset in a TvbRange.

11.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.

11.6.3.42. tvbrange:__eq()

Checks whether the contents of two TvbRanges are equal.

11.6.3.43. tvbrange:__tostring()

Converts the TvbRange into a string. The string can be truncated, so this is primarily useful for debugging or in cases where truncation is preferred, e.g. "67:89:AB:…".

Returns

A Lua hex string of the TvbRange truncated to 24 bytes.

Prev	Up	Next
11.5. Obtaining Packet Information	Home	11.7. Adding Information To The Dissection Tree