11.14. Binary encode/decode support

The Struct class offers basic facilities to convert Lua values to and from C-style structs in binary Lua strings. This is based on Roberto Ierusalimschy’s Lua struct library found in http://www.inf.puc-rio.br/~roberto/struct/, with some minor modifications as follows:

All but the first of those changes are based on an email from Flemming Madsen, on the lua-users mailing list, which can be found here.

The main functions are Struct.pack, which packs multiple Lua values into a struct-like Lua binary string; and Struct.unpack, which unpacks multiple Lua values from a given struct-like Lua binary string. There are some additional helper functions available as well.

All functions in the Struct library are called as static member functions, not object methods, so they are invoked as "Struct.pack(…​)" instead of "object:pack(…​)".

The fist argument to several of the Struct functions is a format string, which describes the layout of the structure. The format string is a sequence of conversion elements, which respect the current endianness and the current alignment requirements. Initially, the current endianness is the machine’s native endianness and the current alignment requirement is 1 (meaning no alignment at all). You can change these settings with appropriate directives in the format string.

The supported elements in the format string are as follows:

[Important]Important

Using i, I, h, H, l, L, f, and T is strongly discouraged, as those sizes are system-dependent. Use the explicitly sized variants instead, such as i4 or E.

Unpacking of i/I is done to a Lua number, a double-precision floating point, so unpacking a 64-bit field (i8/I8) will lose precision. Use e/E to unpack into a Wireshark Int64/UInt64 object instead.

[Note]Note

Lua 5.3 and later provides several built-in functions for struct unpacking and packing: string.pack, string.packsize, and string.unpack. You can use those as well, but note that the format string conversion elements are slightly different, and they do not support the Wireshark Int64/UInt64 objects.

11.14.1. Struct

11.14.1.1. Struct.pack(format, value)

Returns a string containing the values arg1, arg2, etc. packed/encoded according to the format string.

Arguments
format
The format string
value
One or more Lua value(s) to encode, based on the given format.
Returns

The packed binary Lua string, plus any positions due to '=' being used in format.

11.14.1.2. Struct.unpack(format, struct, [begin])

Unpacks/decodes multiple Lua values from a given struct-like binary Lua string. The number of returned values depends on the format given, plus an additional value of the position where it stopped reading is returned.

Arguments
format
The format string
struct
The binary Lua string to unpack
begin (optional)
The position to begin reading from (default=1)
Returns

One or more values based on format, plus the position it stopped unpacking.

11.14.1.3. Struct.size(format)

Returns the length of a binary string that would be consumed/handled by the given format string.

Arguments
format
The format string
Returns

The size number

11.14.1.4. Struct.values(format)

Returns the number of Lua values contained in the given format string. This will be the number of returned values from a call to Struct.unpack() not including the extra return value of offset position. (i.e., Struct.values() does not count that extra return value) This will also be the number of arguments Struct.pack() expects, not including the format string argument.

Arguments
format
The format string
Returns

The number of values

11.14.1.5. Struct.tohex(bytestring, [lowercase], [separator])

Converts the passed-in binary string to a hex-ascii string.

Arguments
bytestring
A Lua string consisting of binary bytes
lowercase (optional)
True to use lower-case hex characters (default=false).
separator (optional)
A string separator to insert between hex bytes (default=nil).
Returns

The Lua hex-ascii string

11.14.1.6. Struct.fromhex(hexbytes, [separator])

Converts the passed-in hex-ascii string to a binary string.

Arguments
hexbytes
A string consisting of hexadecimal bytes like "00 B1 A2" or "1a2b3c4d"
separator (optional)
A string separator between hex bytes/words (default none).
Returns

The Lua binary string