11.12. Functions for handling packet data
Prev | Chapter 11. Lua Support in Wireshark | Next

## 11.12. Functions for handling packet data

### 11.12.1. ByteArray

#### 11.12.1.1. ByteArray.new([hexbytes])

Creates a ByteArray Object

##### 11.12.1.1.1. Arguments

hexbytes (optional)

  A string consisting of hexadecimal bytes like "00 B1 A2" or "1a2b3c4d"

##### 11.12.1.1.2. Returns

The new ByteArray object.

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

Concatenate two ByteArrays

##### 11.12.1.2.1. Arguments

first

  First array

second

  Second array

##### 11.12.1.2.2. Returns

The new composite ByteArray.

##### 11.12.1.2.3. Errors

- Both arguments must be ByteArrays

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

Prepend a ByteArray to this ByteArray

##### 11.12.1.3.1. Arguments

prepended

  Array to be prepended

##### 11.12.1.3.2. Errors

- Both arguments must be ByteArrays

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

Append a ByteArray to this ByteArray

##### 11.12.1.4.1. Arguments

appended

  Array to be appended

##### 11.12.1.4.2. Errors

- Both arguments must be ByteArrays

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

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

##### 11.12.1.5.1. Arguments

size

  New size of the array

##### 11.12.1.5.2. Errors

- ByteArray size must be non-negative

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

Sets the value of an index of a ByteArray.

##### 11.12.1.6.1. Arguments

index

  The position of the byte to be set

value

  The char value to set [0-255]

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

Get the value of a byte in a ByteArray

##### 11.12.1.7.1. Arguments

index

  The position of the byte to get

##### 11.12.1.7.2. Returns

The value [0-255] of the byte.

#### 11.12.1.8. bytearray:len()

Obtain the length of a ByteArray

##### 11.12.1.8.1. Returns

The length of the ByteArray.

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

Obtain a segment of a ByteArray

##### 11.12.1.9.1. Arguments

offset

  The position of the first byte

length

  The length of the segment

##### 11.12.1.9.2. Returns

A ByteArray contaning the requested segment.

A string contaning a representaion of the ByteArray.

### 11.12.2. Int

Int64 represents a 64 bit integer. Lua uses one single number representation which can be chosen at compile time and since it is often set to IEEE 754 double precision floating point, we cannot store a 64 bit integer with full precision. For details, see: http://lua-users.org/wiki/FloatingPoint

### 11.12.3. 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. 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. 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() )

#### 11.12.3.1. ByteArray.tvb(name)

Creates a new Tvb from a bytearray (it gets added to the current frame too)

##### 11.12.3.1.1. Arguments

name

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

##### 11.12.3.1.2. Returns

The created Tvb.

#### 11.12.3.2. TvbRange.tvb(range)

Creates a (sub)Tvb from using a TvbRange

##### 11.12.3.2.1. Arguments

range

  The TvbRange from which to create the new Tvb.

#### 11.12.3.3. tvb:__tostring()

Convert the bytes of a Tvb into a string, to be used for debugging purposes as '...' will be appended in case the string is too long.

##### 11.12.3.3.1. Returns

The string.

#### 11.12.3.4. tvb:reported_len()

Obtain the reported length of a TVB

##### 11.12.3.4.1. Returns

The length of the Tvb.

#### 11.12.3.5. tvb:len()

Obtain the length of a TVB

##### 11.12.3.5.1. Returns

The length of the Tvb.

#### 11.12.3.6. tvb:reported_length_remaining()

Obtain the reported length of packet data to end of a TVB or -1 if the offset is beyond the end of the TVB

##### 11.12.3.6.1. Returns

The length of the Tvb.

#### 11.12.3.7. tvb:offset()

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

##### 11.12.3.7.1. Returns

The raw offset of the Tvb.

#### 11.12.3.8. tvb:__call()

Equivalent to tvb:range(...)

#### 11.12.3.9. wslua:__concat()

Concatenate two objects to a string

### 11.12.4. TvbRange

A TvbRange represents an 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.12.4.1. tvb:range([offset], [length])

Creates a tvbr from this Tvb. This is used also as the Tvb:__call() metamethod.

##### 11.12.4.1.1. Arguments

offset (optional)

  The offset (in octets) from the begining of the Tvb. Defaults to 0.

length (optional)

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

##### 11.12.4.1.2. Returns

The TvbRange

#### 11.12.4.2. tvbrange:uint()

Get a Big Endian (network order) unsigned integer from a TvbRange. The range must be 1, 2, 3 or 4 octets long.

##### 11.12.4.2.1. Returns

The unsigned integer value

#### 11.12.4.3. tvbrange:le_uint()

Get a Little Endian unsigned integer from a TvbRange. The range must be 1, 2, 3 or 4 octets long.

##### 11.12.4.3.1. Returns

The unsigned integer value

#### 11.12.4.4. tvbrange:uint64()

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

#### 11.12.4.5. tvbrange:le_uint64()

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

#### 11.12.4.6. tvbrange:int()

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

##### 11.12.4.6.1. Returns

The signed integer value

#### 11.12.4.7. tvbrange:le_int()

Get a Little Endian signed integer from a TvbRange. The range must be 1, 2 or 4 octets long.

##### 11.12.4.7.1. Returns

The signed integer value

#### 11.12.4.8. tvbrange:int64()

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

#### 11.12.4.9. tvbrange:le_int64()

Get a Little Endian signed 64 bit integer from a TvbRange. The range must be 1-8 octets long.

#### 11.12.4.10. tvbrange:float()

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

##### 11.12.4.10.1. Returns

The floating point value

#### 11.12.4.11. tvbrange:le_float()

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

##### 11.12.4.11.1. Returns

The floating point value

#### 11.12.4.12. tvbrange:ipv4()

Get an IPv4 Address from a TvbRange.

##### 11.12.4.12.1. Returns

The IPv4 Address

#### 11.12.4.13. tvbrange:le_ipv4()

Get an Little Endian IPv4 Address from a TvbRange.

##### 11.12.4.13.1. Returns

The IPv4 Address

#### 11.12.4.14. tvbrange:ether()

Get an Ethernet Address from a TvbRange.

##### 11.12.4.14.1. Returns

The Ethernet Address

##### 11.12.4.14.2. Errors

- The range must be 6 bytes long

#### 11.12.4.15. tvbrange:nstime()

Obtain a nstime from a TvbRange

##### 11.12.4.15.1. Returns

The NSTime

##### 11.12.4.15.2. Errors

- The range must be 4 or 8 bytes long

#### 11.12.4.16. tvbrange:le_nstime()

Obtain a nstime from a TvbRange

##### 11.12.4.16.1. Returns

The NSTime

##### 11.12.4.16.2. Errors

- The range must be 4 or 8 bytes long

#### 11.12.4.17. tvbrange:string()

Obtain a string from a TvbRange

##### 11.12.4.17.1. Returns

The string

#### 11.12.4.18. tvbrange:ustring()

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

##### 11.12.4.18.1. Returns

The string

#### 11.12.4.19. tvbrange:le_ustring()

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

##### 11.12.4.19.1. Returns

The string

#### 11.12.4.20. tvbrange:stringz()

Obtain a zero terminated string from a TvbRange

##### 11.12.4.20.1. Returns

The zero terminated string

#### 11.12.4.21. tvbrange:ustringz()

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

##### 11.12.4.21.1. Returns

The zero terminated string, the length found in tvbr

#### 11.12.4.22. tvbrange:le_ustringz()

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

##### 11.12.4.22.1. Returns

The zero terminated string, the length found in tvbr

#### 11.12.4.23. tvbrange:bytes()

Obtain a ByteArray

##### 11.12.4.23.1. Returns

The ByteArray

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

Get a bitfield from a TvbRange.

##### 11.12.4.24.1. Arguments

position (optional)

  The bit offset from the begining of the TvbRange. Defaults to 0.

length (optional)

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

##### 11.12.4.24.2. Returns

The bitfield value

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

Creates a sub-TvbRange from this TvbRange. This is used also as the TvbRange:__call() metamethod.

##### 11.12.4.25.1. Arguments

offset (optional)

  The offset (in octets) from the begining of the TvbRange. Defaults to 0.

length (optional)

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

##### 11.12.4.25.2. Returns

The TvbRange

#### 11.12.4.26. tvbrange:len()

Obtain the length of a TvbRange

#### 11.12.4.27. tvbrange:offset()

Obtain the offset in a TvbRange

#### 11.12.4.28. tvbrange:__tostring()

Converts the TvbRange into a string. As the string gets truncated you should use this only for debugging purposes or if what you want is to have a truncated string in the format 67:89:AB:...

### 11.12.5. UInt

UInt64 represents a 64 bit unsigned integer.

Prev | Up | Next
11.11. Adding information to the dissection tree | Home | 11.13. Utility Functions