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

11.8. Functions For Handling Packet Data

11.8.1. ByteArray

11.8.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.8.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.8.1.3. bytearray:__concat(first, second)

Concatenate two ByteArrays.

Arguments
first
First array.
second
Second array.
Returns

The new composite ByteArray.

11.8.1.4. bytearray:__eq(first, second)

Compares two ByteArray values.

Since: 1.11.4

Arguments
first
First array.
second
Second array.

11.8.1.5. bytearray:prepend(prepended)

Prepend a ByteArray to this ByteArray.

Arguments
prepended
ByteArray to be prepended.

11.8.1.6. bytearray:append(appended)

Append a ByteArray to this ByteArray.

Arguments
appended
ByteArray to be appended.

11.8.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.8.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.8.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.8.1.10. bytearray:len()

Obtain the length of a ByteArray.

Returns

The length of the ByteArray.

11.8.1.11. 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.8.1.12. bytearray:base64_decode()

Obtain a Base64 decoded ByteArray.

Since: 1.11.3

Returns

The created ByteArray.

11.8.1.13. bytearray:raw([offset], [length])

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

Since: 1.11.3

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.8.1.14. bytearray:tohex([lowercase], [separator])

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

Since: 1.11.3

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.8.1.15. 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.8.1.16. bytearray:tvb(name)

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

11.8.1.17. 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.8.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:len().

[Warning]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.8.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.8.2.2. tvb:reported_len()

Obtain the reported (not captured) length of a Tvb.

Returns

The reported length of the Tvb.

11.8.2.3. tvb:len()

Obtain the actual (captured) length of a Tvb.

Returns

The captured length of the Tvb.

11.8.2.4. tvb:reported_length_remaining()

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

Returns

The captured length of the Tvb.

11.8.2.5. tvb:bytes([offset], [length])

Obtain a ByteArray from a Tvb.

Since: 1.99.8

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.8.2.6. 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.8.2.7. tvb:__call()

Equivalent to tvb:range(…​)

11.8.2.8. 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.8.2.9. tvb:raw([offset], [length])

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

Since: 1.11.3

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.8.2.10. tvb:__eq()

Checks whether contents of two Tvbs are equal.

Since: 1.99.8

11.8.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)'). If the TvbRange span is outside the Tvb's range the creation will cause a runtime error.

11.8.3.1. tvbrange:tvb()

Creates a new Tvb from a TvbRange.

11.8.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.8.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.8.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.8.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.8.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.8.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.8.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.8.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.8.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.8.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.8.3.12. tvbrange:ipv4()

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

Returns

The IPv4 Address object.

11.8.3.13. tvbrange:le_ipv4()

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

Returns

The IPv4 Address object.

11.8.3.14. tvbrange:ipv6()

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

Returns

The IPv6 Address object.

11.8.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.8.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.8.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.8.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.8.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.8.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.8.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.8.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.

Since: 1.11.3

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

Length of the zero terminated string.

11.8.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.8.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.8.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]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.8.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.8.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.8.3.28. tvbrange:uncompress(name)

Obtain an uncompressed TvbRange from a TvbRange

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

The TvbRange.

11.8.3.29. tvbrange:len()

Obtain the length of a TvbRange.

11.8.3.30. tvbrange:offset()

Obtain the offset in a TvbRange.

11.8.3.31. tvbrange:raw([offset], [length])

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

Since: 1.11.3

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.8.3.32. tvbrange:__eq()

Checks whether the contents of two TvbRanges are equal.

Since: 1.99.8

11.8.3.33. 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.7. Adding Information To The Dissection Tree Home 11.9. Custom File Format Reading And Writing